Plumbdev06-1 · say it in the reader's words
What somebody implementing a story does where the story's words and the names the code will use differ: name the inside so it outlives any one audience, and carry each audience's word at the edge.
dev06-1-1 name the thing in words that outlive any one audience Nothing holds it
As somebody implementing a story I want the names inside the code chosen for how long they will be true, so that a second business unit arriving with its own vocabulary is a day's work at the edge rather than a rename of everything.
Requirements (5)
What the user needs
- dev06-1-1-ur1the name is chosen for how long it stays true, and not for who asked for the work first
- dev06-1-1-ur2one name is used at every call site inside, so changing it later is one decision rather than a negotiation
What the system does
- dev06-1-1-sr1the implementation keeps one vocabulary across its own modules; a name that differs between two of them is two concepts or one mistake, and nothing downstream can tell which
How well
- dev06-1-1-nfr1the story is still the authority on what the thing is; this is a naming decision and never a licence to implement something the story did not describe
Still open
- dev06-1-1-u1how anybody recognises a name that will outlive its audiences before the second one arrives is undecided; the ones that failed were obvious only afterwards
dev06-1-2 is that name one audience's word? Nothing holds it
As somebody implementing a story I want a name borrowed from whoever asked first to be caught before anything is built on it, so that the cost of the borrowing does not fall on whoever arrives second.
Requirements (5)
What the user needs
- dev06-1-2-ur1a name that is one audience's own word is named as such before code is written against it
- dev06-1-2-ur2a word the audience happens to share with the trade is not a borrowing; what makes one is that the audience could change theirs and the code would then be wrong
What the system does
- dev06-1-2-sr1the comparison is against the words that audience actually uses, gathered from them, and never against a list of terms somebody believes are domain-specific
How well
- dev06-1-2-nfr1a borrowed word is discovered when the second business unit arrives, which is the most expensive moment available: the code is written, the tests cite it, neighbouring systems read it, and the rename has become a negotiation between two customers rather than a decision
- dev06-1-2-nfr2the same word meaning two things in two business units is the harder case and looks like agreement — done, closed, approved — so it is read fluently and wrongly by both
dev06-1-3 carry each audience's word at the boundary Nothing holds it
As somebody who reads what this system produces I want it to say what I would say, so that I can act on it without translating out of somebody else's trade.
Requirements (8)
What the user needs
- dev06-1-3-ur1each audience meets its own word where it meets the system — the label, the description, the field a consumer reads — and never the implementation's
- dev06-1-3-ur2adding an audience adds words at the boundary and changes nothing inside, which is the whole return on having named the inside durably
- dev06-1-3-ur3two audiences may give one implementation name two different words, and that is ordinary
What the system does
- dev06-1-3-sr1one boundary word stands for exactly one implementation name: an audience may not be shown one word for two things, because it leaves them unable to say which they mean
- dev06-1-3-sr2the boundary is the only place an audience's word appears; a core that reads one has taken the borrowing back
How well
- dev06-1-3-nfr1an audience reading the implementation's words translates on every reading, and the ones who get fastest at it stop noticing — which is when they begin reporting the technology's word back as their own and the two vocabularies quietly merge
- dev06-1-3-nfr2the boundary is where a mistake is visible and cheap; a wrong label is argued with by whoever reads it, and a wrong internal name is argued with by nobody
Still open
- dev06-1-3-u1whether a boundary word belongs to the interface's version or moves independently of it is undecided; a renamed label is not a breaking change to a program and may be one to a person
dev06-1-4 keep the story findable from the code that serves it Nothing holds it
As anybody reviewing whether this was built I want to get from the story to the code and back without either of them being renamed to match, so that two vocabularies do not cost us the trace.
Requirements (6)
What the user needs
- dev06-1-4-ur1the code serving a story can be reached from the story, and the story from the code, while the two go on using different words for the same thing
- dev06-1-4-ur2nothing is renamed to make the trace work — that is the failure this flow exists to avoid, arriving from the other direction
What the system does
- dev06-1-4-sr1the link is the citation a test already carries; no second document is written to hold the mapping
How well
- dev06-1-4-nfr1a mapping kept as its own document is a third home for a fact that already has two, and it drifts from whichever of them moves first — usually the code, silently
- dev06-1-4-nfr2without the trace, a reviewer holding a story and a file cannot tell a faithful implementation under a different name from an unfaithful one, and the safe-looking response is to make the names match
Still open
- dev06-1-4-u1whether a boundary should also say which story it serves is undecided; it would make the trace readable at the edge and would put a spec identifier into shipped surface