Skip to content

Overview

Section 11 · Documentation — Docs as code, READMEs, per-feature docs, lesson banks, runbooks.

6 lessons.

By the end of this section you can

  • Write a README a stranger can follow to a running system.
  • Keep documentation honest by updating the file that would have prevented the confusion.
  • Capture a lesson in the form that changes future behaviour: a gate, a rule, a test or a doc.
  • Write a runbook you could follow at 2am.

Docs As Code

beginner · ~15 min — An agent starts every session with no memory of the last one, and so do you three weeks later.

Writing A Great README

beginner · ~12 min — The README is the only document every visitor reads, human or agent, before deciding whether your project is worth their time.

Documentation Per Feature

intermediate · ~15 min — Docs decay one feature at a time. Nobody decides to let the API reference drift; each PR just happens to be the one where the author was in a hurry.

Lesson Banks And Retros

intermediate · ~15 min — A gotcha entry records a fact ("the container has no CA bundle"). A lesson records the process of finding out, including what it cost — and cost is what makes it a priority.

Writing For Future You

beginner · ~12 min — Everything you do rarely is something you will do badly next time — promoting a release, rotating a key, restoring a database from a backup.

Documentation Exercises

beginner · ~20 min — Documentation is a skill, and skills come from reps against a clock. These four exercises are small and finishable in one sitting each.

← 10. Quality · Home · Sidebar · 12. Rules Of Operation →