Documentation Standards

Documentation exists to serve readers, not to demonstrate knowledge.

Core Principle

Every documentation decision starts with: "What does the reader need?"

Critical Rules

8 Quality Dimensions

1. Clarity

2. Accuracy

3. Conciseness

4. Structure

5. Usability

6. Consistency

7. Completeness

8. Examples

Document Types

README

Purpose: First impression. "What is this? Should I use it? How do I start?"

Required sections:

• Name and description
• Installation
• Basic usage
• License

WRONG:

## Getting Started

Welcome to our project! We're excited that you're interested...

CORRECT:

## Quick Start

Requires Node.js 18+.

npm install mylib

API Reference

Purpose: "What can I call? What do I send? What do I get back?"

Required for each endpoint:

• Parameters with types
• Return type
• Error codes with causes AND solutions
• Request/response examples

WRONG:

### authenticate()
Returns: True if successful

CORRECT:

### authenticate(username, password, mfa_code?)

**Returns:** AuthToken with .token and .expires_at
**Raises:** InvalidCredentialsError, MFARequiredError

**Example:**
try:
    token = authenticate("user@example.com", "pass123")
except MFARequiredError:
    token = authenticate("user@example.com", "pass123", "123456")

Tutorial

Purpose: Guided learning from start to finish.

Required:

• Numbered steps
• Each step: intro → content → verification
• Working end result
• Time estimate

Changelog

Purpose: "What changed? When? Does it affect me?"

Required:

• Semantic versioning
• ISO dates
• Categories: Added, Changed, Fixed, Removed
• Human-written (not commit logs)

Code Sample Rules

WRONG - Incomplete

client.send(message)

Missing: imports, initialization, error handling, output

CORRECT - Complete

import { Client, Message } from 'mylib';

const client = new Client({ apiKey: process.env.API_KEY });
const msg = new Message({ to: "user@example.com", body: "Hello" });

try {
  const result = await client.send(msg);
  console.log(`Sent: ${result.id}`); // Output: Sent: msg_123
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log(`Rate limited. Retry after ${error.retryAfter}s`);
  }
}

Code Sample Checklist

• Imports included
• Initialization shown
• Error handling included
• Output demonstrated
• Language tag on code block
• Copy-paste ready
• Tested and verified

Writing Principles

Sentence Level

Paragraph Level

Document Level

Error Messages

Every error message answers:

1. What went wrong? (Specific)
2. How do I fix it? (Actionable)

WRONG:

Authentication failed

CORRECT:

Authentication failed. Check that your API key is valid at Settings > API Keys.

Integration

Review Checklist

User-Centered Design

• Target user identified
• User goal stated
• Prerequisites listed
• Success criteria clear
• Next steps offered

Content Quality

• First sentence explains purpose
• Active voice used
• Technical terms defined
• Assumptions stated explicitly

Code Examples

• Imports included
• Complete and runnable
• Output shown
• Error handling included
• Tested and verified

Accuracy

• API signatures match code
• Examples syntactically correct
• Version numbers current
• Links resolve

Anti-Patterns