Writing Documentation That People Actually Read

documentation best-practices

Practical tips for writing technical documentation that developers will actually use.

Good documentation is one of the most underrated skills in software engineering. Here are some principles I’ve found useful.

Start with the why

Before writing a doc, ask: who is this for, and what problem are they trying to solve?

A README that starts with installation instructions is fine. A README that starts with “This library solves X problem by doing Y” is better.

Keep it short

Developers skim. Respect their time:

  • Use headers to break up content
  • Put the most important info first
  • Code examples > long explanations

Show, don’t tell

# Bad: "Use the fetch function to retrieve data"
# Good:
import asyncio
from mylib import fetch

async def main():
    data = await fetch("https://api.example.com/users")
    print(data)  # => [{"id": 1, "name": "Alice"}, ...]

asyncio.run(main())

A working example is worth a thousand words.

Docs are code

Treat documentation like code:

  • Version it alongside the code it describes
  • Review it in PRs
  • Test code examples to make sure they actually work

The best documentation is the one that stays up to date because it lives close to the code.

← Back to all posts