Write Documentation Like a Journalist

I’ve been writing documentation for years, and I’ve noticed something interesting: the best tech writers approach their work like journalists. They’re not just regurgitating information - they’re investigating, connecting dots, and telling a story. Here’s why this approach works and how you can use it.

The Parallels Between Journalism and Documentation

Journalists follow leads, dig deep, and piece together a narrative. Good documentation writers do the same thing. They don’t just list features - they uncover the ‘why’ behind each function and explain how it all fits together.

Take the React documentation, for example. It doesn’t just tell you what hooks are - it explains why they were created, how they solve common problems, and when you should (or shouldn’t) use them. That’s journalism in action.

When I’m writing docs, I start with a ‘lead’ - usually a key feature or concept. Then I ask questions:

1. Why was this feature added?
2. What problem does it solve?
3. How does it connect to other parts of the system?

This investigation often uncovers gaps in my understanding. That’s good! It means I’m finding the spots where users might get confused too.

Telling the Story

With all the pieces in place, it’s time to craft the narrative. Good documentation tells a story - it has a beginning (the problem), a middle (the solution), and an end (the implementation).

For example, instead of just saying “Use the cache() method to store results”, I might write:

“As your application scales, repeated database queries can become a bottleneck. The cache() method provides a simple way to store and retrieve frequently accessed data, significantly reducing load times under heavy traffic.”

This approach gives context, explains the ‘why’, and helps the reader understand when and how to use the feature.

Documenting a New API Endpoint

Here’s an introduction to explain the concept, followed by a shortened journalistic example:

When documenting APIs, it’s crucial to provide context and value, not just technical details. Let’s compare a basic approach with a more journalistic style:

Basic documentation:

1
# POST /api/v1/users
2
Creates a new user.

Journalistic approach:

1
# POST /api/v1/users
2
- Streamlined User Creation
3

4
# Why
5
Automates user setup, saving ~15 mins per user for large orgs.
6

7
# Key Features:
8
- Auto-role assignment by email domain
9
- Existing auth system integration
10
- Custom welcome emails
11

12
# Usage:

1
async function createUser(name: string, email: string) {
2
  const response = await fetch('/api/v1/users', {
3
    method: 'POST',
4
    headers: {
5
      'Authorization': 'Bearer YOUR_API_KEY',
6
      'Content-Type': 'application/json',
7
    },
8
    body: JSON.stringify({ name, email }),
9
  });
10
  return response.json();
11
}
12

13
const user = await createUser('John Doe', '[email protected]');
14
console.log(user);

1
# Watch out for:
2
- Email validation
3
- Rate limit: 100 requests/minute
4

5
# Coming soon:
6
Bulk user creation

This journalistic style provides context, highlights benefits, and anticipates user needs—all in a concise format. It turns dry technical info into a story about solving real problems.

Config Setting Example

When documenting configuration settings, it’s tempting to simply list the options and their basic functions. However, by adopting a more journalistic style, we can provide users with context, use cases, and potential impacts of each setting. This approach helps users make informed decisions about when and how to use these configurations.

Let’s compare a basic approach with a more journalistic style:

Basic documentation:

1
# DEBUG_MODE: boolean
2
Enables debug mode when set to true.

Journalistic:

1
# DEBUG_MODE: boolean
2

3
# Purpose:
4
Detailed logs for squashing bugs.
5

6
# Best for:
7
Development and prod issue investigation.
8

9
# Caution:
10
May impact performance in production.
11

12
# Pro tip:
13
Use with LOG_LEVEL for precision debugging.

In the journalistic approach, we’ve transformed a simple boolean flag into a story about problem-solving.

This style of documentation doesn’t just tell users what the setting does—it guides them on how to use it effectively. It anticipates questions and provides valuable context, turning dry technical information into a more engaging and informative resource.

By applying this approach consistently across your configuration documentation, you create a more user-friendly experience that can significantly reduce the learning curve for new developers and provide valuable insights even for experienced users.