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)