Career & Craft
Documentation
Writing down how a system works and why decisions were made — READMEs, API docs, architecture diagrams, runbooks and decision records — so others and future-you are not reverse-engineering intent. It is a first-class deliverable, especially for onboarding and incidents. The discipline is keeping it next to the code and current, since stale docs mislead.
Purpose
Documentation writes down what the code cannot say about itself: how to run the system, why decisions were made, what to do when it breaks. Its real audience is always someone missing context — the new teammate, the on-call engineer at 3 a.m., and future-you, who forgets more than present-you believes.
When to Use It
The high-yield set: a README that gets a newcomer running quickly; API references consumers can trust; architecture decision records capturing why choices were made (the 'why' evaporates fastest); and runbooks for incidents — written calmly in advance, followed under pressure.
Trade-offs
Documentation rots: stale docs actively mislead, which is worse than absence. The economics argue for documenting stable interfaces and decisions rather than volatile internals — code should self-document the how; prose should preserve the why. Writing time competes with building time, so spend it where reading is repeated.
Implementation
Keep docs next to the code they describe (same repo, reviewed in the same PRs) so drift is visible. Prefer plain markdown, date decision records, and delete or mark outdated pages ruthlessly. Test the README by watching a newcomer follow it; test runbooks in game days, not incidents.