What a software specification should contain: a checklist for agencies

A specification is the agreement between what the client expects and what developers build. A good one lets a developer who was not in the meetings build the right thing, and lets the client check that what was built is what they asked for.

It does not have to be long. It has to be complete enough that nobody has to guess. Use the checklist below to find what is missing before the specification is handed over.

• Every screen, named and numbered, so everyone can refer to it.
• How each screen is reached, and where each of its actions leads.
• Which roles can see each screen.
• The states of each screen: empty, loading, error and success.

For each screen, describe what it does in a way that can be tested.

• Required fields and their validation rules.
• What happens on success, and on each kind of failure.
• Limits such as time windows, quotas or maximum file sizes.
• Acceptance criteria that someone can check: when this happens, the app does that.

• The entities the app stores, and their fields.
• How the entities relate to each other.
• Who owns each record, and who may change it.
• What has to be kept, archived or deleted, and when.

• The operations the frontend needs from the server — the API endpoints.
• Who may call each operation, and how they sign in.
• External services such as payments, email, maps or identity providers.
• Background jobs and the notifications the app sends.

• The personal data the app processes, and why it needs it.
• Expected load and response times, where they matter.
• Supported devices, browsers and languages.
• Accessibility requirements.

Every specification has gaps. Mark them instead of hiding them.

• Assumptions you made that the client still has to confirm.
• Questions that are waiting for an answer.
• What is explicitly out of scope for this phase.

A specification written once in a document goes out of date with the first change request. Tie it to the plan it describes, keep its versions, and compare them when the scope changes, so that everyone works from the same one.

Throughplan writes the frontend, backend and database specification from the project’s screens and data, together with the findings of its review agents. Each finding becomes a requirement the specification has to answer.

When the wireframe changes, the specification is marked out of date until it is written again, so you always know whether you are reading the current version.