On writing documentation

Technical documentation should be easy to understand. Here’s what works:

Skip the jargon

Write “This lets users log in” instead of “This facilitates authentication via credentials.” When you use clear words, more people can use your code.

Use direct statements

Write exactly what something does once, then move on. Think “The timeout sets how long to wait.” Your readers will grasp the concept faster without repeated explanations.

Break down complex ideas

Start simple: “Check if a user is logged in” before jumping to “Handle session tokens.” Each piece builds naturally on the last.

Lead with examples

Show a working code snippet before explaining how it works:

// Clear example
const user = await getUser(id)

// Instead of lengthy setup and context
const options = {...}
const client = new Client(...)
const user = await client.users.findOne(...)

Keep code samples minimal

Remove any code that doesn’t directly demonstrate your point. A 3-line example is often better than a 20-line one.

Structure visually

Use whitespace to separate ideas. Let concepts breathe on the page rather than cramming them together with transitions and segues.

Write in active voice

Say “The function returns a string” instead of “A string is returned by the function.” Active voice makes it clear what does what.

Don’t include error handling

Focus on the happy path. Errors should be handled after the reader understands the main concept. For example:

// Instead of:
try {
  await saveUser(data)
} catch (error) {
  // Show how to handle common errors
  if (error.code === 'DUPLICATE_EMAIL') {
    // Handle duplicate email
  }
}

// Write:
await saveUser(data)

These techniques take practice. Test your writing by asking: Could I explain this in a tweet? If not, make it simpler.