Most technical writing is bad. Not because engineers can't write—because they optimize for the wrong things.

Here's how to write technical content that actually helps people.

Start With the Problem

Don't start with what your thing does. Start with why someone would care.

Bad:

MyTool is a CLI utility that processes JSON files and outputs CSV.

Good:

Need to convert JSON to CSV? MyTool does it in one command.

The reader's question is always "why should I care?" Answer it first.

Front-Load Information

Put the most important thing first. Every time.

Structure your content like a newspaper, not a novel:

  1. The answer
  2. The details
  3. The edge cases
  4. The history (if anyone cares)

Most readers won't finish. Make sure they get value even if they stop early.

Use Examples

Abstract explanations are hard to follow. Examples are easy.

Bad:

The function accepts an optional callback parameter that is invoked with the result upon completion.

Good:

# Basic usage
result = fetch_data("users")
 
# With callback
fetch_data("users", callback=lambda r: print(f"Got {len(r)} users"))

Show, don't tell. Then tell if needed.

Write Short Sentences

Long sentences with multiple clauses that introduce several concepts while also providing context and caveats are hard to parse.

Short sentences are easy.

One idea per sentence. Break up complexity.

Use Headers

Walls of text are intimidating. Headers let readers scan.

Good headers:

  • Tell you what's in the section
  • Work as a table of contents
  • Help readers find what they need

Someone should be able to skim your headers and understand the structure.

Be Direct

Technical writing isn't the place for hedging.

Bad:

You might want to consider possibly using environment variables for configuration, as this could potentially be a good practice.

Good:

Use environment variables for configuration.

Say the thing. If there are caveats, state them clearly after.

Delete Words

First drafts have too many words. Edit ruthlessly.

  • "In order to" → "to"
  • "Due to the fact that" → "because"
  • "At this point in time" → "now"
  • "It is important to note that" → (just say the thing)

Every word should earn its place.

Know Your Audience

A tutorial for beginners reads differently than API docs for experts.

For beginners:

  • Explain concepts
  • Don't assume knowledge
  • Show every step

For experts:

  • Get to the point
  • Assume context
  • Focus on what's different

One document rarely serves both. Pick your audience.

Test Your Writing

The best way to know if documentation works: watch someone use it.

  • Do they get stuck?
  • Do they skip sections?
  • Do they ask questions you thought you answered?

If you can't watch users, have a colleague try to follow your docs cold.

Common Mistakes

Burying the lede. Three paragraphs of context before the actual information.

Assuming knowledge. "Just use Docker" (what if they don't know Docker?).

Over-explaining. Ten paragraphs when two would do.

No examples. All theory, no practical application.

Outdated content. Nothing kills trust like wrong instructions.

My Process

  1. Write fast, don't edit
  2. Add examples for every concept
  3. Delete half the words
  4. Add headers to break up sections
  5. Read it aloud (catches awkward phrasing)
  6. Have someone else try to follow it

The last step catches the most issues.

The Goal

Good technical writing is invisible. Readers get what they need and move on.

Bad technical writing makes them think about the writing—parsing sentences, hunting for information, re-reading to understand.

Write so clearly that the writing disappears.

React to this post: