Documentation and knowledge capture

Skill 11: Documentation & Knowledge Capture

Purpose: Write the durable explanations that let others (and future-you) understand, use, and safely change your work. Use when: Anything that will be used or maintained by someone else, revisited later, or whose "why" isn't obvious from the work itself. Don't use when: A throwaway no one will read again. Don't document what the work already makes obvious, that's noise, not knowledge.

---

Why this matters

Undocumented work is knowledge trapped in one head. The moment that person forgets, leaves, or is a weak model whose context resets, the knowledge is gone and the work becomes a black box no one dares touch. But over-documentation is also a real failure: reams of docs that restate the obvious, drift out of date, and actively mislead. Good documentation is selective, it captures exactly the knowledge that isn't recoverable from the work itself, and nothing else.

This skill is distinct from context-and-knowledge-management: that's notes for you during the task; this is durable knowledge for others after it.

The core principle

Document the knowledge that the work cannot show on its own: above all, the "why." Anyone can read what the code does by reading it. What they can't recover is why it's that way, how to use it, and what they must not break. Capture those; skip the rest.

---

The document types that earn their keep

Most work needs only the first two. Add others as the audience demands.

1. The "how to use it" doc (README)

The entry point. A newcomer should get from zero to a working result using only this. Include:

• What it is / what problem it solves: one paragraph.
• How to run it: the exact commands, copy-pasteable, that actually work.
• A minimal example: real input → real output.
• Key options / configuration: the ones people actually need.
• Gotchas: the non-obvious things that will trip people up.

Test it by having someone (or yourself, cold) follow it exactly. If a step is missing or wrong, the doc has a bug.

2. The "why it's like this" record (decisions & rationale)

The highest-value, most-neglected documentation. For any non-obvious choice, record: what was decided, why, what was rejected, and when to revisit. This is what stops future-you from either breaking things you don't understand or wasting days re-deciding a settled question. (Format in first-principles-reasoning.) Keep them together (a decisions log / ADRs) so they're findable.

3. Inline explanation (comments)

Only for what the code can't say itself:

• Why, not what. # retry 3×: the upstream API rate-limits bursts is gold. # increment i by 1 is noise.
• Constraints and traps the next reader can't see: "must stay in sync with the schema in X," "do not reorder, Y depends on Z happening first," "this looks wrong but handles the leap-year edge case."
• Never narrate the obvious, never explain that your change is correct (that's for the review, not the code), never leave commented-out code.

4. Reference (when there's a real API/interface)

For a library or tool others build on: document each public function/command, what it does, inputs, outputs, errors, one example. Only for the public surface; internal details are free to change and shouldn't be pinned down in prose.

---

Writing principles

Write for the reader who knows nothing

Assume the reader lacks all the context you have right now. The codename you invented, the shorthand, the thing "everyone knows": spell it out. You are writing for someone who stepped away and is catching up, or a model whose memory reset.

Make it findable and skimmable

Knowledge no one can find is undocumented. Put docs where people look (a README at the root, comments at the code, decisions in one log). Use clear headings and short sections so a reader can jump to what they need without reading it all.

Keep it close to the work and current

Docs far from what they describe rot fastest. Prefer documentation near the thing (README beside the code, comment beside the line). When you change the work, update its docs in the same motion: a wrong doc is worse than a missing one because it's trusted.

Be concise and concrete

One good runnable example beats three paragraphs of description. Show the actual command, the actual output. Cut every sentence that doesn't help the reader do something.

Prefer self-documenting work, then document the rest

The best documentation is work that doesn't need much: clear names, obvious structure, small pieces (maintainability-and-extensibility). Make the thing readable first; then document only the knowledge that still isn't visible. Don't use comments to rescue unclear code, clarify the code.

---

Worked example

Situation: You built the API-cost CLI. What deserves documentation?

Over-documented (noise): A comment on every line (# open the file, # loop over rows), a 10-page manual for a 50-line script, a description of every internal helper.

Right-sized:

• README: "Summarizes API costs from your provider's CSV export. Run: python costs.py export.csv [--json]. Example: [3-row input → table output]. Gotcha: the export includes a TOTAL summary row which the tool ignores, if your export format differs, check parse_rows()."
• Decision log: "Chose CSV-in / stdout-out over a database because volume is tiny and users want a quick one-shot report. Revisit if we need history across months."
• One inline comment: # skip the provider's appended TOTAL row, it's not a transaction on the exact filter line, because that's non-obvious and someone will otherwise "fix" it and reintroduce the bug from Skill 06.

Three small artifacts capture everything a future maintainer actually needs, and nothing they don't.

---

Common failure modes

Failure	Fix
No docs: knowledge trapped in one head	Write at least a README + decision log.
Documenting what instead of why	Comment the reason and the constraint, not the mechanics.
Over-documentation / restating the obvious	Cut anything recoverable from reading the work.
Docs drift out of date	Update docs in the same change as the work; delete wrong docs.
Assuming reader context	Write for someone who knows nothing; spell out shorthand.
Commented-out code left as "history"	Delete it; version control is the history.
Docs no one can find	Put them where people look; make them skimmable.

Red flags: stop and capture (or stop over-capturing)

• A non-obvious decision is about to be lost because it's only in your head.
• Someone couldn't run your work from the README alone.
• You're writing a comment that just restates the line below it.
• You changed the work and left the docs describing the old behavior.
• There's a "clever" or surprising piece of work with no note explaining why.
• You're documenting internal details that are free to change.

Definition of done for this skill

• A newcomer can use the work from the README alone (tested cold).
• Non-obvious decisions are recorded with their reasons.
• Comments explain why and flag constraints, not narrate what.
• Docs live close to the work and match its current state.
• Nothing is documented that the work already makes obvious.

See also

• context-and-knowledge-management, working notes that become durable docs.
• first-principles-reasoning, the decision-record format.
• maintainability-and-extensibility, self-documenting work reduces how much you must write.