Technical Writing for Developers: A Practical Guide

Most developers write documentation the way they learned to write essays: long sentences, passive voice, lots of hedging. That approach fails for technical docs. Here's what actually works.

Write for Scanning

Readers don't read technical docs — they scan for the piece they need. Structure every page with that in mind.

Bad:

This section provides an overview of the configuration options that are available to users who wish to customize the behavior of the application.

Good:

Configuration Options

Write headings as outcomes, not topics: "Install the CLI" beats "Installation." "Fix authentication errors" beats "Troubleshooting."

The Four Types of Documentation

Don't mix types. A tutorial that also serves as a reference confuses both audiences.

Seven Rules for Writing Clearly

1. Use Active Voice

Passive: "The token is included in the Authorization header." Active: "Include the token in the Authorization header."

2. One Idea Per Sentence

Break complex sentences into two.

3. Second Person

Write to "you," not "the user." It feels more direct.

Distant: "The user should click Save." Direct: "Click Save."

4. Lead With the Verb in Steps

markdown
1. Open the terminal.
2. Run `npm install`.
3. Edit `config.json`.

Not: "1. The first thing to do is open the terminal."

5. Minimize Jargon

Define a term once, use it consistently. Never use two terms for the same thing.

6. Use Notes and Warnings Sparingly

markdown
> **Note:** This only applies to macOS.
> **Warning:** This action cannot be undone.

If every paragraph has a note, none stand out.

7. Cut Filler

• "In order to" → "To"
• "It is important to note that" → just say it
• "Please note" → delete it
• "This section will explain" → just explain it

Structuring a Good Reference Doc

Every reference page should answer:

1. What is it? (one sentence)
2. When would I use it?
3. What are the parameters/fields? (table)
4. What does a real example look like?
5. What are the errors/edge cases?

Minimum Viable Documentation Set

For a library or API, ship these first:

• README with install + quick start (under 2 minutes to first result)
• Getting Started guide with a real working example
• API reference for every public method/endpoint
• Changelog from version 1.0

Editing Checklist

• Every heading is an action or outcome
• Every code example is copy-pasteable and working
• No step requires undocumented prior knowledge
• Passive voice → active voice
• Tables used for 3+ items that would be prose lists
• Links point to the right sections

A Note on Documentation Debt

Undocumented behavior becomes expected behavior. Incorrect docs are worse than no docs — they erode trust. Schedule a quarterly docs review alongside dependency updates.

Open MarkGenie, paste in your function signature, and write one sentence explaining what it does. That's the hardest part — everything follows.