19 May 2022

Beyond Specs

This is an exec member exclusive video.

You might think that documenting what you're doing would be an untrammeled good. Surely it will help QA people test, customers understand the system, and new engineers learn the code quickly. But there's a good reason that some smart engineers resist writing yet another spec or drawing yet another diagram.

The dirty secret of "standalone" documentation is that it goes out of date quickly, often before it's finished. Especially when you build iteratively, adapting to your market as you learn about it, your architecture, code design, and user interface all change very rapidly, and it's beyond the capacity of every team I've ever seen to keep up without slowing development to tortoise speed.

But there's no need to despair. There are well-tested methods for ensuring you always know what your system does and what it's supposed to do, and keeping those two closely in sync. I'll explain:

"Narrative" tests and how they let anyone, no matter how non-technical, read and comment on the real code directly.
How you can make your whole system self-documented and always up to date, including infrastructure and integrations.
Decision logs and why they win over Architectural Decision Records (ADRs).