Best Practices

Great documentation is the difference between users succeeding or struggling with your product. This guide covers proven practices for writing documentation that truly helps.

Writing Principles

1. Know Your Audience

Before writing, consider:

• Who is reading? (beginners, experts, both?)

• What do they need to accomplish?

• When will they read this? (learning, troubleshooting?)

Adjust your language and depth accordingly.

2. Start with the Goal

Every page should answer: "After reading this, the user will be able to..."

      

        markdown
        
          
          
        
      
    ❌ "This page explains the authentication system."

✅ "After reading this, you'll be able to authenticate
   users and manage sessions in your application."

3. Be Concise

Respect readers' time:

• Cut unnecessary words

• Use short paragraphs

• Break up long sections

• Get to the point quickly

4. Show, Don't Just Tell

Pair explanations with examples:

      

        markdown
        
          
          
        
      
    ❌ "Use the `fetch` function to make API requests."

✅ "Use the `fetch` function to make API requests:

   ```javascript
   const response = await fetch('/api/users');
   const users = await response.json();
   ```"

Structure and Organization

Information Architecture

Organize documentation logically:

      

        plaintext
        
          
          
        
      
    1. Getting Started (onboarding)
   ├── Introduction
   ├── Installation
   └── Quick Start

2. Core Concepts (understanding)
   ├── Architecture
   ├── Key Terms
   └── How It Works

3. Guides (doing)
   ├── Common Tasks
   ├── Advanced Usage
   └── Best Practices

4. Reference (looking up)
   ├── API Reference
   ├── Configuration
   └── Troubleshooting

Page Structure

Each page should have:

1. Clear title - What is this page about?

2. Introduction - Why should I read this?

3. Prerequisites - What do I need first?

4. Content - The main information

5. Next steps - Where do I go from here?

Use Headings Effectively

      

        markdown
        
          
          
        
      
    # Page Title (one per page)

## Major Sections (main topics)

### Subsections (supporting details)

#### Minor Sections (rarely needed)

Writing Style

Active Voice

      

        markdown
        
          
          
        
      
    ❌ "The configuration file should be created in the root directory."

✅ "Create the configuration file in the root directory."

Present Tense

      

        markdown
        
          
          
        
      
    ❌ "The function will return a promise."

✅ "The function returns a promise."

Second Person

      

        markdown
        
          
          
        
      
    ❌ "Users can configure the settings..."

✅ "You can configure the settings..."

Consistent Terminology

Create and follow a style guide:

Code Examples

Make Them Runnable

      

        javascript
        
          
          
        
      
    // ❌ Incomplete example
fetch('/api/users')

// ✅ Complete, runnable example
async function getUsers() {
  const response = await fetch('/api/users', {
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    }
  });

  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  return response.json();
}

Show Expected Output

      

        javascript
        
          
          
        
      
    const user = await getUser(123);
console.log(user);

// Output:
// {
//   id: 123,
//   name: "Alice",
//   email: "alice@example.com"
// }

Include Error Handling

Show how to handle things going wrong:

      

        javascript
        
          
          
        
      
    try {
  const data = await fetchData();
} catch (error) {
  if (error.status === 401) {
    // Handle unauthorized
  } else if (error.status === 404) {
    // Handle not found
  } else {
    // Handle other errors
  }
}

Visual Elements

When to Use Tables

Tables work well for:

• Comparing options

• Parameter documentation

• Feature matrices

      

        markdown
        
          
          
        
      
    | Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | User's display name |
| `email` | string | Yes | Valid email address |
| `role` | string | No | Default: "user" |

When to Use Lists

Lists work well for:

• Steps in a process

• Features or benefits

• Prerequisites

Callouts and Warnings

Highlight important information:

Note: This feature requires version 2.0 or higher.

Warning: This action cannot be undone.

Tip: Use keyboard shortcuts to speed up your workflow.

Maintenance

Keep Documentation Updated

• Review docs with each release

• Add "Last updated" timestamps

• Remove deprecated content promptly

Version Your Documentation

• Match docs versions to product versions

• Clearly mark version-specific features

• Maintain docs for supported versions

Gather Feedback

• Add "Was this helpful?" prompts

• Monitor support tickets for doc gaps

• Track popular search queries

Common Mistakes to Avoid

1. Assuming Knowledge

      

        markdown
        
          
          
        
      
    ❌ "Configure the OAuth callback URL."

✅ "Configure the OAuth callback URL. This is the URL
   where users are redirected after authenticating.
   For local development, use: http://localhost:3000/callback"

2. Wall of Text

Break up long content with:

• Headings

• Bullet points

• Code examples

• Images or diagrams

3. Outdated Screenshots

• Use text descriptions when possible

• Update screenshots with each UI change

• Consider automated screenshot tools

4. Missing Prerequisites

Always list what users need:

• Required software/versions

• Account setup steps

• Prior knowledge

5. Broken Links

• Regularly audit internal links

• Use relative URLs when possible

• Set up link checking in CI

Checklist for Every Page

Before publishing, verify:

• Title clearly describes the content

• Introduction explains the purpose

• Prerequisites are listed

• Code examples are complete and tested

• All links work

• Spelling and grammar are correct

• Page works in both light and dark mode

• Next steps guide readers forward