The average documentation page: written once, read never. Someone spends hours creating it. It grows stale immediately. It sits untouched until deleted years later.
This isn't a documentation problem. It's a weight problem.
Heavy documentation is costly to create. Costly to maintain. Costly to read. The cost exceeds the value, so documentation gets skipped, ignored, or abandoned.
Lightweight documentation inverts this. Cheap to create. Cheap to maintain. Useful enough to read. Actually gets used.
Why Heavy Documentation Fails
**Too costly to create.** If documenting takes an hour, it competes with an hour of productive work. The productive work wins.
**Too costly to maintain.** Heavy documentation has more surface area to grow stale. Maintenance burden exceeds value.
**Too costly to read.** Long documents take time. Readers skim or skip. The value never reaches readers.
**Wrong level of detail.** Comprehensive documentation includes everything. Readers need specific things. Useful content is buried.
Heavy documentation: lots of effort, little value, gets ignored.
Principles of Lightweight
Minimum Viable Documentation
What's the least that provides the required value? Write that. Not more.
Every additional word is maintenance burden and reading load.
Write for Retrieval, Not Reading
People don't read documentation linearly. They search for specific answers.
Clear titles. Scannable headings. Keywords that match searches. Standalone sections.
Document at Decision Points
Don't document everything. Document decision points — where understanding matters.
Why was this approach chosen? What alternatives were rejected? What risks accepted?
Skip obvious implementation details. Skip things derivable from code.
Integrate, Don't Separate
Documentation that lives separately from what it describes grows stale.
Keep docs near code. Attach context to prompts. Put decisions in the repo.
Make It Easy to Update
If updating is hard, it won't happen.
Simple formats. Easy editing. No approval workflows for minor changes.
Practical Formats
The One-Paragraph Document
For simple context, one paragraph is enough:
"Profile update feature: Users update profile info via form that PATCHes to /api/profile. Validation client-side for immediacy, server-side for security. Email changes allowed per decision 2025-01-09 because [reason]."
Done. Two minutes to write. Thirty seconds to read.
The Decision Log Entry
For recording decisions without full ADRs:
| Date | Decision | Why | Owner | |------|----------|-----|-------| | 11-16 | Use streaming | Latency needs | @sarah |
Quick to add. Quick to scan.
The Minimal README
Most READMEs do too much. Focus:
"Component: [Name] Does: [One sentence] Use: [Minimal example] Decisions: [Link] Owner: [Contact]"
If someone needs more, they can ask.
The Inline Comment
Sometimes the best doc is in the code:
// Using retry logic — external API is flaky // See decision log 2025-11-16 // Owner: @mike
Context exactly where needed.
What to Document
Always
- Decisions that affect others
- Non-obvious reasoning
- Risk acceptances
- Intent
Sometimes
- How things work (if not obvious from code)
- Implementation details (if surprising)
- Status and history (if tracking matters)
Rarely
- The obvious
- The temporary
- The derivable
Making It Stick
**Part of workflow.** Documentation isn't separate. It's part of finishing work.
**Low friction.** Simple tools, no permissions, easy templates.
**Pruned regularly.** Dead documentation is worse than none. Remove stale content.
**Used visibly.** Reference the docs. Point people to them. Demonstrate value.
---
Less documentation, actually read, beats more documentation, never read.