A small note on writing the manual before the code
Why our first deliverable on most engagements is a one-page operating manual, not a prototype, and how it changes what gets built.
Most software engagements start the same way. Kickoff on Monday, scoping conversations all week, then a fortnight later someone shows a prototype: a clickable thing, a half-working pipeline, the shape of an answer. The prototype proves the technology works. It tells you almost nothing about whether the operation works.
By month two, the team has quietly built a parallel set of spreadsheets, group chats, and follow-up rituals around the prototype. The prototype handles the easy 60%. The spreadsheets handle the awkward 40%, the bit nobody wrote down, the bit that turns out to be the actual job. We have watched this play out enough times that we now do something different first.
The manual
Before we write code, we write a one-page operating manual. Not a spec. Not a brief. A manual: the document that tells a future operator how to run the thing once it exists. It contains: who is responsible for what, in second-person language ("you do", "the system does"); the trigger conditions for each action ("when an order arrives, the warehouse notifies the courier"); the explicit non-goals ("we are not handling international shipping in this version"); the failure modes ("if the courier API is down, we email the orders queue"); and the named humans and systems on either side of every handoff.
We write it in concrete verbs. Not "manage" or "handle" or "process"; those words hide the work. "Confirm", "record", "forward", "reject". One verb per action. If a step needs a paragraph to explain, the step is wrong.
Why it works
The act of writing "you do" forces ownership to be named. The act of writing "the system does" forces the system's job to be defined. Most of our manuals never reach the second draft before someone says "wait, that's not how we do it" and a thirty-minute conversation surfaces an assumption that would otherwise have hidden until launch week. Each of those conversations is worth a fortnight of rework.
By the time we draft any code, the prototype has half the surface area it would have had otherwise. The team agrees on what it is supposed to do, who runs it, and what it explicitly does not do. The build phase becomes (boringly, usefully) the act of making the manual true.
Caveats
Not every engagement needs this. Pure greenfield work, where the operation does not yet exist, sometimes wants a prototype first, because the prototype is the operation, and the manual can only be written by watching the prototype get used. But for the other 80% of jobs (replacing something, automating something, joining two existing operations together) the manual saves more than it costs.
The closing rule we have adopted: if we cannot fit it on one page, we do not yet understand it well enough to build it.