Technical Writing for Developers

Writing docs, READMEs, and technical posts is a skill. Here's how to get better at it.

Why It Matters

You can write the best code in the world. If no one understands how to use it, it doesn't matter.

Good technical writing:

  • Helps users succeed
  • Reduces support burden
  • Makes you a better communicator
  • Builds your reputation

Know Your Audience

Before writing, ask:

  • Who will read this? (Users? Developers? Both?)
  • What do they already know?
  • What do they need to accomplish?

A README for a CLI tool reads differently than API documentation.

Structure First

People scan before they read. Make scanning easy:

## Installation

One command:

npm install my-tool


## Quick Start

Get running in 30 seconds:

1. Install the package
2. Import it
3. Call the function

## API Reference

### `doThing(options)`

Does the thing.

**Parameters:**
- `options.foo` (string, required) - The foo to bar
- `options.baz` (number, optional) - Defaults to 42

Write Simply

  • Short sentences
  • Common words
  • Active voice
// ❌ Verbose
The function that is being called will, upon completion, return a value 
that represents the user object as retrieved from the database.

// ✅ Simple
The function returns the user from the database.

Show, Don't Tell

Every explanation needs an example:

// ❌ Just description
The map function transforms each element of an array.

// ✅ With example
map transforms each element:

[1, 2, 3].map(n => n * 2) // Returns: [2, 4, 6]

Be Scannable

  • Use headings
  • Use bullet points
  • Use code blocks
  • Bold key terms

Walls of text get skipped.

Get Feedback

Before publishing:

  • Read it out loud
  • Have someone else read it
  • Try following your own instructions

Fresh eyes catch what you missed.

Practice

Technical writing is a muscle. Write more:

  • Document your projects
  • Write blog posts
  • Answer Stack Overflow questions
  • Create internal docs at work

Every piece of writing makes you better at the next one.

Back to Journal