Documentation Nobody Reads is Worse Than No Documentation

I've created beautiful Confluence spaces that nobody visited. 50-page PRDs that sat untouched. API docs that developers ignored in favor of just reading the code.

I've also written docs that teams referenced daily. That onboarded new engineers in days instead of weeks. That prevented the same questions from being asked 100 times.

The difference isn't the tool or the formatting. It's understanding what documentation is actually for.

Why Most Documentation Fails

It's not because people don't like reading. It's because:

Written too early: Documenting something that's still changing is wasted effort. You'll need to rewrite it, and the old version will confuse people.

Written for the wrong audience: Technical specs written like marketing copy. User guides with implementation details. Nobody gets what they need.

Not findable: Great docs buried in folder structures nobody understands. If people can't find it in 30 seconds, it doesn't exist.

Not maintained: Docs from 2 years ago describing how the system used to work. Worse than no docs because it actively misleads.

What Actually Works

1. Write When Stable, Not When Starting

Don't document while building. You'll waste time on things that change.

Document when:

• The feature is launched and stable
• The API contract is finalized
• The process has been followed 3+ times
• People are asking the same questions repeatedly

That last one is my trigger. Third time someone asks "how does X work?" — it's time to write it down.

2. One Doc, One Purpose

Each document should answer one question:

• "How do I use this API?" → API reference
• "Why did we build it this way?" → Architecture decision record
• "How do I set up my dev environment?" → Getting started guide
• "What does this feature do?" → User guide

Mixing purposes = confused readers = unused docs.

3. Start With The Problem

Don't start with "This document describes..." Nobody cares.

Start with:

• What problem does this solve?
• Who is this for?
• What will you be able to do after reading this?

Get to the useful part in the first paragraph.

4. Keep It Scannable

Nobody reads documentation top to bottom. They scan.

Use:

• Clear headings
• Bullet points
• Code examples
• Screenshots where helpful

If I can't find what I need in 30 seconds of scanning, the doc failed.

My Documentation Stack

Different docs for different purposes:

README files: Live with the code. Setup instructions, quick start, common tasks. If a dev needs it while coding, it goes here.

Wiki/Notion: Process docs, onboarding guides, meeting notes. Stuff that changes regularly and needs to be searchable.

Architecture Decision Records (ADRs): Why we made technical decisions. Invaluable when someone asks "why didn't we just..." 6 months later.

API docs: Auto-generated from code when possible. Manual docs for the parts that need more context.

Runbooks: Step-by-step guides for operational tasks. "If X happens, do Y." Critical for on-call.

The Minimum Viable Docs

Starting a new project? Here's what you actually need:

1. README — How to run the project locally
2. Architecture overview — One-page diagram of how things connect
3. API reference — If you have an API
4. Deployment guide — How to ship to production

That's it. Everything else can wait until there's demand.

What I Don't Document

Obvious code: If the code is readable, don't add comments explaining what it does. Comments should explain why, not what.

Things that change weekly: Document processes after they're stable. Premature docs create maintenance burden.

Tribal knowledge that's actually just one person's opinion: "We always do X because Bob said so" isn't documentation, it's politics.

The Real Test

Good documentation passes this test:

A new team member can get productive without asking someone to explain what the docs already cover.

If new people still need hand-holding for things that should be documented, your docs are failing.

Not because documentation is hard. Because documentation that nobody uses is just noise.