How to write a functional design document

A functional design document (FDD) describes what a system must do — its behaviour, rules and boundaries — precisely enough that a team can build it, a client can accept it, and both can agree on whether a feature is finished. It sits between the business requirements (why the system exists) and the technical design (how it is built).

The test of an FDD is not its length. It is whether two people reading it independently would build the same thing.

What an FDD contains

Every FDD we write follows the same structure, scaled to the size of the job. You can see it in full in our sample FDD — the specification for this website.

1. Purpose and scope. What the system is for, and what outcome it serves. One page, not ten.
2. Out of scope. The explicit list of what the system will not do. This is the section that makes a fixed price possible, and the one most often missing.
3. Assumptions. What is being taken as true, and what changes if it is not.
4. People and roles. Who uses the system and what each role is allowed to do.
5. The process, as-is and to-be. How the work runs today, including the workarounds, and how it will run with the new system — including which changes are software and which are people.
6. Functional requirements. Each with an identifier, a statement of what the system must do, and acceptance criteria.
7. Business rules. The calculations, validations and decisions the system enforces, written so they can be checked.
8. Data. The entities the system holds, their relationships, and who owns each record.
9. Integrations. Every other system it talks to, what moves in each direction, and what happens when the other side fails.
10. Non-functional requirements. Performance, availability, security, privacy, accessibility — stated as measurable targets.
11. Decisions and open questions. What has been decided and why, and what is still open.

Write requirements that can be tested

The difference between a useful requirement and a useless one is whether you can test it.

Untestable: The system should make approvals easy and fast.

Testable: A purchase request over the approval threshold is routed to the requester’s manager. The manager can approve or reject it from the notification. A request not actioned within two business days is escalated to the next approver, and the escalation is recorded.

The second version tells the developer what to build, tells the tester what to check, and tells the client exactly what they are getting. Every requirement should have acceptance criteria in that form: specific conditions under which it is met.

Words to hunt for and replace: user-friendly, fast, flexible, intuitive, seamless, as needed, etc. Each hides a decision nobody has made yet.

Make it traceable

Give every requirement an identifier. Then each acceptance test can point to the requirement it proves, each change request can name the requirements it alters, and nobody has to argue about which version of a feature was agreed. On larger programmes this becomes a requirements traceability matrix; on smaller ones, consistent identifiers do most of the work.

How long should it be?

As long as the risk requires, and no longer. We scale the same discipline to the engagement:

• A defined feature or single integration: a two-to-four-page scope annex inside the quote.
• A module or workflow: a short-form FDD, produced in one to two weeks.
• A platform, many stakeholders, or compliance-bearing process: a full FDD with architecture and data model, over three to six weeks.

Five tests before you sign it off

1. Could two teams quote it and arrive at similar numbers? If not, it is too vague.
2. Can every requirement be tested? Look for acceptance criteria on each one.
3. Is the out-of-scope list real? It should name things stakeholders actually asked for.
4. Do the people who do the work recognise the as-is process? If not, the to-be is built on a fiction.
5. Are the integrations’ failure cases described? “Sends data to the ERP” is not enough; what happens when the ERP is down?

Where to start

Start with the out-of-scope list and the as-is process — the two sections people skip, and the two that cause the most trouble later. If you want a specification written for you, or a review of one you already have, that is our requirements analysis service.