Technical documentation writing - Rule overview

This is an overview of the specialized technical documentation writing rules. Each rule set focuses on a specific aspect of documentation creation to provide targeted, actionable guidance.

Available rule sets

🎯 general-writing.md — Core writing principles

When to use: Always applies to all documentation types Focus: Language standards, organization principles, accessibility, and quality practices that apply universally across all technical writing.

💡 explaining-concepts.md — Making complex topics clear

When to use: When explaining how things work, defining terms, or clarifying abstract concepts Focus: Breaking down complex ideas, using analogies, progressive disclosure, and validation techniques for conceptual understanding.

📋 technical-guides.md — Step-by-step procedures

When to use: For tutorials, how-to guides, installation instructions, and procedural documentation Focus: Task-oriented writing, step structure, code examples, troubleshooting, and user success optimization.

🗂️ site-navigation.md — Information architecture

When to use: When organizing documentation sites, planning content hierarchy, or improving discoverability Focus: Content organization, navigation design, user journeys, and documentation site structure.

🔌 api-documentation.md — Reference materials

When to use: For API docs, technical references, and comprehensive specifications Focus: API endpoint documentation, parameter specifications, code examples, authentication, and reference material organization.

How to use these rules

For comprehensive projects

Apply multiple rule sets as needed:

1. Start with general-writing.md principles
2. Add specific rules based on content type:
   • Explaining features → explaining-concepts.md
   • Writing tutorials → technical-guides.md
   • Documenting APIs → api-documentation.md
   • Organizing content → site-navigation.md

For focused tasks

Choose the most relevant specialized rule set:

• "How does X work?" → explaining-concepts.md
• "How do I do X?" → technical-guides.md
• "What are X's parameters?" → api-documentation.md
• "How should I organize this?" → site-navigation.md

Quality assurance

Always refer back to general-writing.md for:

• Language and style consistency
• Accessibility requirements
• Content validation practices
• Maintenance standards

Quick reference

Most common combinations:

• Product documentation: general-writing.md + explaining-concepts.md + technical-guides.md + site-navigation.md
• API documentation: general-writing.md + api-documentation.md + technical-guides.md
• Learning materials: general-writing.md + explaining-concepts.md + technical-guides.md
• Reference sites: general-writing.md + api-documentation.md + site-navigation.md

Each rule set is designed to work independently while complementing the others. Choose the combination that best matches your documentation goals and user needs.

Core writing principles

Language and style requirements

• Use clear, direct language appropriate for technical audiences
• Write in second person ("you") for instructions and procedures
• Use active voice instead of passive
• Prefer present tense for current states; future tense for outcomes
• Avoid jargon unless necessary; define terms on first use
• Keep terminology consistent across all docs
• Keep sentences concise, with full context
• Use parallel structure in lists, headings, and procedures

Content organization standards

• Lead with the most important information (inverted pyramid style)
• Use progressive disclosure: simple → advanced
• Break complex procedures into numbered steps
• Always include prerequisites and context
• Provide expected outcomes for each step
• Use keyword-rich, descriptive headings for SEO/navigation
• Group related content logically with clear section breaks

User-centered approach

• Focus on user goals/outcomes rather than system features
• Anticipate common questions and answer them in the docs
• Include troubleshooting for common failure points
• Optimize for scanning: headings, lists, white space
• Include verification steps to confirm success
• Start with the user's context — explain why they need this information
• Provide multiple paths — acknowledge different user skill levels and use cases
• Include realistic timelines — tell users how long procedures should take

Content formatting guidelines

Highlighting and callouts

Use appropriate formatting for different types of content:

Notes and tips:

• Notes: Supplementary information that supports the main content
• Tips: Best practices, shortcuts, or expert advice
• Warnings: Critical warnings about issues or destructive actions
• Info boxes: Neutral background or contextual information
• Danger alerts: Severe risks like data loss, downtime, or security issues

Implementation varies by platform (markdown callouts, HTML boxes, etc.)

Code examples

Use syntax highlighting for code blocks when available:

// Example with title/filename when supported
const apiConfig = {
  baseURL: '[https://api.example.com](https://api.example.com)',
  headers: { Authorization: `Bearer ${process.env.API_TOKEN}` }
};

Multiple language examples

When showing the same concept across different languages:

Node.js:

await fetch('/api/endpoint', { headers: { Authorization: `Bearer ${apiKey}` }});

Python:

import requests
requests.get('/api/endpoint', headers={'Authorization': f'Bearer {api_key}'})

Shell/cURL:

curl -H 'Authorization: Bearer YOUR_API_KEY' [https://api.example.com/endpoint](https://api.example.com/endpoint)

Request/response examples

Structure API examples clearly:

Request:

curl -X POST [https://api.example.com/users](https://api.example.com/users) \
  -H 'Content-Type: application/json' \
  -d '{"name":"John Doe","email":"john@example.com"}'

Response — 201 Created:

{
  "id": "user_123",
  "name": "John Doe",
  "email": "john@example.com"
}

Step-by-step procedures

Use numbered lists for sequential steps:

1. Install dependencies

   npm install
   

   Verify: run npm list to confirm installation.

2. Configure environment

   echo "API_KEY=your_api_key" >> .env
   

Collapsible sections

Use platform-appropriate collapsible content for:

• Troubleshooting information
• Advanced configuration
• Optional details
• FAQ answers

Media and visuals

Images:

• Always include descriptive alt text
• Add captions when helpful for context
• Use consistent image sizing and formatting

Videos:

• Provide fallback descriptions
• Include timestamps for longer videos
• Ensure accessibility with captions when possible

Content quality standards

Code examples

• Must be runnable end-to-end
• Use realistic data (not foo/bar)
• Show error handling and edge cases
• Include expected output when useful
• Add explanatory comments for complex logic
• Never use real secrets or API keys
• Avoid comments in bash/shell commands — they can break copy-paste functionality and cause execution errors
• Version-pin dependencies — specify exact versions in installation examples
• Test all code samples — ensure examples work as written before publishing
• Use consistent naming conventions — maintain the same variable/function names across related examples

API docs

• Document all parameters (including optional)
• Show both success and error responses
• Cover rate limits and authentication details
• Explain HTTP status codes and handling
• Provide request/response cycles fully

Accessibility

• Provide alt text for all images
• Use clear link text (not “click here”)
• Respect heading hierarchy (H2 > H3 > H4)
• Ensure color contrast is sufficient
• Support keyboard navigation where possible

Content formatting selection guide

Choose appropriate formatting based on content type:

• Callouts/alerts → tips, warnings, notes, contextual information
• Code blocks → runnable, tested examples with syntax highlighting
• Multi-language tabs/sections → alternative platforms/languages
• Collapsible sections → advanced or optional content
• Numbered lists → sequential instructions and procedures
• Images with captions → visual explanations and screenshots
• Interactive elements → demos, examples, or embedded content (when supported)