The Software Spec (Cahier des Charges) Guide — And Why Yours Is Too Long

Most custom-software projects don't fail in the code. They fail in the brief — the cahier des charges. Either there isn't one, or it's a 50-page document written before anyone understood the problem, frozen into a contract nobody reads after week two.

A software specification is simply a shared description of what the software has to do and why. Its job is to create agreement between you and whoever builds it — not to predict every screen in advance. Here's how to write one that actually helps: a clear definition, what belongs in it, a concrete example, and a template you can copy.

---

What is a software specification?

Definition, in one sentence: a software spec (cahier des charges) is the document that describes what a piece of software has to do and why, as a written agreement between the client and whoever builds it. It isn't a technical blueprint, and it isn't a frozen contract — it's a shared point of reference on the problem to solve and the outcome expected.

People often split it into two forms, and confusing them is a classic way projects derail: the functional spec (what the software must do, from the business side) and the technical spec (how it will be built). Both are useful — just not at the same moment.

Functional vs. technical spec

The distinction comes up constantly, so let's make it clear:

• The functional spec describes the business need: the expected functions, the users, the workflows, the outcomes. It answers "what" and "why" without assuming the technology. This is the one to start with.
• The technical spec describes the "how": architecture, technology, performance, security, integration constraints. It's usually written later, with the builder, once the functional side is clear.

Our advice: start with the functional spec and keep it short. The technical side follows from build decisions; freezing it too early means imposing a solution before you've understood the problem.

What actually belongs in it

Keep it short enough that people read it. In practice, a useful software brief needs six things:

• The problem and context. What's broken today, for whom, and what it costs (time, errors, money). Not "we want an app" — "quotes take three hours in a spreadsheet and 1 in 5 goes out with a pricing error."
• The users and their jobs. Who uses it and what they're trying to get done. A tool for two power users is a different project from one for fifty occasional users.
• The core workflows. The three or four things the software must do end to end. Describe the flow, not every button.
• Must-have vs. nice-to-have. An explicit line between what version one needs and what can wait. This single distinction saves more budget than anything else.
• Constraints. The systems it must connect to (ERP, accounting, messaging), the data it touches, security and GDPR requirements, and any hard deadlines.
• What success looks like. One or two measurable outcomes — "reps send a correct quote in under 10 minutes" — so everyone knows when it worked.

That's it. If your document is longer than what your team will actually read, it's not a spec, it's a filing cabinet.

A concrete example

Theory is clearer with an example. Here's what a useful functional spec looks like for an SME that wants to replace its spreadsheet-based quoting process:

One page, six points, and everyone knows what's being built and why. It's an example, not a rigid template — adapt it to your project.

The mistakes that sink projects

• Specifying solutions instead of problems. "Add a dropdown here" hides the real need and blocks better answers. Describe the outcome; let the builder propose the how.
• Freezing scope before you've learned anything. The most expensive assumptions are the ones written down as requirements on day one and never questioned.
• Ignoring the data and integration reality. Where does the data live today, in what state, and what has to talk to what? This is where "simple" projects get expensive.
• No success metric. Without one, "done" becomes an argument instead of a fact.

Our take: the brief is a starting point, not a fortress

We build software for a living, and the best projects don't start with a perfect 50-page cahier des charges. They start with a clear one-page brief and a small, high-value first slice — something real in weeks, not a big-bang delivery in a year. You learn more from one working feature than from three months of specification.

Modern AI-assisted development makes this even truer: it's cheaper to build a first version and iterate than to try to specify everything up front. So write the brief to align on the problem and the first slice — then let reality refine the rest.

A template you can copy

Here's the template, stripped to the essentials. Copy it, fill it in on one page:

Skip the 50-page document

If you're scoping a custom tool and staring at a blank cahier des charges, don't over-engineer it. Send us the one-pager — or even the messy version — and we'll tell you honestly what's missing and whether the project is worth doing. Get in touch.

Related: what custom software actually is and when it's worth it, low-code, no-code, or custom: how to choose, and business process modeling.