Technical Writing

Technical Writing Mastery

Write clear, effective technical documentation that your audience can actually use — SOPs that get followed, manuals that solve problems, and release notes that keep everyone informed.

Core Principles

1. Know Your Audience

Every document serves a specific reader with a specific goal. A system administrator reading an SOP needs exact CLI commands. An end-user reading a manual needs step-by-step workflows. A developer reading release notes needs to know what changed and whether it breaks their code.

2. Active Voice, Plain Language

Write directly. "The system processes the request" — not "The request is processed by the system." Use plain language: "Start the server" instead of "Initiate the server startup sequence."

3. Structure for Scanning

Most people don't read documentation — they scan it. Use clear headings, bullet lists, tables, and bold key terms so readers find what they need in seconds.

4. One Task Per Section

Each section should answer one question or guide one action. If a section covers more than one task, split it.

5. Test Everything You Write

If you write a command, run it. If you write a procedure, follow it exactly as written. Nothing erodes trust faster than instructions that don't work.

Technical Writing Maturity Model

Target: Level 3 for internal team docs. Level 4 for customer-facing documentation.

Actionable Guidance

Audience Analysis Matrix

Before writing anything, map your audience:

Exercise: Before writing, fill in this table for your document. If you can't clearly define the audience, don't start writing yet.

SOP (Standard Operating Procedure) Template

# SOP: [Procedure Name]

**SOP ID**: SOP-[Dept]-[Number]
**Version**: 1.0
**Effective Date**: YYYY-MM-DD
**Owner**: [Name/Role]
**Review Cycle**: [Quarterly/Annually]

## Purpose
[1-2 sentences explaining why this procedure exists]

## Scope
[Who performs this? When? Under what conditions?]

## Prerequisites
- [Access needed]
- [Tools required]
- [Permissions needed]

## Definitions
| Term | Definition |
|------|------------|
| [Term] | [Definition] |
| [Term] | [Definition] |

## Procedure

### Step 1: [Step Name]
**Action**: [What to do]
```bash
[Command if applicable]

Expected Result: [What should happen] Troubleshooting: [If X happens, do Y]

Step 2: [Step Name]

Action: [What to do] Expected Result: [What should happen]

Verification

[How to confirm the procedure completed successfully]

Escalation

If procedure fails: [Who to contact] Emergency contact: [Name/Phone]

Revision History

---

### User Manual Structure

A well-structured user manual follows this hierarchy:

```text
1. Title Page & Table of Contents
2. About This Manual
   - Who this is for
   - What you'll need
   - Conventions used in this manual
3. Getting Started
   - Installation or setup
   - First-run experience
   - Quick start tutorial
4. Core Tasks
   - Task 1: Step-by-step
   - Task 2: Step-by-step
   - Task 3: Step-by-step
5. Reference
   - Settings and configuration
   - Keyboard shortcuts
   - File formats
6. Troubleshooting
   - Common issues and solutions
   - Error messages explained
   - Support contact information
7. Glossary
8. Index

Rule of thumb: If a user can't find the answer to a question within 30 seconds of opening the manual, the information architecture needs work.

Release Notes Patterns

By Category (Recommended)

# Release Notes v2.4.0 — March 15, 2024

## ✨ New Features
- **Dark mode**: You can now switch to a dark theme in Settings > Appearance
- **Bulk export**: Export up to 500 records at once (previously 50)
- **Webhook retries**: Failed webhooks now retry up to 3 times with exponential backoff

## 🔧 Improvements
- Search results load 40% faster on large datasets
- Reduced memory usage by 25% during batch operations
- Updated the dashboard charts to use the new design system

## 🐛 Bug Fixes
- Fixed: Login page crashes on Safari when using password managers
- Fixed: "Report generated" email sent twice for scheduled reports
- Fixed: CSV export missing header row for locale-sensitive fields

## ⚠️ Deprecations
- Legacy API v1 will be removed on June 30, 2024. Migrate to v2.
- The `--legacy-format` CLI flag is deprecated

## 📝 Migration Notes
- If you use the batch API, review the new rate limit of 100 req/s (was 200)
- Database schema migration required: `npm run migrate:v2.4.0`

## 📦 Downloads
[Download v2.4.0](https://downloads.example.com/v2.4.0)

Keep a Changelog Format

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/),
and this project adheres to [Semantic Versioning](https://semver.org/).

## [2.4.0] — 2024-03-15

### Added
- Dark mode support (`Settings > Appearance`)
- Bulk export (up to 500 records)
- Webhook retry mechanism with exponential backoff

### Changed
- Improved search performance (40% faster)
- Reduced memory usage in batch operations by 25%
- Updated dashboard chart components

### Fixed
- Safari login crash with password managers
- Duplicate email notifications for scheduled reports
- CSV export missing headers for locale fields

### Deprecated
- API v1 (removal: June 30, 2024)
- `--legacy-format` CLI flag

### Security
- Updated dependencies to patch CVE-2024-XXXX
- Added rate limiting to authentication endpoints

Versioning Documentation

Document Version Numbering

Version Tracking in Documents

Include a revision history table at the end of every document:

## Document History

| Version | Date | Author | Summary of Changes |
|---------|------|--------|--------------------|
| 1.2.0 | 2024-03-01 | J. Smith | Added troubleshooting section for timeout errors |
| 1.1.0 | 2024-01-15 | A. Lee | Updated installation instructions for v3.2 |
| 1.0.0 | 2023-11-01 | J. Smith | Initial release |

Managing Multiple Versions

docs/
├── v1.0/
│   ├── getting-started.md
│   ├── installation.md
│   └── api-reference.md
├── v2.0/
│   ├── getting-started.md
│   ├── installation.md
│   ├── api-reference.md
│   └── migration-guide-v1-to-v2.md
└── latest/    → symlink to v2.0/

Document Review Workflow

# .github/workflows/doc-review.yml
name: Documentation Review
on:
  pull_request:
    paths:
      - 'docs/**'
      - '*.md'

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      # Automated checks
      - name: Markdown lint
        run: npx markdownlint-cli2 'docs/**/*.md'
      
      - name: Spell check
        run: npx cspell 'docs/**/*.md'
      
      - name: Check links
        run: npx hyperlink docs/
      
      - name: Readability check
        run: npx write-good docs/**/*.md --no-passive
      
      # Assign reviewers
      - name: Assign reviewers
        uses: actions/github-script@v6
        with:
          script: |
            const reviewers = ['tech-writer-lead', 'sme-team'];
            await github.rest.pulls.requestReviewers({
              owner: context.repo.owner,
              repo: context.repo.repo,
              pull_number: context.issue.number,
              reviewers: reviewers
            });

Review Checklist Template

## Documentation Review Checklist

### Accuracy
- [ ] All technical claims verified by SME
- [ ] Code examples tested and working
- [ ] Screenshots match current UI
- [ ] Commands produce expected output

### Clarity
- [ ] Active voice used throughout
- [ ] Plain language — no unnecessary jargon
- [ ] Each sentence has one idea
- [ ] Steps are numbered and sequential

### Completeness
- [ ] All prerequisites listed
- [ ] Expected results described
- [ ] Error conditions documented
- [ ] Troubleshooting section included

### Structure
- [ ] Headings follow a logical hierarchy
- [ ] Most important information is first
- [ ] Related content is grouped together
- [ ] Navigation is clear (next steps, related topics)

### Formatting
- [ ] Consistent heading style (sentence case or title case)
- [ ] Code blocks have language tags
- [ ] Tables are properly formatted
- [ ] Links work and have descriptive text

Style Guide Essentials

A good style guide ensures consistency across all documentation, regardless of who writes it.

Voice and Tone Rules

## Voice

### Rule 1: Use Active Voice
❌ "The configuration file should be edited by the administrator."
✅ "Edit the configuration file."

### Rule 2: Use Second Person
❌ "Users should verify their email address."
✅ "Verify your email address."

### Rule 3: Use Present Tense
❌ "The system will process the request."
✅ "The system processes the request."

### Rule 4: Use Imperative Mood for Instructions
❌ "You should restart the server after updating."
✅ "Restart the server after updating."

Word Choice Guidelines

Formatting Conventions

- **UI Labels**: Bold, exact capitalization — "Click **Save**"
- **Code/Commands**: Inline code — "Run `npm install`"
- **File Names**: Inline code — "Edit `config.json`"
- **Variables**: Inline code, angle brackets — "Replace `<API_KEY>`"
- **Key Names**: Bold or keyboard style — "Press **Ctrl+C**"
- **Notes/Warnings**: Blockquote with label — "> **Note**: ..."
- **Cross-references**: As links — "See [Installation](#installation)"

Information Architecture

Organize content so users find what they need without thinking.

The Three-Click Rule

Users should be able to reach any piece of documentation within three clicks from the home page.

Home
├── Getting Started (1 click)
│   ├── Installation (2 clicks)
│   └── Quick Start (2 clicks)
├── Guides (1 click)
│   ├── Configuration (2 clicks)
│   │   ├── Environment Variables (3 clicks)
│   │   └── Feature Flags (3 clicks)
│   ├── Deployment (2 clicks)
│   └── Monitoring (2 clicks)
├── Reference (1 click)
│   ├── API (2 clicks)
│   └── CLI (2 clicks)
└── Support (1 click)
    ├── FAQ (2 clicks)
    └── Troubleshooting (2 clicks)

Content Types and Their Structure

Readability Scoring

Use automated tools to measure document quality:

# Flesch-Kincaid readability on markdown files
npx textlint --rule textlint-rule-write-good docs/**/*.md

# Automated readability checker
pip install readabili-cli
readabili-cli check docs/user-manual.md

# Hemingway-style analysis
# (aim for Grade 8-10 for user-facing docs)
npx hemingway-js docs/ --grade-level 8

Target readability scores by document type:

Doc-as-Code Automation

# .github/workflows/technical-writing.yml
name: Technical Writing Quality
on:
  pull_request:
    paths:
      - 'docs/**'
      - '**/*.md'

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Spell Check
        uses: streetsidesoftware/cspell-action@v2
        with:
          files: 'docs/**/*.md'
      
      - name: Markdown Lint
        run: |
          npx markdownlint-cli2 'docs/**/*.md' \
            --config .markdownlint.json
      
      - name: Link Check
        run: |
          npx hyperlink --recursive docs/
      
      - name: Readability Check
        run: |
          npx write-good docs/**/*.md \
            --no-passive \
            --no-illusion
      
      - name: Vale Style Check
        uses: errata-ai/vale-action@v2
        with:
          files: 'docs/**/*.md'
          styles: |
            https://github.com/errata-ai/write-good/releases/latest/download/write-good.zip

Common Mistakes

1. Writing without knowing the audience: A guide for senior engineers is useless to a new hire and vice versa. Always profile your reader first.

2. Passive voice overuse: "The button should be clicked" — no, "Click the button." Passive voice adds words and removes accountability.

3. Assuming prior knowledge: "Just set up the reverse proxy" is meaningless to someone who's never configured nginx. Define or link to prerequisites.

4. Inconsistent terminology: Using "start," "launch," "initialize," and "boot" interchangeably confuses readers. Pick one term per concept and use it consistently.

5. Skipping troubleshooting sections: Every procedure should answer "what if it doesn't work?" If there's no troubleshooting section, you're hiding failure modes.

6. No version control in docs: Documentation without version history is untrustworthy. Readers need to know when something was last verified.

7. Writing for yourself, not the reader: "As we all know..." or "Clearly..." dismisses the reader's perspective. If it's obvious, don't write it. If it's not obvious, explain it.

8. Prose without structure: Walls of text are never read. Use headings, lists, tables, and code blocks to break content into digestible chunks.

9. No examples: Abstract instructions are hard to follow. Every concept needs at least one concrete example.

10. Not testing the documentation: Read your own docs as if you've never seen the product. Better yet, have someone new follow them and watch where they struggle.

Evaluation Rubric