Why specifications instead of a requirements document

The structure below follows the Manz textbook (chapter 7, lesson 2). Read it as one argument in seven steps: where the client stands, what they already have, what they want, what the system must do, how much of it, how an offer is to be handed in, and what is agreed around all of that.

The chain from chapter 1 to chapter 4 is what makes the document readable: an initial situation, the problem it produces, and only then the task derived from it. A requirement whose origin you cannot trace back to chapters 1 to 3 is usually somebody’s private wish.

Two chapters are regularly skipped and both are expensive. Current state: the system is built into an organisation that already works somehow, and whatever it does today is what people will compare yours with. Volume estimate: 30 members and 30 000 are not the same system, and you find that out either here or in production.

Chapter 4 carries two kinds of requirement, and telling them apart is the skill:

A functional requirement you either implemented or you did not. A non-functional one only becomes a requirement once it carries a number or an observable condition: "fast" is not a requirement, "the attendance list of a group of 30 opens in under a second on the lab laptops" is.

Requirements are numbered, and that is not decoration. Numbering is what makes a requirement referable: a test case, a review comment and an acceptance protocol can all point at the same number and mean the same sentence. That is exactly the job a requirement id in openspec/specs/ does today.

"Non-functional" is a wastebasket word until you have a list. ISO/IEC 25010 is that list — the product quality model, nine characteristics, each with its sub-characteristics. Use it as a checklist when writing chapter 4: go through the nine, and for each one decide whether it matters here and what the measurable condition is. Most will not matter; the two or three that do are the ones that would otherwise have been discovered in production.

The colours in the diagram group the nine: the top row is what the user experiences, the middle row is how the system behaves and protects, the bottom row is what the developer lives with — plus safety, which sits with the protecting ones.

Own diagram; the characteristic names follow the current edition (ISO/IEC 25010:2023) as published at iso25000.com. The 2011 edition had eight characteristics: Usability has become Interaction capability, Portability has become Flexibility and gained scalability, and Safety is new. Older material — including much of what you will find while searching — still shows the eight.

Two characteristics carry a warning for school projects. Security is not a feature you add at the end; confidentiality and integrity decide the data model. And Safety only concerns you if your system can cause physical harm — in an attendance app the honest answer is "not applicable", and writing that down is better than inventing a requirement for it.

Alongside the functional specification the client writes a second paper — for themselves. The criteria catalogue (Kriterienkatalog) is internal, the supplier never sees it, and its purpose is to evaluate the offers that come in.

Nothing in that list was abolished. What changed is the form: instead of one document written once, the same content lives in small files that are updated with every change and checked by the build.