Writing Better Technical Documentation

Most technical docs fail for the same reason: they were written for the person who wrote them, not the person who has to read them. The author already knows the system, so they document the parts that were interesting to build instead of the parts that are confusing to use.

Good documentation is an act of empathy. You are trying to get an idea out of your head and into someone else's with as little friction as possible. Everything below is in service of that one goal.

Know your reader

Before writing a single line, answer three questions: who is reading this, what are they trying to do, and how much do they already know?

A person landing on your docs is almost never reading for pleasure. They have a job to do and your page is in the way. They are scanning, not reading — looking for the one code block or the one sentence that unblocks them. Write for the scanner.

Concretely, that means:

• Put the most important thing first. Do not bury the install command under three paragraphs of history.
• Assume they arrived from a search engine, not from page one. Every page should stand on its own.
• Match their vocabulary. If your users say "log in" and your code says "authenticate the principal", the docs say "log in".

A useful trick: imagine one specific person — a new teammate, a frustrated user — and write the whole page as if answering their exact question. Generic docs written for "everyone" tend to help no one.

The four kinds of documentation

Not all docs are the same, and mixing them up is the single most common structural mistake. The Diátaxis framework splits documentation into four types, each with a different job:

The mistake is writing a "tutorial" that is secretly a wall of reference tables, or a reference page that keeps stopping to explain concepts. Keep them separate. A tutorial holds the reader's hand and guarantees success; a reference is exhaustive and dry on purpose so people can look things up fast.

You do not need all four for a small project. But knowing which one you are writing keeps a single page focused.

Structure a page so it can be scanned

Readers skim in an F-shaped pattern: down the left edge, reading headings, stopping only where something catches. Structure the page to survive that.

• Lead with a one-sentence summary of what the page covers.
• Use descriptive headings. "Configuring the cache" beats "Configuration". Someone should be able to read only your headings and understand the shape of the page.
• Keep paragraphs short — two to four sentences. A wall of text signals "this will be hard" before a word is read.
• Use lists for steps and options. Prose is for ideas; lists are for enumerations.
• Front-load sentences. Put the point at the start: "To reset your password, click…" not "If you happen to find yourself needing to reset your password, you can click…".

A table of contents helps once a page passes a few screens. If a page needs more than about seven top-level sections, it is probably two pages.

Show, don't just tell

Nothing builds confidence like a working example. For most technical readers, one good code sample is worth three paragraphs of description.

Make examples copy-pasteable and complete. A snippet that references three undefined variables is worse than no snippet, because now the reader has to debug your docs. Show the imports. Show the expected output.

# Install and run in one go
npm install lexicon-cli
lexicon build ./notes --out ./dist
# → Built 42 pages in 1.3s

When you show output, show real output. Fabricated results that do not match what the tool actually prints erode trust the moment someone runs the command.

For anything with more than one step, number the steps and put exactly one action in each. If a step has an "and", it is usually two steps. Tell the reader how to check it worked — the "you should see…" line is what turns a nervous beginner into a confident one.

Write clearly

Clear writing is mostly about removing things.

• Prefer short words. "Use", not "utilize". "Help", not "facilitate".
• Cut hedges. "This basically just sort of handles the request" is "This handles the request".
• Use active voice and name the actor. "The server validates the token" is clearer than "The token is validated".
• Define a term once, then use it consistently. Do not call the same thing a "job", a "task", and a "run" on one page.
• Be concrete. "Returns quickly" means nothing; "returns in under 10ms" means something.

Read it out loud before publishing. Your ear catches tangled sentences your eye skims past. If you run out of breath, the sentence is too long.

Keep docs alive

Documentation rots. Code changes, the docs do not, and every wrong instruction teaches readers to distrust the whole site. Stale docs are often worse than missing docs, because missing docs at least do not lie.

A few habits keep docs honest:

• Treat docs as part of the change. A pull request that changes behavior is not done until the docs match. Reviewers should block on it.
• Keep docs in the repo, next to the code, in version control. Docs that live in a separate wiki drift almost immediately.
• Test your examples. If a code sample can be run in CI, run it. Broken example code is the fastest way to lose credibility.
• Add a "last updated" date and owner. A visible date lets readers judge staleness themselves.
• Delete aggressively. A page describing a feature that no longer exists should be removed, not left to mislead.

The best signal for what to write next is your support channel. Every question asked twice is a documentation gap. Answer it once in the docs and link to it forever.

Common mistakes

• Documenting the code instead of the task. Users care about "how do I upload a file", not a tour of your class hierarchy.
• Assuming context the reader lacks. The curse of knowledge: you forgot what it was like not to know. Have a newcomer read it.
• One giant page. Everything on a single scroll is impossible to link to and impossible to scan. Split by task.
• No examples, or fake examples. Abstract description without a runnable sample leaves the reader guessing.
• Screenshots of code and text. They cannot be copied, searched, or read by screen readers, and they go stale silently. Use real text.
• Writing once and never revisiting. Docs are a product, not a launch task.
• Burying the answer. If the fix is one command, that command goes near the top, not after the backstory.

Checklist

Before you publish a page, check:

• The first sentence says what the page is for.
• Headings are descriptive and skimmable on their own.
• It is clearly one type: tutorial, how-to, reference, or explanation.
• Every code example is complete and actually runs.
• Expected output is shown where it helps.
• Jargon is defined or avoided; terms are used consistently.
• Paragraphs are short and sentences are front-loaded.
• There is a visible last-updated date and an owner.
• You read it out loud and it did not make you wince.

Keep learning

The single best resource is the Diátaxis framework — read it once and you will never confuse a tutorial with a reference again. Google's Technical Writing courses are free, short, and practical. Write the Docs maintains a warm community and a large guide collection worth browsing.

For the mechanics of clear prose, William Zinsser's On Writing Well is old but unbeaten, and the classic Elements of Style is a 20-minute read that will improve every sentence you write for the rest of your life.

Then practice on your own projects. Pair this with How to Structure a Software Project — a well-organized codebase is far easier to document — and with Understanding REST APIs if you are documenting an interface others will call.