Documentation Practice
Keeping documents close to the code and honest about staleness.
4 to work through
-
intermediate
A developer platform's users repeatedly build integrations that break on the platform's next release. What communication failure caused this?
2 min answer -
intermediate
A platform's documentation is comprehensive and developers still get things wrong. What kind of documentation is missing?
2 min answer -
intermediate Multiple choice
Four team wikis holding about 1400 pages between them are being consolidated into one documentation site for 300 engineers. Analytics show 43 pages serve over half of all reads. Which sequence do you run?
3 min answer -
intermediate
You have two hours to document a system before handing it over. What do you write, and what do you deliberately leave out?
2 min answer
3 terms in this topic
Diátaxis Framework
A placement rule for technical documentation that separates four reader needs - tutorial, how-to, reference and explanation - so one page serves one …
conceptDocumentation Decay
The tendency of written documentation to become inaccurate faster than it is updated, making stale documentation actively more harmful than none.
practiceDocumentation Practice
Writing what will be read, keeping it true, and deliberately not writing the rest.
Neighbouring topics
Architecture Communication
General material on communicating architecture.
Architecture Diagrams
Choosing an audience and refusing to mix levels of abstraction.
C4 Model
Context, container, component and code as four separate diagrams.
Context Diagrams
The system as one box, with its users and external systems.
Sequence Diagrams
Ordered message exchange, and walking the failure of each arrow.
Data-Flow Diagrams
Following the data across trust boundaries rather than the calls.
Deployment Diagrams
What runs where, in which zone, behind which boundary.
Communicating Threat Models
Making risk legible to people who will fund or accept it.
Writing Decision Records
Context, alternatives and consequences, written once and never edited.
Technical Proposals
A written argument circulated before the decision feels made.
Architecture Reviews
Reviewing early enough to influence rather than to veto.
Presenting to Executives
Decision first, cost, risk, and what happens if we do nothing.
Presenting to Engineers
Mechanism, alternatives rejected, and what you are unsure about.
Explaining Trade-offs
Naming what was given up, and the condition that would change it.
Handling Disagreement
Arguing from consequences, and escalating in the room.
Negotiation
Trading on interests rather than positions, with priced options.
Presentation Skills
Structure, pacing and the slide that carries the decision.
Written Communication
Writing that survives being read without you in the room.
Facilitation
Running a design session that reaches a decision.