IT project: how to write good specifications

In any IT project, the specifications can become your best ally... or your worst enemy. If they are vague or too generic, they open the door to abuses. If they are too technical, they lose sight of the business. If they are too rigid, they stifle agility. Discover how to write specifications that are structured, readable, and usable by both technical teams and business stakeholders.

You are launching a new IT project. The atmosphere is positive, ideas are flowing: an internal application that finally streamlines workflows, a website that increases conversion rates, a CRM that speaks the same language as your sales and marketing teams, more reliable cloud hosting...

Then comes the moment of specifications (CDC). In the public sector, these are referred to as CCTP (Cahier des Clauses Techniques Particulières, or Specific Technical Specifications). In many private organisations, the document is called CCFT (Cahier des Clauses Fonctionnelles et Techniques, or Functional and Technical Specifications).

The acronyms change, but the function remains the same: to provide a common language for the project management (PM), which expresses the need, and to the project management (PM), which designs and implements the solution.

In concrete terms, the specifications play a threefold role: 

• it translates the business requirement into concrete requirements,
• it structures the contractual obligations,
• it serves as legal reference in the event of a dispute.

If it lacks precision, it leaves room for cost overruns, delays and fragile IT contracts. Conversely, if it remains clear, consistent and legally sound, it becomes a management tool, protects the customer-supplier relationship and supports your decisions.

Good news: you can write a set of specifications at the same time. clear, practical and reassuring, without overwhelming everyone with technical jargon or indigestible administrative language.

Better still, you can design it in such a way that your teams will actually want to read it... and comply with it.

Timeline of an IT project

Before writing: define the need and the market

From vague need to formalised need

The fundamental mistake, even made by experienced teams, is to dive headfirst into the technical solution. For example: «We need a new ERP system,» «We want’Generative AI » or «we need to redo the entire website». However, good specifications act as a strategic filter.

First of all, set a clear, measurable, time-bound objective. Before describing an interface or feature, the CDC sets a business ambition.

In practice, A single sentence should summarise the need, with a clear, measurable and time-bound objective..

So it's no longer a question of announcing, «We want a new AI-based multilingual system,» but rather saying, «We need to reduce the time it takes to publish multilingual content by 40% before Q3, without sacrificing quality.».

This nuance changes everything. On the one hand, it provides a compass for future decisions. On the other hand, when the budget is under pressure, this sentence will help to distinguish between what is essential and what is superfluous.

A clear scope, including what you will not do

Once the objective has been clarified, translate this need into functional requirements : what users need to be able to do, see, and decide. Above all, resist the temptation to impose the solution immediately («we absolutely need this tool»).

First the intention, then the technology.

Then, you set the boundaries of the project. Define what the project includes… and above all what he excludes. In reality, the power of a well-formulated non-function often surprises project managers.

In fact, defining what the project will not do is often more powerful than listing what it will do. Setting exclusions in stone (the « out of scope »), you defuse functional abuses in advance, the famous « scope creep» which, according to the PMI, affects more than half of large-scale projects.

For example: «The system does not support automatic translation of complex PDFs in phase 1.»

This simple sentence can save weeks of discussions with the IT department or business management.

The constraints triangle: budget, deadlines, scope

Next, draw your stress triangle :

• the budget : set a budget range
• deadlines : create a macro-plan (major phases, a few milestones)
• the perimeter : specify everything that needs to be done (deliverables, tasks, features, etc.)

There is no need to aim for absolute precision from the outset. An order of magnitude is sufficient to avoid illusions.

Then, only afterwards, descend towards the technical constraints : cloud or on-premise choice, interoperability with your existing IT system, security, volume, data reversibility, etc.

What specifications according to your project? ?

Not all specifications tell the same story. In other words, you do not emphasise the same sections depending on whether you are ordering a specific development, choosing a software package or requesting project management support.

▶ For bespoke development

Focus on diagnosing the existing situation, business processes, data handled, workflows, and quality requirements.

▶ Do you want to choose off-the-shelf software or an ERP system?

You mainly describe your business needs, priorities, integration constraints and selection criteria. The specifications then form the basis of a detailed questionnaire that each publisher completes. You can then compare the offers, weigh them up and draw up a shortlist based on objective criteria rather than the most impressive sales pitch.

▶ You must connect several tools

You place greater emphasis on interfaces and flows. Exchange formats, frequency, volume, data recovery and error management become central elements of the document.

▶ For a website or web platform

You emphasise user experience, perceived performance, account security, accessibility, search engine optimisation, scalability and hosting requirements.

▶ Are you seeking a project management support partner?

Your objective is to find a partner to help you frame and manage the project. You describe your partner's scope of involvement: helping to define requirements, organising workshops, drafting specifications, reviewing bids, facilitating acceptance testing, and managing change.

Please note: for complex projects (ERP, IS overhaul), expect to draw up several specifications: software supply, integration, specific developments, migration, IT outsourcing, TMA, etc.

The players: project owner, project manager, sponsor, steering committee

Good specifications do not just describe a system, they also describe a set of actors.

Client side, project management (Project Owner) formulates requirements, verifies the suitability of proposed solutions, organises workshops, validates deliverables, manages the project and acceptance testing, and drives change. The project management office often operates on two levels: a Strategic project owner, close to management, which sets the mandate and broad guidelines, and an operational project owner, who writes and leads the day-to-day work.

On the supplier side, project management (MOE) designs solutions, implements the chosen solution, provides technical advice to the project owner and commits to resources and deadlines.

Above this duo, the sponsor acts as the project sponsor. He or she takes the project to the highest level of the organisation, legitimises the objectives, arbitrates sensitive issues and protects the budget.

And finally.., the steering committee (Co-pilot) brings together sponsors, business representatives, IT managers, and sometimes purchasing managers, and makes structural decisions at key milestones.

Logical conclusion: the clearer the specifications are in describing this governance, the more the project will remain on track.

The structure of specifications that inspires confidence

An effective specification follows a simple logic: it first explains why you act, then what you expect, then how you plan to go there, with whom and dunder what conditions.

Here is a structure that you can use as is and adapt to your context.

1. Context and objectives: set the scene

To begin with, describe the present system : its strengths, limitations, and irritants. Describe what will happen if nothing changes: delays, compliance risks (GDPR, etc.), lost opportunities, excessive dependence on a supplier, etc.

Next, you explain the business and user objectives. Ideally, make them measurable and prioritised according to logic. Must / Should / Could / Won't (mandatory / desirable / nice-to-have / out of scope).

Finally, add your indicators of success : KPIs (key performance indicators) and the acceptance criteria.

Example: «95 % of translated content must be aligned with the glossary within 48 hours.»

Do your KPIs really help you make decisions when requests pile up? If the answer is unclear, simplify. Three clear indicators are better than an illegible dashboard.

 «The day we put a single KPI on the table: the average time between request and online publication. Since then, decisions have become much simpler,» Damien, digital project manager in industry.

2. Scope and deliverables: stating what is included

First, describe the functional scope : what users will be able to do and what they will not do. Use action verbs and draw inspiration from everyday life: «create content», «request a translation», «approve a campaign», etc.

Then, detail the technical constraints Major: target architecture, key integrations (API, SSO, DAM, PIM, CRM), and security standards to be met.

Afterwards, Finally, list the expected deliverables : software, documentation, test suites, training materials, mock-ups, deployment plan, additional services (third-party application maintenance, IT outsourcing, acceptance testing, migration, etc.).…

And finally.., Put in writing what is included in the contract and what will remain outside its scope. (or will be the subject of another contract).

To summarise, clearly explain what the CDC must do. describe :

• expected services (hosting, TMA, IT outsourcing, development, SaaS integration, etc.)
• deliverables (software, documentation, test plans, training materials)
• the obligations of the service provider (responsiveness, service continuity, security, reporting, support)

In summary, the reader should understand within a few pages where does the marketing promise end and the contractual commitment begin?.

The framework is becoming clearer. You have set the scene and laid down the rules of the game. Now let's take a look at what users are experiencing.

3. User journeys and functional requirements: describing usage before technology

Your CDC must address project managers, technical teams, purchasers and sometimes lawyers. The only way to speak to everyone is to describe customs.

Use the user journey and user stories to avoid grey areas.

Start with your personas :

• the publisher who publishes,
• the translator who processes a queue of content,
• the project manager who orchestrates,
• the IT department that keeps things secure.

Describe a typical day with their irritants and expectations.

Then switch to user stories. A user story describes a functional requirement as seen by the user, in the format: «As a... I want... in order to...». Associate each story from acceptance criteria.

For example:

Story
«As an editorial project manager, I want to be able to submit a translation request with a single click from within the editor, so that I can track the status and approve the returns without leaving my workflow.»

Acceptance criteria

• The «Request a translation» button is displayed for authorised roles.
• The system pre-fills the source language and target languages according to a template.
• The status of the request is updated in real time and keeps a history.
• The user closes the task with a mandatory comment.

A good user story often replaces a long paragraph of unreadable specifications. This type of wording quickly clarifies what the solution should enable, without limiting the technical choice..

 «We rewrote 40 pages of specifications in the form of 80 user stories. Debates decreased, and developers asked fewer questions,» summarises Claire, a project manager in the media industry.

4. Technical requirements and architecture: laying the groundwork

In this section, you give technical teams the depth they need without losing other readers.

First, describe a target architecture diagram : modules, feeds, APIs, storage, third-party tools. Even a simplified sketch makes the subject more concrete.

Then, provide details:

• the integrations (REST or GraphQL, authentication via OAuth2 or OpenID Connect, data mapping),
• the security (encryption at rest and in transit, logging, retention, GDPR, role-based rights management),
• the performance (response time, load, peaks, cache strategy, fault tolerance),
• the quality and observability (logs, metrics, alerts, SLO/SLA, traceability).

Rely on UML modelling When useful: use case diagrams, activity diagrams, sequence diagrams, class diagrams. This allows you to represent data, actors, exchanges, and not just a list of features.

A system lives, changes and improves. You have laid the first bricks. Now you need to decide who will manage it all.

5. Governance, roles and responsibilities: knowing who decides what

A project that is progressing maintains a transparent governance.

Present your project committee : sponsor, product manager, technical advisor, security, editorial... Everyone has a clear role.

Then enter the matrix RACI (Responsible, Accountable, Consulted, Informed):

• who achieves (R),
• who bears ultimate responsibility (A),
• who consults you (C),
• who informs you (I).

Example of a simplified RACI matrix for an IT project (to be adapted according to your needs)

Caption:

• R = Responsible (carries out)
• A = Accountable (final decision-maker)
• C = Consulted
• I = Informed

Add the key point rhythm : sprint reviews, product demonstrations, steering committees, arbitration.

Finally, finish with a risk mapping with their probability, impact and a plan B.

Have you appointed a owner (identified responsible person) for each critical requirement? If not, do so and enter their name in the CCFT.

6. Planning and methods: transforming intention into trajectory

At this stage, it is no longer just a matter of defining what the project must produce, but how it will move forward, be monitored and delivered on time and to the expected standard of quality.

Project management method

First, choose and explain your approach to delivery :

• Agile (Scrum or Kanban) with sprints, prioritised backlog, regular demonstrations, continuous feedback
• Iterative approach or V-model, if your context requires it: V : formalised milestones, sequential phases, intermediate validations

Then, show a roadmap clear, outlining the key phases: exploration, design, build, integration, user acceptance testing, training, go-live, hypercare (period of enhanced support after going live).

Also add phases change management : communication, materials, training, feedback loops.

Quality Assurance Plan (QAP)

Next, the project must be supervised by a Quality Assurance Plan (QAP), formalised by the service provider and approved by the project owner at the start of the assignment.

The PAQ defines the quality framework :

• organisation and responsibilities,
• control and validation processes,
• the criteria for compliance and passing key milestones.

It conditions in particular the user recipe, the decision to go into production and the Go/No-Go. The PAQ thus constitutes a common reference point between the project owner and the project manager to secure deliveries throughout the project.

Operational quality: testing and tools

Finally, in terms of operational quality, Describe the specific measures implemented to apply this framework:

• the CI/CD pipelines (continuous integration and deployment),
• the code reviews and technical inspections,
• the testing strategy : unit, integration, end-to-end (E2E) and security.

Specify the environments (development, testing, acceptance, production), acceptance criteria, and procedures for correcting anomalies.

The objective is straightforward : ensure that each delivery is tested, validated and complies with functional, technical and security requirements prior to deployment.

You have described how the team progresses on a daily basis. All that remains is to define the contractual relationship.

7. Sensitive clauses and contractual clauses

Here, certain clauses carry a significant amount of risk. Therefore, draft them carefully. These include:

• Security and service continuity : encryption requirements, incident management, disaster recovery plan (DRP), logging, authorisations.
• Interoperability and compatibility : exchange formats, APIs, open standards, integration constraints with your IT system (SSO, directory, PIM, CRM, etc.).
• Data reversibility and restitution : export formats, deadlines, responsibilities, costs, support from the outgoing service provider.
• Personal data protection (GDPR) : data categories, location, processors, data processing agreement, role of the DPO.
• SLA / SLO (Service Level Agreement/Objectives): response time, availability rate, escalation and resolution times, potential penalties.

For each clause, Ask yourself the question: “What happens if...?”. If the answer is unclear, the clause lacks precision.

Then define the intellectual property : code, deliverables, templates, documentation, any AI models.

Also address the confidentiality and the RGPD : data, subcontractors, data processing agreement, role of the DPO (Data Protection Officer).

Finish with the invoicing and amendments (how you handle requests outside the scope), then the reversibility : exit plan, backups, data export, skills transfer.

Plan for a legal round table with the DPO and the legal department before signing, not after the first incident.

The most successful projects are prepared by thinking about the outcome right from the start. Paradoxical, but extremely effective.

8. Useful appendices: the toolbox

Finally, don't forget the appendices. They transform a good CDC into reference tool.

Slide it in:

• a glossary which translates jargon (API, SSO, PRA, TMA, etc.)
• from models (user stories, test cases, security checklists, RACI example)
• from diagrams (architecture, data flow, responsibilities)

Readers in a hurry will quickly find the essential information here.

Writing without boring your readers: 10 tips to get read

Specifications must be operational. In other words, the aim is not to produce an exhaustive document, but a living working tool. It should also be remembered that this is still a text. And a text is easier to read when it follows a few simple rules.

1. Adopt a modular structure: each main section can be read separately.
2. Adopt a neutral, factual tone focused on results.
3. Speak to users, not systems
   Prefer «The editor triggers the translation» to «The translation module is triggered».
4. Use concrete and catchy titles
   «What the editor does in 3 clicks» speaks better than «Editor features».
5. Shorten sentences
   Two clear sentences convey more information than one that stretches over five lines.
6. Show progress with words of connection at the beginning of a sentence (First, Next, Furthermore, Finally, etc.)
7. Avoid the passive voice
   «The security team approves the design» is more common than «The design is approved».
8. Promote readability: illustrate with images, tables, diagrams, and mini-scenarios.
   A simple 5-step process, with screenshots or mock-ups, is more convincing than a page of text.
9. Put technical details in boxes or appendices. You maintain a fluid narrative while providing precision for those who seek it.
10. Update the document whenever there is a major change.

A good test: if an external service provider can understand the purpose of the project without verbal explanation, then it is successful.

The technical side: aligning expectations and quality

Ask quantified requirements. Figures reduce misunderstandings.

• Performance : «95% of requests in less than 300 ms for 500 concurrent users (excluding planned peaks).»
• Security : «AES-256 encryption at rest, TLS 1.2+ in transit, monthly rotation of secrets.»
• Interoperability : «Paginated REST API, JSON, versioned, OpenAPI documentation, published consumption limits.»
• Quality : «80% unit test coverage on critical modules», «zero P1 severity incidents in production.»

The figures protect the discussion: everyone knows what “fast”, “reliable” or “secure” means in this specific project.

Governance and communication: the mechanism that prevents over-enthusiasm

Good governance is based on simple routines rather than on ad hoc committees.

For example, implement:

• a demo every fortnight : each sprint concludes with a visibility session
• a monthly steering committee : decisions, trade-offs, risks, finances
• a single channel for change requests (a short form with impact, cost, deadline)
• a decision register shared in 24 hours

Who keeps this record of decisions? Appoint someone and give them the authority to say, «This does not fall within the defined scope.»

Budget, deadlines, risks: putting all cards on the table

Discuss money and timing early on, clearly. For the budget, organised into main sections: Build, Integrations, Security, Testing, Training, Run. Add a contingency reserve (10-15 %).

Side deadlines, use a Lightweight Gantt or a visual roadmap: dated milestones, main dependencies.

Side risks, List them with a mitigation plan.

Example: «SSO integration delay» → «Upstream POC + dedicated IT department contact person».

A simple prototype, produced early on, can sometimes eliminate half of the uncertainties: don't hesitate to negotiate a sprint spike for tricky technical points.

Specifications do more than just define the scope of a project. They explain why the organisation is changing, how it is organising itself to do so, with which partners and under what conditions. They link opportunities to contracts, business ambitions to acceptance tests, users' daily lives to UML models, and commercial promises to SLAs.

When well designed, it becomes a compass shared by all stakeholders. It reduces friction, speeds up decisions and secures the relationship with service providers.

Above all, it no longer resembles a bureaucratic tome. It becomes a document that people open during meetings not because they have to, but because it really helps them do their job.