writing-documentation

Writing Documentation

Overview

Documentation is code for humans. If humans can't understand your system, it might as well not exist. Bad documentation is worse than no documentation — it actively misleads.

Core principle: Write for the reader who has zero context, is in a hurry, and will judge your entire project in 30 seconds.

The Iron Law

NO PUBLIC API WITHOUT DOCUMENTATION. NO COMPLEX LOGIC WITHOUT COMMENTS. NO DOCUMENTATION THAT DOESN'T MATCH THE CODE.

When to Use

• Creating a new project or module
• Adding public APIs or exported functions
• After major architectural changes
• Before onboarding new team members
• When someone asks "how does this work?" (a documentation failure signal)
• When you struggle to explain something (sign it needs better docs)
• Before launching or publishing

When NOT to Use

• Auto-generated API reference from types (tools like TypeDoc handle this)
• Comments that restate what the code does (// increment i by 1)
• Documentation for internal implementation details that change frequently

Anti-Shortcut Rules

YOU CANNOT:
- Say "documentation is done" — verify every code example runs, every link works, every setup step succeeds
- Copy-paste code examples without testing them — stale examples are worse than no examples
- Document what you PLAN to build — only document what EXISTS and WORKS
- Write "see code for details" — if the reader needs code, the documentation failed
- Skip the Quick Start — the first 60 seconds determines if anyone reads further
- Leave TODO or "Coming soon" in documentation — remove it or write it now
- Document for yourself — document for someone who joins tomorrow
- Skip testing setup instructions — run them from scratch in a clean environment

Common Rationalizations (Don't Accept These)

Rationalization	Reality
"The code is self-documenting"	Code explains WHAT and HOW. It never explains WHY, trade-offs, or business rules.
"Nobody reads documentation"	Nobody reads BAD documentation. Good docs with a Quick Start get read.
"We'll document it later"	Later = never. Document as you build.
"It's an internal project"	Internal projects have the highest onboarding cost. Your future self is "internal."
"The types are the documentation"	Types tell you the shape of data. They don't tell you when to use it, what happens on error, or why this API exists.
"Just ask the team"	That person will leave, be on vacation, or be too busy. Docs scale, people don't.
"Too many changes to keep docs updated"	Then automate what you can and document stable interfaces, not implementation details.