Technical Documentation
The problem
Code shows what a system does, but rarely why — the reasoning, constraints, and rejected alternatives behind a decision live only in someone's memory unless deliberately written down, and that memory leaves with the person or simply fades, leaving future engineers to rediscover the same reasoning from scratch.
Why now
Coupling and cohesion already established that a module's public interface should be a deliberately narrow, understandable contract; documentation is the missing explanation of that contract's intent for a reader who can see the interface but not the reasoning that shaped it.
Mental model
Good technical documentation answers the questions code alone can't: why this approach and not an obvious alternative, what constraints shaped this design, what would break if a specific assumption stopped holding. It's written for a reader arriving cold, with none of the context the author had while writing the code — the same 'why before how' discipline this entire graph is built around, applied to your own systems instead of general concepts.
Requires
- Coupling & CohesionSoftware Architecture
Documentation is most valuable exactly at the boundaries coupling-and-cohesion already identifies — a module's public interface — explaining the intent behind that interface for a reader who can see its shape but not its reasoning.
Used in
- READMEs, architecture decision records, and API documentation
- Onboarding new engineers into an unfamiliar codebase
- Explaining a non-obvious design decision so a future engineer doesn't accidentally 'fix' it back into a known bug
- Runbooks used during incident response, written calmly in advance rather than improvised under pressure
Projects
- Write a README for a real project explaining not just how to run it, but why it's structured the way it is and what tradeoffs were made
- Write an architecture decision record (ADR) for a real or hypothetical technical choice, including the alternatives considered and why they were rejected
Examples
- A comment explaining 'we retry three times because the payment provider's API is flaky under load, confirmed via their status page' prevents someone from later 'simplifying' away a deliberate workaround
- An architecture decision record documenting why a team chose PostgreSQL over MongoDB lets a future engineer understand the reasoning instead of re-litigating a settled decision
Resources
Mastery checklist
- I can write documentation that explains why a decision was made, not just what the code does
- I can write an architecture decision record including rejected alternatives
- I can identify which parts of a system most need documentation (non-obvious tradeoffs, workarounds)
- I can write a README that orients a completely new reader effectively