technical-writing

name	technical-writing
description	Technical Writing Mastery: SOPs, user manuals, guides, release notes, and professional technical documentation
metadata	{"author":"cosmicstack-labs","version":"1.0.0","category":"development","tags":["technical-writing","sop","user-manual","documentation","guides"]}

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

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

# 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

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:

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

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

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

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:

# 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

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