Writing a design the whole team reads
Actors, features, objects, rules: describing a product as connected needs rather than pages.
Product specs have a bad reputation: long, frozen, read once and then forgotten. Yet a team needs a shared description of what it is building.
Why linear documents fall behind
A text document tells the product’s story in a given order. But a product has no order: an actor uses several features, an object is handled in several places, a rule applies everywhere. As soon as one item changes, you have to track it down everywhere it is mentioned.
Four catalogs
An alternative is to write each item only once, in a catalog. Four are usually enough:
- Actors: who uses the product (customer, administrator, coach…).
- Features: what they can do.
- Objects: what the product handles, with their fields.
- Rules: what must always be true.
Needs to connect them
Catalogs don’t yet say who does what. That is the job of the need, a sentence anyone can read: “As a Customer, I want to place an order, so as to receive my items.” The need names its actors, its feature, the objects involved and the rules to follow — for example the Order object, whose payment field carries the 3-D Secure rule.
Inheritance, without the jargon
When several actors share characteristics, inheritance avoids repetition: a Coach and a Customer both inherit from User, and its needs are theirs too. The same goes for objects: an object that inherits from another gets its fields, and can override some of them.
A diagram you never draw
Every need has its own diagram, generated from what it connects: the actors, the feature, the objects with their fields, the rules. Nobody draws it, so nobody forgets to update it.
Export for humans and machines
Every need exports to Markdown with its full context. The format reads just as well for a developer discovering the project as for an AI assistant that has to understand its context.