# Technical Writing

> Technical Writing Mastery: SOPs, user manuals, guides, release notes, and professional technical documentation

- Skill: `gabrielmoreira/technical-writing` (Agent Skill)
- Install (CLI): `npx skillmds@latest add gabrielmoreira/technical-writing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gabrielmoreira/technical-writing/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: gabrielmoreira (https://skillmd.com/u/gabrielmoreira)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/gabrielmoreira/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

| Level | Audience Awareness | Style Consistency | Structure | Review Process | Maintenance |
|-------|-------------------|-------------------|-----------|----------------|-------------|
| **1: Ad Hoc** | None — one-size-fits-all | Inconsistent tone and voice | No headings, walls of text | No review | Never updated |
| **2: Basic** | Some awareness of primary audience | Mostly consistent | Basic headings, some lists | Peer review occasionally | Updated for major releases |
| **3: Structured** | Audience-defined docs for different readers | Style guide followed | Clear hierarchy, tables, scanned layout | Dedicated review cycle | Updated with each release |
| **4: Systematic** | Persona-based documentation | Automated style linting | Information architecture mapped | SME + editor review | Versioned, changelog maintained |
| **5: Exemplary** | Proactive content based on user analytics | Programmatic consistency enforced | Modular, reusable content components | Automated + multi-stage review | Continuous updates, feedback-driven |

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

---

## Actionable Guidance

### Audience Analysis Matrix

Before writing anything, map your audience:

| Audience | Goal | Knowledge Level | Document Type | Tone |
|----------|------|-----------------|---------------|------|
| End User | Complete a task | Low | User manual, quick start guide | Simple, supportive |
| Administrator | Configure/maintain a system | Medium-High | Admin guide, runbook | Direct, precise |
| Developer | Integrate or extend | High | API reference, developer guide | Technical, complete |
| Executive | Understand value/status | Low-Medium | Overview, decision doc | Strategic, concise |
| Support Team | Troubleshoot issues | Medium | Knowledge base, FAQ | Thorough, structured |

**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

```markdown
# 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
| Version | Date | Author | Changes |
|---------|------|--------|---------|
| 1.0 | YYYY-MM-DD | [Name] | Initial version |
```

---

### 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)

```markdown
# 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

```markdown
# 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

| Change Type | Version Bump | Example |
|-------------|-------------|---------|
| Minor correction (typo, formatting) | Patch | v1.0.0 → v1.0.1 |
| New section or procedure added | Minor | v1.0.0 → v1.1.0 |
| Major restructuring or rewrite | Major | v1.0.0 → v2.0.0 |
| Software version change | Match software version | v2.4.0 docs |

#### Version Tracking in Documents

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

```markdown
## 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

```text
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

```yaml
# .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

```markdown
## 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

```markdown
## 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

| Use This | Not This | Reason |
|----------|----------|--------|
| start / stop | initiate / terminate | Simpler |
| use | utilize | Fewer syllables |
| set up | configure | More direct |
| fix | resolve | Clearer |
| show | display | More natural |
| help | assist | Less formal |
| send | transmit | More common |

#### Formatting Conventions

```markdown
- **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.

```text
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

| Content Type | Purpose | Structure |
|-------------|---------|-----------|
| Tutorial | Learning by doing | Step-by-step, numbered, with expected outcomes |
| How-to Guide | Completing a task | Prerequisites, steps, verification |
| Reference | Looking up information | Alphabetical or categorical, consistent format |
| Explanation | Understanding concepts | Problem → Solution → Trade-offs |
| SOP | Consistent execution | Purpose → Prerequisites → Steps → Verification |
| Release Notes | Announcing changes | Features → Fixes → Deprecations → Migration |

---

### Readability Scoring

Use automated tools to measure document quality:

```bash
# 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:**

| Document Type | Flesch-Kincaid Grade Level | Flesch Reading Ease |
|--------------|---------------------------|---------------------|
| End-user manual | 6-8 | 60-70 |
| Admin guide | 8-10 | 50-60 |
| Developer guide | 10-12 | 40-50 |
| API reference | 12+ | 30-40 |
| SOP | 8-10 | 50-60 |

---

### Doc-as-Code Automation

```yaml
# .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

| Criterion | 1 - Beginning | 2 - Developing | 3 - Proficient | 4 - Advanced |
|-----------|--------------|----------------|----------------|---------------|
| **Audience Awareness** | No audience defined | Basic audience identified | Persona-based content | Adaptive content for multiple personas |
| **Style Consistency** | No style guide | Informal style guide | Documented and followed style guide | Automated style enforcement in CI |
| **Information Architecture** | No structure | Basic headings | Clear hierarchy with navigation | Modular, reusable content components |
| **Review Process** | No review | Occasional peer review | Structured SME + editor review | Automated checks + multi-stage review |
| **Accuracy** | Often outdated | Occasionally verified | Verified at each release | Validated in CI with automated tests |
| **Readability** | Grade 15+ | Grade 12-14 | Grade 8-11 | Grade 6-8 (for user docs) |
| **Maintenance** | Never updated | Updated reactively | Updated on schedule | Continuously improved via feedback |