What a software specification should actually include

Before software gets built, there is a specification — the document that says what is being made. For the business commissioning the work, this document is the single most important protection it has, and most specifications fail at the job. They describe features in vague terms, leave the important things unsaid, and protect the builder far better than the client. A good specification is what stands between you and a project that overruns, drifts, and delivers something you did not want. Here is what one should actually include.

What the specification is really for

A specification is not paperwork; it is the agreement that everything else is measured against. When there is a dispute about whether something was delivered, whether a change is in scope, whether the work is finished — the specification decides it. A vague spec means every one of those questions is settled in the builder’s favour, because there is nothing concrete to hold them to. A clear spec means the client can hold the work to a defined standard. The document is, in effect, where the balance of power in the project is set.

What a good specification includes

A specification that protects the client covers more than a feature list. It states the problem and the outcome — what the software is for and what success looks like in business terms, not just what screens it has. It defines the functionality precisely enough that “done” is unambiguous, so completion is a fact rather than an argument. It addresses the data: what the system holds, where it comes from, how it relates — the foundation that determines whether the result is sound or produces the kind of inconsistent data that plagues poorly specified systems. It covers the non-obvious requirements that get omitted and cost the most: security, performance under real load, what happens at the edges, how it integrates with what you already have. And it sets out acceptance — how you will judge that the work meets the spec before final payment.

The omissions are where projects die. The features get specified; the data, the integrations, the security, the performance and the acceptance criteria get left vague — and those are exactly the things that overrun, disappoint, or fail later.

Why most specifications fail the client

Most specifications are written by, or heavily shaped by, the builder — and a builder, reasonably, writes a spec that is comfortable to build against and easy to claim completion on. A non-technical client cannot tell what is missing, so they sign it. The gaps surface later as change requests, overruns and disappointment, all of which the vague spec quietly licensed. This is a major reason behind IT projects going over budget: the budget was set against a specification that never pinned down what was actually being bought.

What to do before you commit

The protection is to have the specification written or reviewed by someone on your side before you commit to it — someone who knows what should be in it and what is conspicuously missing. That is part of the independent oversight described in what build and oversee actually means: getting the spec right is the cheapest, highest-leverage point in the whole project to influence the outcome, because everything downstream is measured against it.

Most specifications fail to protect the client. I can review what you are planning to send before you commit to it. We will make sure the document protects you rather than the builder.

Start a Conversation