Documentation Style

Documentation Style & Standards

Provides documentation patterns for Markdown formatting, structure, voice/tone, and technical writing best practices across user guides, API docs, and code comments.

Description

This skill teaches documentation agents how to create clear, consistent, well-structured documentation following industry best practices. It covers Markdown conventions, information architecture, writing style (active voice, concise sentences), code examples, and accessibility considerations for documentation.

When to Use

• Writing user-facing documentation
• Creating API reference guides
• Documenting architecture decisions
• Writing README files
• Creating onboarding materials
• Updating changelogs

When NOT to Use

• Do not use for inline code comments in implementation files — those follow language-specific instructions.
• Do not use for commit messages or PR descriptions — use the git-operations skill instead.

Entry Points

Trigger Phrases: "write documentation", "create user guide", "document this API", "update README", "onboarding guide"

Context Patterns: New feature completion, API endpoint additions, architecture changes, refactoring tasks

Core Knowledge

Document Structure

Standard Sections:

1. Title/Overview: What is this? (1-2 sentences)
2. Prerequisites: What do you need first?
3. Quick Start: Fastest path to hello world (5 min)
4. Usage: Core functionality with examples
5. Configuration: Options and settings
6. API Reference: Detailed method/endpoint documentation
7. Troubleshooting: Common issues and solutions
8. FAQs: Frequently asked questions
9. Resources: Related links and references

Markdown Conventions

# H1: Document Title (one per file)

Brief overview paragraph explaining purpose.

## H2: Major Section

Content with **bold** for emphasis, *italic* for terms, `code` for technical elements.

### H3: Subsection

- Bullet lists for unordered items
- Keep items parallel in structure

1. Numbered lists for sequential steps
2. Start each item with action verb
3. Include expected outcomes

### Code Blocks

\`\`\`javascript
// Always specify language for syntax highlighting
const example = 'Use comments to explain why, not what';
\`\`\`

### Tables

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Data | Data | Data |

### Links

[Descriptive link text](https://example.com) not "click here"

### Images

![Alt text describing image content](path/to/image.png)

Writing Style Guidelines

Do:

• ✅ Use active voice: "The function returns..." (not "is returned by")
• ✅ Be concise: "Use X to do Y" (not "X can be used in order to accomplish Y")
• ✅ Start with action verbs: "Configure", "Install", "Run"
• ✅ Use second person: "You can configure..." (not "One can configure...")
• ✅ Define acronyms on first use: "API (Application Programming Interface)"

Don't:

• ❌ Use passive voice unnecessarily
• ❌ Write long, complex sentences (>25 words)
• ❌ Assume prior knowledge without linking context
• ❌ Use jargon without explanation
• ❌ Skip error handling in examples
• ❌ Hype or oversell: avoid "revolutionary", "cutting-edge", "game-changing", "paradigm shift" — describe what things actually do
• ❌ Add filler paragraphs that restate what was just said in different words
• ❌ Use buzzwords as substitutes for explanation ("leverages AI-driven insights" → "queries the model for suggestions")
• ❌ Pad docs with speculative future benefits — document what exists and works today

Code Example Best Practices

Complete and Runnable:

# ✅ GOOD: Complete example with imports and context
import requests

def get_user(user_id):
    """Fetch user data from API."""
    response = requests.get(f'https://api.example.com/users/{user_id}')
    response.raise_for_status()  # Handle errors
    return response.json()

# Usage
user = get_user(123)
print(user['name'])

# ❌ BAD: Incomplete snippet, unclear context
response = requests.get(url)
return response.json()

Include Error Handling:

// ✅ GOOD: Shows both success and error paths
try {
  const user = await fetchUser(userId);
  console.log(user.name);
} catch (error) {
  if (error.response?.status === 404) {
    console.error('User not found');
  } else {
    console.error('Failed to fetch user:', error.message);
  }
}

API Documentation Template

## `functionName(param1, param2)`

Brief one-line description of what the function does.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `param1` | string | Yes | Description of param1 |
| `param2` | number | No | Description of param2 (default: 0) |

### Returns

`Promise<User>` - User object containing `id`, `name`, `email`.

### Throws

- `ValidationError` - If param1 is empty or invalid format
- `NotFoundError` - If user with specified ID doesn't exist

### Example

\`\`\`javascript
const user = await functionName('john@example.com', 10);
console.log(user.name); // 'John Doe'
\`\`\`

### See Also

- [Related function](#related-function)
- [Configuration guide](./configuration.md)

Examples

Example: API Endpoint Documentation

# User Management API

RESTful API for managing user accounts and profiles.

**Base URL:** `https://api.example.com/v1`

**Authentication:** Bearer token in `Authorization` header

## Endpoints

### Create User

`POST /users`

Creates a new user account.

**Request Body:**

\`\`\`json
{
  "email": "user@example.com",
  "name": "John Doe",
  "role": "user"
}
\`\`\`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| email | string | Yes | Valid email address (unique) |
| name | string | Yes | Full name (2-100 characters) |
| role | string | No | User role: `user` or `admin` (default: `user`) |

**Success Response (201):**

\`\`\`json
{
  "user": {
    "id": "usr_abc123",
    "email": "user@example.com",
    "name": "John Doe",
    "role": "user",
    "created_at": "2026-01-09T10:30:00Z"
  }
}
\`\`\`

**Error Responses:**

| Status | Code | Description |
|--------|------|-------------|
| 400 | `invalid_email` | Email format invalid |
| 409 | `email_exists` | Email already registered |
| 401 | `unauthorized` | Missing or invalid auth token |

**Example Request:**

\`\`\`bash
curl -X POST https://api.example.com/v1/users \\
  -H "Authorization: Bearer YOUR_TOKEN" \\
  -H "Content-Type: application/json" \\
  -d '{"email":"user@example.com","name":"John Doe"}'
\`\`\`

**Rate Limits:** 100 requests/hour per API key

**See Also:**
- [Authentication Guide](./authentication.md)
- [Rate Limiting](./rate-limits.md)

References

• Markdown Guide: https://www.markdownguide.org/
• Write the Docs: https://www.writethedocs.org/guide/
• Technical Writing Best Practices: Google Developer Documentation Style Guide
• instructions/languages/markdown.instructions.md — repository Markdown guardrails
• instructions/compliance/documentation.instructions.md — documentation compliance overlay
• docs/templates/ — reusable documentation templates and canonical structures