Documentation that gets read
On This Lesson 4 topics
This lesson is planned. The outline below lists the topics it will cover. The full lesson has not been published yet.
In this lesson
write docs people actually use.
Planned topics
- Write for a named reader with a named question: new joiner, on-call engineer, reviewer.
- Keep docs next to the code (docs as code): reviewed in pull requests, versioned in git.
- Prefer a few short, current documents over many stale ones; give each an owner and a date.
- Document why, not what; the code already says what.
- Every diagram needs a title and a legend.
Draft outline details
Demonstration
a docs folder layout: docs/adr/, docs/rfc/, docs/architecture/, docs/runbooks/.
Check your understanding
What goes wrong with a diagram that has no legend?
Show answer
Readers guess what boxes and arrows mean.
Practice
Apply this lesson with the module's lab, exercises and quiz.
Marking a lesson complete is optional and you can undo it any time. Your progress stays in this browser.