The project that documents itself

Every consultancy has a graveyard, and it's in the docs. Somewhere in the wiki of every project that ever ran long enough is a beautiful discovery document — weeks of workshops distilled into it, formatted with love, signed off with ceremony — that now describes a platform that doesn't exist. Not because anyone lied. Because the document was written once, at the start, by hand, and the project kept moving after the writing stopped.

I've stopped believing this is a discipline problem. We've all worked with diligent people, on projects with documentation standards, and the graveyard fills up anyway. It's a structural problem: the way documentation gets made guarantees it dies. So on our current builds we changed the way it gets made, and the result is a project where the documentation assembles itself out of the conversations we were having anyway — and keeps going, past the docs, all the way into the Jira backlog.

This is the front half of a story whose back half I've already told. Last time it was defects: a one-hour UAT walkthrough becoming forty-five finished tickets, because the call itself was the raw material. This is the same idea aimed at the other end of the project — where requirements are born instead of where bugs are found — and it turns out that end is where the idea pays best.

Written twice, read never

Watch what actually happens to workshop knowledge on a traditional project. The workshop itself is brilliant: the client's operations manager explains, with total precision, exactly how their dealer pricing works, including the exception for the legacy accounts and the thing nobody in head office admits about freight. Everyone nods. Someone writes "pricing — see recording" on a sticky note.

Then the knowledge starts its journey to the page, and the journey is where it dies. Whoever runs the write-up spends the following week reconstructing the conversation from memory and scribbles — the first writing. The write-up lands wherever it lands, usually a page named after the meeting rather than the topic, so three months later nobody can find it — which produces the second writing, when someone re-asks the client a question they answered in June. And because updating a hand-written document is nobody's actual job, the version that exists describes the project as it stood at the last heroic write-up, drifting a little further from the truth every sprint.

Written twice. Read never. Rotting from the day it's born.

The UAT article's diagnosis applies here word for word: the information is at its richest in the room, and the traditional process throws that version away and reconstructs it later, from worse material. But requirements have a second, sneakier failure mode that defects don't. A bug report that rots simply gets re-found. A requirement that rots gets rebuilt wrong — the platform ships with the misremembered version of the pricing rule, and you find out at go-live, from the operations manager, who told you the correct version in workshop two.

The hypothesis: ask the questions before you have the answers

The fix has two moves, and the first one looks like nothing.

Before any workshop runs — before we know anything about the client beyond their name — we scaffold the entire documentation tree, empty. Not a blank wiki. A structured emptiness: sixty-odd Notion pages laying out everything we know we'll eventually need to know about any B2B commerce build. Business overview. Customer personas. Business actors and roles. A glossary table mapping the client's language to platform concepts. Page-by-page functional requirements for a storefront that doesn't exist yet — listing, detail, quick order, checkout, my account. Platform configuration sections with every table empty and every decision marked TBD. There's even a page titled "What Does Utopia Look Like?", which sounds like a joke until you watch what clients tell you when you ask them that with a straight face.

Alongside it, a workshop framework: nine sessions that walk the whole domain — business context, personas and actors, systems of record, org structure and access, catalogue and pricing and entitlements, cart and checkout, admin and provisioning, integrations, operations. Here's the detail that makes the whole machine work: every workshop page declares, up front, which documentation pages it fills. Each question in the workshop agenda carries a status the facilitator flips as the session runs — answered, unresolved, deferred. The scaffold isn't a filing cabinet waiting for paper. It's a set of typed slots, and the workshops are the process that populates them.

Which is the point of the second move. Every workshop is recorded, and the AI meeting note — summary, action items, full transcript — lands in Notion attached to the workshop page. Then one sentence, process workshop five, and the pipeline reads the transcript against the scaffold and files what it heard: pricing rules into business requirements, a new persona into personas, three new terms into the glossary with their commercetools mappings, the deferred questions marked TBD on the pages where their answers will eventually live. Because the structure existed before the content, "where does this go?" was answered before the workshop happened. Nobody writes up the workshop. The workshop is the write-up.

The loop: teaching it to merge, not to write

Getting there was the same reverse-engineering exercise as the defect skill — run it, compare it to what a good human would have produced, name the difference, encode the rule — and once again the failures were more instructive than the successes, because each one was a piece of unwritten judgement we'd been applying for years.

The most important rule sounds banal and is anything but: merge, don't replace. Workshop five's transcript arrives at documentation that workshops one through four already populated. The naive move is to write what the new transcript says. The correct move is closer to what a careful editor does: if the workshop confirms something already documented, enrich it; if it introduces something new, weave it into the structure that's there; and if it contradicts the docs — this is the one that matters — update the page and leave a visible scar: "Updated per Workshop 5 — previously X, now confirmed as Y." Projects change their minds. A documentation system that silently overwrites its history will eventually gaslight its own team about what was ever agreed.

The second rule: document the final position, not the journey. Workshop conversations wander — someone proposes a thing, the room argues, the thing dies, a better thing emerges. A transcript-faithful summary would document the corpse alongside the survivor. The docs get the decision, and the reasoning when the reasoning matters, and none of the noise. The transcript keeps the noise, footnoted, for the day someone asks how we got here.

The third took a bad experience to learn: mused is not decided. A client thinking out loud — "maybe we should let dealers see each other's pricing, actually no, forget that" — must never crystallise into a requirement. The machine's ear had to be tuned for commitment: decisions confirmed in the room land as facts, speculation lands nowhere, and anything ambiguous lands as a flagged question rather than a quiet guess. Same principle the defect skill arrived at from the other side: an honest gap beats a confident fabrication, every time.

And wrapped around every run, the same safety gate as always: before anything is written, the pipeline presents what it heard and where it plans to file it, and a human says yes. That checkpoint costs two minutes. What it buys is the right to let the machine touch your source of truth at all.

The unexpected side effect, which regular readers will recognise as a pattern by now: knowing the transcript is the raw material changes how you run the room. You start saying decisions in full sentences. You state the final position out loud before moving on — "so, confirmed: entitlements renew on the employment anniversary, not July" — not for the humans, who already know, but for the record, which is listening. Facilitation becomes dictation. It's a better meeting discipline even before a machine is involved.

Past the docs: the pipeline keeps going

If the story stopped at "tidy Notion pages", it would be a nice productivity anecdote. What makes it structural is that the docs aren't the end of the pipeline. They're the middle.

Once workshops have filled the requirements, the next skill in the chain reads them and proposes the platform configuration — the concrete commercetools product types, custom objects, business unit hierarchies, the Algolia index strategy, the CMS content models — each derived from named requirements, each iterated with a human before it's committed. This is the stretch of the pipeline where mistakes are expensive: a product type can't be restructured once products exist, and a business unit hierarchy quietly decides your permission model forever. So this stage runs propose-discuss-confirm, and it writes down why each choice was made next to the choice — the rationale column that every future developer silently thanks you for.

And once the specs are firm, the last skill reads a requirements page and emits the Jira epic and its stories — personas from the project's own glossary, acceptance criteria in Gherkin for behaviour and checklists for detail, never inventing a criterion the spec doesn't support, each story labelled back to the page and sub-flow it came from. Those labels aren't decoration; they're how the pipeline detects, on a re-run, that a page is already ticketed and only the delta is new. Sound familiar? It's the defect skill's discipline — classify, gate, never fabricate, leave a provenance trail — applied to the start of the build instead of the end.

Put the stages together and you get the property that I think matters most, the one hand-written documentation has never once delivered on any project I've seen: traceability. A developer picks up a story about dealer pricing. The story labels back to the requirements page that produced it. The requirement carries the workshop that established it. The workshop page holds the meeting note, and the meeting note holds the transcript, and somewhere in minute forty-one the operations manager is explaining the legacy-account exception in her own words. Every link in that chain was created as a by-product of work someone was doing anyway. Nobody maintained a traceability matrix. Nobody would. That's why this only works as a pipeline.

The real lesson isn't about documentation

Strip away Notion and commercetools and nine workshops' worth of agendas, and the move underneath is one I'd now look for everywhere: build the structure before the content arrives, and the content files itself.

The scaffold is the whole trick. Unstructured conversation flowing at structured emptiness becomes structured knowledge — the same hour of talking, worth an order of magnitude more, because there was a shaped place for it to land. Without the scaffold, a transcript is a wall of words and every write-up is an act of heroism. With it, the write-up is a routing problem, and routing is exactly the kind of judgement you can teach a machine, one named rule at a time: merge don't replace, final position not the journey, mused is not decided.

The graveyard, it turns out, was never full of documents. It was full of artefacts — things written once, at a moment in time, by someone whose real job was elsewhere. The docs on this pipeline aren't artefacts. They're the medium the project flows through on its way from a conversation to a backlog, kept alive by the same meetings that used to kill them.

The operations manager, for what it's worth, has no idea she's been writing the requirements since June. She just thinks we run unusually good workshops.

AFKN builds B2B commerce platforms on commercetools and Algolia, and runs every engagement through the pipeline described here — nine workshops in, a traceable backlog out. If your project's documentation is already describing a platform that doesn't exist, we should talk: hello@afkn.com.au