Technical Writing

Principles

• Write for a senior engineer maintaining this in 6 months with no prior context.
• Document why, not what. The code shows what. Comments and docs explain the intent, the trade-offs, the non-obvious constraints.
• Concision over completeness. A short doc that gets read beats a long doc that doesn't.
• English by default. French only if explicitly requested.
• Plain Markdown. No HTML, no custom themes, no emoji in technical docs.

What NOT to document

These are wastes of tokens that degrade trust in the documentation:

• Obvious code behavior: # increment counter above counter += 1
• Repetition of the function signature in the docstring
• Historical narrative: "We used to do X but now we do Y because..." — put that in an ADR
• Aspirational statements: "This module will eventually support..." — document what exists
• Author name and date in file headers — that's what git blame is for