Technical Writing

Technical Writing

Creates professional technical documentation with clear structure, appropriate detail level, and user-focused content.

Workflow

1. Identify Documentation Type

Determine which type of documentation is needed:

• API Documentation - REST, GraphQL, webhooks, authentication
• User Guides - Features, how-tos, troubleshooting
• Tutorials - Learning-focused with hands-on examples
• Architecture Documents - System design, technical decisions
• README Files - Project overview, quick start
• Release Notes - Changes, migrations, breaking changes
• Technical Specifications - Requirements, constraints

For detailed templates and patterns: Load documentation-types-and-workflows.md

2. Gather Context

Collect essential information before writing:

• Audience - Developers, end-users, managers, administrators
• Technical depth - Beginner, intermediate, advanced
• Scope - Codebase/APIs/systems to document
• Standards - Style guides or organizational requirements
• Related docs - Existing documentation to reference or integrate with

3. Structure Content

Apply clear organization principles:

• Lead with overview/introduction
• Use descriptive heading hierarchy (H1 → H2 → H3)
• Include table of contents for documents with >3 sections
• Group related information logically
• Place examples immediately after concepts
• Add diagrams/visuals for complex workflows

4. Write Clear Content

Follow core writing principles:

• Active voice - "The API returns..." not "The response is returned..."
• Specificity - "Response time < 200ms" not "Fast response"
• Define acronyms - "API (Application Programming Interface)" on first use
• Consistent terminology - Same terms throughout document
• Imperative instructions - "Run the command" not "You should run..."
• Show examples - Provide code/output for every concept

For comprehensive style guidance: Load writing-guidelines.md

5. Add Code Examples

Code example requirements:

• Specify language in code blocks: ``python,``javascript
• Show complete, runnable examples (not fragments)
• Include input/output pairs
• Add explanatory comments for complex logic
• Test all code before publishing

6. Review and Validate

Quality assurance checklist:

• ✓ Verify technical accuracy
• ✓ Test all code examples
• ✓ Check clarity and completeness
• ✓ Ensure consistent terminology
• ✓ Validate all links and references

Documentation Templates

README Files

Essential components for project documentation:

# Project Name
Brief description of what the project does

## Features
- Key feature 1
- Key feature 2
- Key feature 3

## Installation
[step-by-step installation commands]

## Quick Start
[minimal working example]

## Configuration
[environment variables or config options]

## License
[license type]

Release Notes

Structure for version releases:

# Version X.X.X - YYYY-MM-DD

## Summary
[High-level overview of this release]

## New Features
- Feature description (#issue-number)
- Feature description (#issue-number)

## Bug Fixes
- Fix description (#issue-number)
- Fix description (#issue-number)

## Breaking Changes
⚠️ **Change that breaks compatibility**
Migration guide: [step-by-step migration instructions]

## Deprecations
- Deprecated feature (will be removed in vX.X)

Quality Standards

Documentation quality checklist before publishing:

• [ ] Accuracy - All technical details are correct
• [ ] Completeness - All necessary topics covered
• [ ] Clarity - Target audience can understand content
• [ ] Examples - Working code included and tested
• [ ] Structure - Logical organization with clear headings
• [ ] Consistency - Terminology and formatting consistent
• [ ] Links - All hyperlinks are valid
• [ ] Grammar - No spelling or grammatical errors
• [ ] Current - Version numbers and dates up-to-date

Common Pitfalls to Avoid

1. Assuming knowledge - Define all acronyms and technical terms 2. Vague instructions - Be specific with concrete examples 3. Missing error scenarios - Document errors and solutions 4. Outdated examples - Test and update code regularly 5. Inconsistent terminology - Use identical terms throughout 6. Missing prerequisites - List all requirements upfront 7. Poor formatting - Use headings, lists, code blocks properly 8. No examples - Always include working code samples 9. Wrong audience level - Match technical depth to readers 10. Dense text - Break into scannable sections with clear headings

Reference Files

• [documentation-types-and-workflows.md](references/documentation-types-and-workflows.md) - Complete templates and patterns for API docs, user guides, tutorials, architecture docs, and technical specifications
• [writing-guidelines.md](references/writing-guidelines.md) - Detailed style rules for clarity, active voice, specificity, consistency, heading hierarchy, code formatting, and lists

Documentation Types and Workflows

Comprehensive patterns for creating different types of technical documentation. Each section provides structure, essential components, and examples.

Table of Contents

• API Documentation
• User Guides
• Tutorials
• Architecture Documents
• Technical Specifications

---

API Documentation

Purpose

Enable developers to integrate and use your API effectively by providing complete reference documentation.

Target Audience

Software developers, integration engineers, technical architects, DevOps engineers.

Essential Components

1. Overview

Brief description of the API's purpose, capabilities, and base information.

Template:

# API Name vX.X

Brief description of what the API does and its primary use cases.

**Base URL:** `https://api.example.com/v1`
**Protocol:** HTTPS only
**Response Format:** JSON
**Authentication:** Bearer token

2. Authentication

Document all authentication methods with examples.

Template:

## Authentication

[Description of authentication method]

**Header Format:**

Authorization: Bearer YOUR_API_KEY

**Obtaining Credentials:**

1. Step-by-step instructions
2. Where to find/generate keys
3. How to store securely

**Example Request:**

curl https://api.example.com/v1/users \ -H "Authorization: Bearer YOUR_API_KEY"

3. Endpoints

Document each endpoint completely.

Template:

### [METHOD] /path/to/endpoint

Brief description of what this endpoint does.

**Parameters:**

| Name | Type | In | Required | Description |
| ------ | ------ |-----|----------|-------------|
| id | string | path | Yes | Resource identifier |
| limit | integer | query | No | Results per page (default: 20, max: 100) |

**Request Body:**

{ "field1": "value", "field2": 123 }

**Success Response (200 OK):**

{ "id": "abc123", "field1": "value", "created_at": "2026-01-15T10:30:00Z" }

**Error Responses:**

**400 Bad Request:**

{ "error": "invalid_request", "message": "Detailed error message", "field": "fieldName" }

**Example:**

curl -X POST https://api.example.com/v1/resource \ -H "Authorization: Bearer TOKEN" \ -H "Content-Type: application/json" \ -d '{"field1":"value"}'

4. Rate Limiting

Explain limits and how to handle them.

Template:

## Rate Limits

**Limits:**
- X requests per minute
- Y requests per hour

**Response Headers:**
- `X-RateLimit-Limit`: Maximum requests allowed
- `X-RateLimit-Remaining`: Requests remaining
- `X-RateLimit-Reset`: Unix timestamp when limit resets

**429 Too Many Requests Response:**

{ "error": "rate_limit_exceeded", "retry_after": 60 }

5. Pagination

Document pagination strategy for list endpoints.

Template:

## Pagination

**Parameters:**
- `page`: Page number (default: 1)
- `limit`: Items per page (default: 20, max: 100)

**Response:**

{ "data": [...], "pagination": { "current_page": 1, "total_pages": 10, "total_items": 200, "per_page": 20 } }

6. Error Codes

Complete reference of all error codes.

Template:

## Error Codes

| Code | Status | Meaning | Solution |
| ------ | -------- |---------|----------|
| 400 | Bad Request | Invalid parameters | Check request format |
| 401 | Unauthorized | Missing/invalid auth | Verify API key |
| 404 | Not Found | Resource doesn't exist | Check resource ID |
| 429 | Too Many Requests | Rate limit exceeded | Wait and retry |
| 500 | Internal Server Error | Server error | Contact support |

---

User Guides

Purpose

Help end users understand and use product features effectively.

Target Audience

End users (non-technical), product administrators, customer success teams.

Essential Components

1. Feature Overview

Explain what the feature is and why it's valuable.

Template:

# Feature Name

## Overview

[Brief description of the feature]

**Benefits:**
- Benefit 1: Specific value provided
- Benefit 2: Specific value provided
- Benefit 3: Specific value provided

**Use Cases:**
- When you need to...
- Perfect for...
- Ideal when...

2. Prerequisites

List requirements before starting.

Template:

## Prerequisites

Before using this feature, ensure you have:

- [ ] Requirement 1 (with link if applicable)
- [ ] Requirement 2
- [ ] Requirement 3

**Permissions Required:** [Role or permission level needed]

**Note:** [Any important notes about prerequisites]

3. Step-by-Step Instructions

Provide clear, numbered steps with visuals.

Template:

## How to [Action]

### Step 1: [First Action]

1. Navigate to [Location]
2. Click [Button/Link]
3. Select [Option]

![Screenshot description](path/to/image.png)

**Tip:** [Helpful tip or note]

### Step 2: [Next Action]

1. In the [Section] area...
2. Enter [Information]...
3. Click [Confirm]

![Screenshot description](path/to/image.png)

**Important:** [Critical information or warning]

### Step 3: [Final Action]

[Instructions for completing the process]

**Success Indicator:** [How users know they succeeded]

4. Configuration Options

Document all settings and customization.

Template:

## Configuration

### General Settings

**Setting Name:**
- Description of what this setting does
- Options: Option1, Option2, Option3
- Default: [Default value]
- Recommendation: [Best practice guidance]

### Advanced Settings

**Advanced Setting:**
- [Detailed explanation]
- **When to use:** [Specific scenarios]
- **Impact:** [What changes when enabled]

5. Troubleshooting

Common issues and solutions.

Template:

## Troubleshooting

### Problem: [Issue Description]

**Symptoms:**
- Symptom 1
- Symptom 2

**Possible Causes:**
- Cause 1
- Cause 2

**Solutions:**

**Solution 1: [Most Common Fix]**
1. Step 1
2. Step 2
3. Step 3

**Solution 2: [Alternative Fix]**
1. Step 1
2. Step 2

**If problem persists:**
- Link to support
- Contact information
- Related documentation

6. Best Practices

Tips for optimal usage.

Template:

## Best Practices

### Do's

✅ **Do this:**
- Explanation of why
- How it helps

✅ **Do that:**
- Explanation of why
- Benefit provided

### Don'ts

❌ **Don't do this:**
- Explanation of why not
- What could go wrong

❌ **Avoid that:**
- Explanation of why
- Alternative approach

---

Tutorials

Purpose

Teach users new skills through hands-on, guided learning.

Target Audience

Learners (beginners to intermediate), developers learning new technologies.

Essential Components

1. Learning Objectives

Clear statement of what learners will accomplish.

Template:

# Tutorial Title

## What You'll Build
[Concrete description of the end result]

## What You'll Learn
- Skill/concept 1
- Skill/concept 2
- Skill/concept 3

**Time Required:** [X minutes/hours]
**Skill Level:** Beginner/Intermediate/Advanced

## Prerequisites
- Prior knowledge required
- Tools needed
- Accounts/access required

2. Setup Instructions

Get learners ready to start.

Template:

## Setup

### 1. Install Prerequisites

**Tool 1:**

Installation command

Verify: `tool --version`

**Tool 2:**
[Installation instructions with alternatives for different platforms]

### 2. Create Project

Commands to set up project structure

mkdir project-name cd project-name npm init -y

### 3. Configure Environment

Environment setup

cp .env.example .env

Edit .env with your values

### 4. Verify Setup

[Commands to verify everything is working]
Expected output: [What they should see]

3. Step-by-Step Implementation

Build progressively with explanations.

Template:

## Step 1: [Milestone Title]

[Brief explanation of what this step accomplishes]

**Create [filename]:**

[Complete code]

**Explanation:**

- Line/section 1: What it does and why
- Line/section 2: What it does and why
- Key concept: Deeper explanation

**Test It:**

Command to test

Expected output: [What they should see]

**Checkpoint:** At this point, you should have:

- [ ] Thing 1 working
- [ ] Thing 2 completed
- [ ] Thing 3 verified

4. Progressive Complexity

Build on previous steps.

Pattern:

## Step 2: Add [Feature]

Building on Step 1, now we'll add [feature].

**Update [filename]:**

Show the addition/modification in context:

// Existing code for context existing_function() { // ... }

// NEW CODE - Add this new_function() { // New functionality }

**Why this works:**
[Explanation of the concept]

**Try it:**
[How to test the new functionality]

5. Complete Solution

Provide final working code.

Template:

## Complete Application

### Final Project Structure

project/ ├── src/ │ ├── file1.js │ ├── file2.js │ └── file3.js ├── tests/ ├── package.json └── README.md

### Running the Complete Application

Clone or download

Install dependencies

Run application

### Repository

Complete code available at: [GitHub link]

6. Next Steps

Guide continued learning.

Template:

## What You've Accomplished

Congratulations! You've successfully:
- [ ] Accomplishment 1
- [ ] Accomplishment 2
- [ ] Accomplishment 3

## Next Steps

### Extend Your Project
- [ ] Enhancement 1
- [ ] Enhancement 2
- [ ] Enhancement 3

### Related Tutorials
- [Tutorial A]: Learn about...
- [Tutorial B]: Explore...
- [Tutorial C]: Dive into...

### Resources
- **Documentation:** [link]
- **Community:** [link]
- **Advanced Topics:** [link]

---

Architecture Documents

Purpose

Communicate system design, technical decisions, and architectural patterns.

Target Audience

Software architects, senior developers, technical leads, engineering managers.

Essential Components

1. Executive Summary

High-level overview for decision makers.

Template:

# System/Project Name Architecture

## Executive Summary

[2-3 paragraph overview of the architecture]

**Key Characteristics:**
- Characteristic 1
- Characteristic 2
- Characteristic 3

**Major Technical Decisions:**
- **Decision 1:** Technology/approach chosen
- **Decision 2:** Technology/approach chosen
- **Decision 3:** Technology/approach chosen

**Investment:**
- Development: [Timeline]
- Infrastructure: [Cost estimate]
- Team: [Size and composition]

**Timeline:**
- Phase 1: [Scope and duration]
- Phase 2: [Scope and duration]

2. System Context

How the system fits in the ecosystem.

Template:

## System Context

### External Systems

**Integration 1: System Name**
- Purpose: [Why we integrate]
- Protocol: [How we communicate]
- Data Flow: [What data is exchanged]
- SLA: [Expected availability]

### Users

**User Type 1:**
- Who they are
- What they do
- How they access the system
- Volume/load expectations

### Boundaries

**In Scope:**
- Capability 1
- Capability 2

**Out of Scope:**
- What we don't handle
- What's delegated to external systems

3. Architecture Diagrams (Mermaid Format)

Visual representation of system structure.

Template:

## Architecture Overview

### High-Level Architecture

[Mermaid C4 diagram or flowchart]

### Component Diagram

[Detailed breakdown of major components and their relationships]

### Data Flow

[How data moves through the system]

4. Component Descriptions

Detailed explanation of each major component.

Template:

## Core Components

### Component Name

**Purpose:**
[What this component does]

**Responsibilities:**
- Responsibility 1
- Responsibility 2
- Responsibility 3

**Technology Stack:**
- Language: [Language and version]
- Framework: [Framework and version]
- Database: [Database type and version]
- Dependencies: [Key libraries]

**API:**
- `ENDPOINT 1`: Description
- `ENDPOINT 2`: Description

**Data Model:**

{ "example": "data structure" }

**Scalability:**

- Scaling approach
- Performance targets
- Monitoring metrics

5. Technology Stack

Complete list of technologies with rationale.

Template:

## Technology Stack

| Component | Technology | Version | Rationale |
| ----------- | ----------- |---------|-----------|
| Service Layer | Go | 1.20 | Performance, concurrency |
| Database | PostgreSQL | 15 | ACID, reliability |
| Cache | Redis | 7.x | Speed, pub/sub |
| Queue | Kafka | 3.x | Throughput, replay |

### Technology Decisions

**Why [Technology]:**
- Reason 1
- Reason 2
- Alternatives considered: [Other options and why not chosen]

6. Non-Functional Requirements

Performance, scalability, reliability targets.

Template:

## Non-Functional Requirements

### Performance

| Metric | Target | Measurement |
| -------- | -------- |-------------|
| Response Time (p95) | < 500ms | APM tool |
| Throughput | 10K req/sec | Load balancer |
| Database Query | < 100ms | Query logs |

### Scalability

| Metric | Target | Strategy |
| -------- | -------- |----------|
| Concurrent Users | 100K | Horizontal scaling |
| Data Growth | 10TB/year | Partitioning |
| Geographic | Multi-region | Active-active |

### Availability

| Component | SLA | Strategy |
| ----------- | ----- |----------|
| Overall | 99.99% | Redundancy |
| Database | 99.99% | Replication |
| API | 99.95% | Multi-AZ |

### Security

- Authentication: [Approach]
- Authorization: [Approach]
- Data Encryption: At rest and in transit
- Compliance: [Standards met]

---

Technical Specifications

Purpose

Provide detailed technical requirements for implementation.

Target Audience

Software developers, QA engineers, technical leads.

Essential Components

1. Requirements

What the system must do.

Template:

# Feature Specification: [Feature Name]

## Functional Requirements

**FR-1: [Requirement Title]**
- System MUST [requirement]
- Performance: [specific metric]
- Input: [what goes in]
- Output: [what comes out]

**FR-2: [Requirement Title]**
[Description]

## Non-Functional Requirements

**Performance:**
- Metric 1: [specific target]
- Metric 2: [specific target]

**Security:**
- Requirement 1
- Requirement 2

**Scalability:**
- Requirement 1
- Requirement 2

2. API Specifications

Detailed API contracts.

Template:

## API Specification

### Endpoint: [METHOD] /path

**Purpose:** [What it does]

**Parameters:**

| Name | Type | In | Required | Validation | Description |
| ------ | ------ |-----|----------|------------|-------------|
| id | string | path | Yes | UUID v4 | Resource ID |
| limit | integer | query | No | 1-100 | Items per page |

**Request Body Schema:**

{ "field1": { "type": "string", "required": true, "validation": "email format" } }

**Response Codes:**

- 200: Success
- 400: Validation error
- 404: Not found
- 500: Server error

**Example Request:**

[Complete curl example]

**Example Response:**

[Complete response example]

3. Algorithm Details

How complex logic works.

Template:

## Algorithm: [Algorithm Name]

**Purpose:** [What problem it solves]

**Input:**
- Input 1: [type and constraints]
- Input 2: [type and constraints]

**Output:**
- Output: [type and format]

**Logic:**

1. Step 1: [What happens] 2. Step 2: [What happens] 3. Step 3: [What happens]

**Pseudocode:**

function algorithm(input): // Step-by-step pseudocode if condition: do something else: do something else return result

**Edge Cases:**
- Case 1: [How handled]
- Case 2: [How handled]

**Complexity:**
- Time: O(n)
- Space: O(1)

4. Data Models

Structure of data entities.

Template:

## Data Models

### Entity: [Entity Name]

**Purpose:** [What this entity represents]

**Schema:**

{ "id": "string (UUID)", "field1": "string (1-100 chars)", "field2": "integer (>= 0)", "created_at": "timestamp (ISO 8601)", "updated_at": "timestamp (ISO 8601)" }

**Validation Rules:**

- field1: Required, alphanumeric only
- field2: Optional, must be positive

**Relationships:**

- Entity → Other Entity (one-to-many)
- Entity → Another Entity (many-to-many through table_name)

**Indexes:**

- Primary: id
- Unique: field1
- Index: (field2, created_at)

5. Testing Requirements

How to verify functionality.

Template:

## Testing Requirements

### Test Scenario 1: [Scenario Name]

**Purpose:** Verify [what is being tested]

**Preconditions:**
- Precondition 1
- Precondition 2

**Test Steps:**
1. Step 1
2. Step 2
3. Step 3

**Expected Result:**
- Result 1
- Result 2

**Acceptance Criteria:**
- [ ] Criterion 1
- [ ] Criterion 2

### Performance Tests

**Test:** [Test name]
- Load: [X concurrent users]
- Duration: [Y minutes]
- Target: [Metric < Z]
- Tool: [Testing tool]

### Edge Cases

**Edge Case 1: [Description]**
- Input: [Specific input]
- Expected: [How system should behave]

---

Best Practices Across All Documentation

Keep Documentation Close to Code

• Store docs in the same repository as code
• Version documentation with code changes
• Review docs during code review

Update Docs With Code Changes

• Update docs before/with code changes
• Mark outdated sections clearly
• Deprecate old documentation properly

Use Templates and Standards

• Create reusable templates
• Enforce documentation standards
• Use linters for documentation

Make Documentation Searchable

• Use clear, descriptive titles
• Include keywords in content
• Provide comprehensive index/TOC

Gather Feedback

• Track documentation issues
• Monitor search queries
• Survey users about doc quality
• Iterate based on feedback

Writing Guidelines

Comprehensive guidelines for clear, consistent, and effective technical writing.

Table of Contents

• Clarity and Conciseness
• Consistent Terminology
• Active Voice
• Specificity
• Heading Hierarchy
• Code Formatting
• Lists and Tables
• Common Mistakes

---

Clarity and Conciseness

Use Active Voice

Active voice makes documentation clearer and more direct.

✅ Good Examples:

• "The system processes the request"
• "Click Save to store your changes"
• "The API returns a JSON response"
• "Configure the settings in the dashboard"

❌ Bad Examples:

• "The request is processed by the system"
• "Your changes can be stored by clicking on the Save button"
• "A JSON response is returned by the API"
• "The settings can be configured in the dashboard"

Be Direct and Concise

Eliminate unnecessary words and get to the point.

✅ Good Examples:

• "Configure the settings"
• "Run the command"
• "The function returns a boolean"
• "Authentication requires an API key"

❌ Bad Examples:

• "Configure the settings and parameters"
• "You should go ahead and run the command"
• "The function will go ahead and return a boolean value"
• "In order to authenticate, you will need to provide an API key"

Avoid Redundancy

Don't repeat information unnecessarily.

✅ Good Examples:

• "Create a new user"
• "Delete the file"
• "Important: Backup data before upgrading"

❌ Bad Examples:

• "Create a new user account" (account is redundant)
• "Delete and remove the file" (delete and remove mean the same)
• "Important note: Please note that..." (redundant "note")

Define Acronyms and Jargon

Always define acronyms on first use and explain technical terms.

✅ Good Examples:

• "API (Application Programming Interface)"
• "JWT (JSON Web Token) for authentication"
• "Use CRUD (Create, Read, Update, Delete) operations"
• "Configure the REST (Representational State Transfer) endpoint"

❌ Bad Examples:

• "Configure the API" (assumes everyone knows API)
• "Use JWT for auth" (unexplained acronyms)
• "Implement CRUD" (no explanation)

Use Short Sentences

Keep sentences concise and focused on one idea.

✅ Good Example:

The API supports pagination. Use the `page` parameter to specify the page number. Each page returns up to 100 results.

❌ Bad Example:

The API supports pagination and you can use the `page` parameter to specify which page number you want to retrieve, with each page returning up to 100 results depending on your configuration.

---

Consistent Terminology

Choose One Term and Stick With It

Don't alternate between synonyms for the same concept.

✅ Good (Consistent):

## User Management

To create a user, click "Add User".
To edit a user, select the user from the list.
To delete a user, click the trash icon next to the user.

❌ Bad (Inconsistent):

## User Management

To create a customer, click "Add User".
To edit a client, select the account from the list.
To delete a person, click the trash icon next to the member.

Create and Use a Glossary

Document your terminology and share with the team.

Example Glossary:

# Terminology

- **User**: Person who interacts with the system (not customer, client, or account)
- **Project**: Collection of tasks and resources (not workspace or folder)
- **API Key**: Authentication credential (not access token or secret key)
- **Endpoint**: API route (not URL, path, or resource)

Be Consistent with Technical Terms

Use standard industry terminology correctly.

✅ Correct:

• REST API (not RESTful API or REST endpoint)
• JSON (all caps, not Json or json)
• JavaScript (not Javascript or java script)
• macOS (not MacOS or Mac OS)
• URL (not Url or url)
• HTTP (not Http or http)

---

Active Voice

Prefer Active Over Passive

Active voice is more engaging and clearer.

✅ Active Voice:

• "The API validates the input"
• "Run the migration script"
• "The user clicks the button"
• "Configure the database connection"

❌ Passive Voice:

• "The input is validated by the API"
• "The migration script should be run"
• "The button is clicked by the user"
• "The database connection should be configured"

When Passive Voice is Acceptable

Use passive voice when the actor is unknown or unimportant.

Acceptable Examples:

• "The user was created successfully" (focus on the result)
• "The file has been deleted" (who deleted it doesn't matter)
• "An error was encountered" (source of error is unknown)

---

Specificity

Be Specific with Numbers

Provide exact numbers instead of vague terms.

✅ Specific:

• "Response time < 200ms for 95% of requests"
• "Retry up to 3 times with 2-second delays"
• "Password must be 12+ characters"
• "API rate limit: 1000 requests per hour"
• "Cache expires after 5 minutes"

❌ Vague:

• "Fast response time"
• "Retry a few times"
• "Strong password required"
• "High API rate limit"
• "Short cache duration"

Be Specific with Instructions

Provide exact steps, not general guidance.

✅ Specific:

1. Open terminal
2. Navigate to project directory: `cd /path/to/project`
3. Run: `npm install`
4. Start server: `npm start`
5. Open browser to: http://localhost:3000

❌ Vague:

1. Open your terminal
2. Go to the project folder
3. Install the dependencies
4. Start the server
5. Check if it's working

Specify Versions and Requirements

Always include version numbers and system requirements.

✅ Specific:

• "Requires Node.js 18.0 or higher"
• "Compatible with Python 3.9, 3.10, 3.11"
• "Tested on Ubuntu 22.04 LTS"
• "Supports PostgreSQL 14+ and MySQL 8+"

❌ Vague:

• "Requires recent Node.js"
• "Works with Python 3.x"
• "Compatible with modern Linux"
• "Supports major databases"

---

Heading Hierarchy

Use Proper Heading Levels

Follow semantic heading structure (H1 → H2 → H3).

✅ Correct Hierarchy:

# Main Title (H1)

## Major Section (H2)

### Subsection (H3)

#### Minor Point (H4)

## Another Major Section (H2)

### Subsection (H3)

❌ Incorrect (Skipping Levels):

# Main Title (H1)

### Subsection (H3) - skipped H2

##### Minor Point (H5) - skipped H4

Make Headings Descriptive

Headings should clearly indicate section content.

✅ Descriptive:

• "Installing Prerequisites"
• "Configuring Authentication"
• "Troubleshooting Connection Errors"
• "API Rate Limits"

❌ Vague:

• "Setup"
• "Configuration"
• "Problems"
• "Limits"

---

Code Formatting

Always Specify Language

Always include language identifier in code blocks.

✅ With Language:

````markdown

const result = await fetchData();
console.log(result);

❌ Without Language:

````markdown

const result = await fetchData();
console.log(result);

Use Inline Code for Keywords

Wrap code elements in backticks.

✅ Good:

• Use the GET method to retrieve data
• Set the Content-Type header to application/json
• The userId parameter is required
• Run npm install to install dependencies

❌ Bad:

• Use the GET method to retrieve data
• Set the Content-Type header to application/json
• The userId parameter is required
• Run npm install to install dependencies

Format Code Examples Properly

Show complete, runnable code with proper formatting.

✅ Complete Example:

// Fetch user data
async function getUserById(id) {
  try {
    const response = await fetch(`/api/users/${id}`);
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}`);
    }
    const user = await response.json();
    return user;
  } catch (error) {
    console.error('Failed to fetch user:', error);
    throw error;
  }
}

❌ Incomplete Example:

// Get user
fetch('/api/users/' + id)
  .then(res => res.json())

Include Input/Output Pairs

Show both input and expected output.

✅ With Input/Output:

// Input
const input = "hello world";
const result = capitalizeWords(input);
console.log(result);

// Output
// "Hello World"

---

Lists and Tables

Use Lists for Sequential Steps

Number lists for steps, bullets for items.

✅ Numbered for Steps:

## Installation

1. Install Node.js from https://nodejs.org
2. Clone the repository: `git clone ...`
3. Install dependencies: `npm install`
4. Start the server: `npm start`

✅ Bullets for Non-Sequential Items:

## Features

- User authentication
- Real-time updates
- File upload support
- Email notifications

Use Tables for Structured Data

Tables are ideal for parameters, options, and comparisons.

✅ Good Table:

| Parameter | Type | Required | Description |
| ----------- | ------ |----------|-------------|
| name | string | Yes | User's full name |
| email | string | Yes | Valid email address |
| age | integer | No | User's age (18+) |

❌ Poor Formatting:

Parameters:
- name (string, required): User's full name
- email (string, required): Valid email address
- age (integer, optional): User's age (must be 18 or older)

---

Common Mistakes

Don't Use "You Should" or "You Might Want To"

Be direct with imperative mood.

✅ Direct:

• "Install Node.js 18 or higher"
• "Configure the database URL"
• "Run tests before deploying"

❌ Wishy-Washy:

• "You should install Node.js 18 or higher"
• "You might want to configure the database URL"
• "You should probably run tests before deploying"

Don't Use Future Tense for Documentation

Use present tense for current functionality.

✅ Present Tense:

• "The API returns a JSON response"
• "The function validates user input"
• "Authentication requires an API key"

❌ Future Tense:

• "The API will return a JSON response"
• "The function will validate user input"
• "Authentication will require an API key"

Don't Assume Gender

Use gender-neutral language.

✅ Gender-Neutral:

• "The user enters their email"
• "Each developer has their own API key"
• "The admin can configure their preferences"

❌ Gendered:

• "The user enters his email"
• "Each developer has his own API key"
• "The admin can configure her preferences"

Don't Use Contractions

Use full words in formal documentation.

✅ Full Words:

• "do not"
• "cannot"
• "it is"
• "you are"

❌ Contractions:

• "don't"
• "can't"
• "it's"
• "you're"

Avoid "Just" and "Simply"

These words can be condescending or dismissive.

✅ Without "Just":

• "Run npm install to install dependencies"
• "Add the API key to your environment variables"
• "Configure the database connection string"

❌ With "Just":

• "Just run npm install to install dependencies"
• "Simply add the API key to your environment variables"
• "Just configure the database connection string"

---

Formatting Standards

Capitalization

Sentence Case for Headings:

• ✅ "Getting started with the API"
• ❌ "Getting Started With The API"

Exception - Title Case for Main Titles:

• ✅ "API Reference Guide"
• ✅ "User Authentication Tutorial"

Proper Nouns Always Capitalized:

• JavaScript, Python, PostgreSQL, Docker, AWS

Punctuation

End Sentences with Periods:

✅ Configure the database. Run migrations. Start the server.
❌ Configure the database

No Period for Headings:

✅ ## Installing Dependencies
❌ ## Installing Dependencies.

Use Periods in Lists (for Complete Sentences):

✅ 
- Install Node.js 18 or higher.
- Clone the repository from GitHub.
- Run `npm install` to install dependencies.

❌ 
- Install Node.js 18 or higher
- Clone the repository from GitHub
- Run `npm install` to install dependencies

Line Length

Keep Lines Reasonable:

• Target: 80-100 characters per line in markdown
• Helps with readability and diffs
• Exception: URLs and code blocks can be longer

---

Accessibility

Provide Alt Text for Images

Always include descriptive alt text.

✅ With Alt Text:

![Login screen showing username and password fields](images/login-screen.png)

❌ Without Alt Text:

![](images/login-screen.png)

Use Descriptive Link Text

Link text should describe the destination.

✅ Descriptive:

• See the API authentication guide for details
• Download the installation script
• View complete code example

❌ Non-Descriptive:

• See documentation for details
• Click this link
• View example

Ensure Proper Heading Hierarchy

Screen readers rely on heading hierarchy for navigation.

✅ Proper Hierarchy:

• Never skip heading levels (H1 → H2 → H3)
• Each page has exactly one H1
• Headings are descriptive

---

Review Checklist

Before publishing documentation:

• [ ] All acronyms defined on first use
• [ ] Active voice used throughout
• [ ] Specific numbers and versions provided
• [ ] Code blocks have language specified
• [ ] Consistent terminology used
• [ ] Proper heading hierarchy (no skipped levels)
• [ ] Tables formatted correctly
• [ ] Links are descriptive
• [ ] Images have alt text
• [ ] No gendered language
• [ ] No contractions in formal docs
• [ ] Grammar and spelling checked