Technical Writing

Technical Writing

This skill guides internal engineering documentation (specs, architecture, runbooks, API references, changelogs)—not marketing or end-user product docs unless the task says otherwise.

How to use it: follow Instructions (Steps 1–5) in order. For copy-paste skeletons, use Step 2 and Document templates. For the user’s final document, use normal Markdown and three backticks for code fences. In this skill file only, some templates use four leading backticks on the outer fence so inner triple-backtick samples do not break the fence pairing.

When to use this skill

• Writing technical specifications
• Creating architecture documentation
• Documenting system designs
• Writing runbooks and operational guides
• Creating developer documentation
• API documentation
• User manuals and guides
• Release notes and changelogs

Instructions

Step 1: Understand your audience

Developer audience:

• Focus on implementation details
• Include code examples
• Technical terminology is okay
• Show how, not just what

DevOps/Operations audience:

• Focus on deployment and maintenance
• Include configuration examples
• Emphasize monitoring and troubleshooting
• Provide runbooks

Manager/Stakeholder audience:

• High-level overview
• Business impact
• Minimal technical jargon
• Focus on outcomes

End user audience:

• Simple, clear language
• Step-by-step instructions
• Visual aids (screenshots, videos)
• FAQ section

Step 2: Choose the right document type

Technical Specification:

````markdown

[Feature Name] Technical Specification

Overview

Brief description of what this spec covers

Problem Statement

What problem are we solving?

Goals and Non-Goals

Goals

• Goal 1
• Goal 2

Non-Goals

• What we're explicitly not doing

Solution Design

High-Level Architecture

Data Models

API Contracts

User Interface

Implementation Plan

Phase 1

Phase 2

Testing Strategy

Security Considerations

Performance Considerations

Monitoring and Alerting

Rollout Plan

Rollback Plan

Open Questions

References

````

Architecture Document:

````markdown

System Architecture

Overview

High-level system description

Architecture Diagram

[Insert diagram]

Components

Component 1

• Responsibility
• Technology stack
• Interfaces

Component 2

_Repeat the same subsections (responsibility, stack, interfaces) for each additional component._

Data Flow

How data moves through the system

Key Design Decisions

Decision 1

• Context
• Options considered
• Decision made
• Rationale

Technology Stack

• Frontend: React, TypeScript
• Backend: Python, FastAPI
• Database: PostgreSQL
• Infrastructure: AWS, Docker, Kubernetes

Scalability

How the system scales

Security

Authentication, authorization, data protection

Monitoring and Observability

Metrics, logs, tracing

Disaster Recovery

Backup and recovery procedures

Future Considerations

````

Runbook:

````markdown

[Service Name] Runbook

Service Overview

What this service does

Dependencies

• Service A
• Service B
• Database X

Deployment

How to deploy

./deploy.sh production

Rollback

./rollback.sh

Monitoring

Key Metrics

• Request rate
• Error rate
• Latency

Dashboards

• Production Dashboard
• Alerts

Common Issues

Issue 1: High latency

Symptoms: Response time > 1s Diagnosis: Check database connection pool Resolution: Restart service or scale up

Issue 2: Memory leak

Symptoms: Memory usage growing over time Diagnosis: Check heap dump Resolution: Restart service, investigate in staging

Troubleshooting

How to check logs

kubectl logs -f deployment/service-name

How to access metrics

curl https://api/metrics

Emergency Contacts

• On-call: PagerDuty
• Team Slack: #team-name

````

API Documentation:

````markdown

API Documentation

Authentication

All requests require authentication:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.example.com/endpoint

Endpoints

List Users

GET /api/v1/users

Parameters:

Example Request:

curl -X GET "https://api.example.com/api/v1/users?page=1&limit=20" \
  -H "Authorization: Bearer YOUR_TOKEN"

Example Response:

{
  "data": [
    {
      "id": 1,
      "name": "John Doe",
      "email": "john@example.com"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100
  }
}

Error Responses:

````

Step 3: Writing guidelines

Clarity:

• Use simple, direct language
• One idea per sentence
• Short paragraphs (3-5 sentences)
• Define technical terms
• Avoid jargon when possible

Structure:

• Use hierarchical headings (H1, H2, H3)
• Break content into sections
• Use lists for multiple items
• Use tables for structured data
• Add table of contents for long docs

Examples:

• Include code examples
• Provide diagrams
• Show before/after comparisons
• Real-world scenarios

Completeness:

• Cover prerequisites
• Include error handling
• Document edge cases
• Explain why, not just how
• Link to related docs

Consistency:

• Consistent terminology
• Consistent formatting
• Consistent code style
• Consistent structure

Step 4: Visual aids

Architecture diagrams (Mermaid):

graph TB
    A[Client] -->|HTTP| B[Load Balancer]
    B --> C[Web Server 1]
    B --> D[Web Server 2]
    C --> E[Database]
    D --> E

Sequence diagrams:

sequenceDiagram
    Client->>+Server: Request
    Server->>+Database: Query
    Database-->>-Server: Data
    Server-->>-Client: Response

Flowcharts:

flowchart TD
    A[Start] --> B{Is valid?}
    B -->|Yes| C[Process]
    B -->|No| D[Error]
    C --> E[End]
    D --> E

Code blocks with syntax highlighting:

def calculate_total(items: List[Item]) -> Decimal:
    """Calculate total price of items."""
    return sum(item.price for item in items)

Screenshots:

• Use for UI documentation
• Annotate important parts
• Keep up-to-date with UI changes

Tables:

Step 5: Review and refine

Self-review checklist:

• [ ] Clear purpose stated upfront
• [ ] Logical flow of information
• [ ] All terms defined
• [ ] Code examples tested
• [ ] Links work
• [ ] Diagrams are clear
• [ ] No typos or grammar errors
• [ ] Consistent formatting
• [ ] Table of contents (if needed)
• [ ] Last updated date

Get feedback:

• Have someone from target audience review
• Test instructions (can they follow them?)
• Check for missing information
• Verify accuracy

Maintain documentation:

• Update with code changes
• Version your docs
• Archive outdated docs
• Regular review cycle

Document templates

Technical Spec Template

````markdown

[Feature Name] Technical Spec

Author: [Your Name] Date: [Date] Status: [Draft/Review/Approved]

Overview

[1-2 paragraphs describing what this document covers]

Background

[Context and motivation]

Goals

• Goal 1
• Goal 2

Non-Goals

• What we're not doing

Detailed Design

[Technical details]

Alternatives Considered

[Other approaches and why we didn't choose them]

Timeline

• Week 1: ...
• Week 2: ...

Open Questions

• Question 1
• Question 2

Features

• Feature 1
• Feature 2

Installation

Prerequisites

• Node.js (current LTS) or the version in the repository
• Package manager: npm, pnpm, or yarn as used by the project

Setup

git clone https://github.com/user/project.git
cd project
npm install

Usage

npm start

Configuration

Environment variables:

• API_KEY: Your API key
• PORT: Server port (default: 3000)

Development

npm run dev
npm test

Deployment

[Deployment instructions]

Contributing

[Contributing guidelines]

License

MIT

````

Changelog Template

````markdown

Changelog

[1.2.0] - 2026-01-15

Added

• New feature X
• Support for Y

Changed

• Improved performance of Z
• Updated dependency A to v2.0

Fixed

• Bug where user could not log in
• Memory leak in background task

Deprecated

• Old API endpoint /v1/users (use /v2/users)

Removed

• Legacy authentication method

Security

• Fixed XSS vulnerability in comments

[1.1.0] - 2025-10-01

… ````

Writing tips

Use active voice

✅ Good: "The system sends a notification"
❌ Bad: "A notification is sent by the system"

Be concise

✅ Good: "Click Save to save changes"
❌ Bad: "In order to save your changes, you should click on the Save button"

Use examples

```` ✅ Good: "Set the timeout in seconds:

timeout: 30

❌ Bad: "Configure the timeout parameter appropriately" ````

Break down complexity

✅ Good:
"To deploy:

1. Build the image
2. Push to registry
3. Update deployment
4. Verify rollout"

❌ Bad:
"Deploy by building and pushing the image to the registry, then update
the deployment and verify the rollout succeeded"

Common mistakes to avoid

1. Assuming knowledge: Define terms, explain context 2. Outdated docs: Keep in sync with code 3. Missing examples: Always include examples 4. No visuals: Use diagrams for complex concepts 5. Poor structure: Use headings and sections 6. Passive voice: Use active voice 7. Too much jargon: Write for your audience 8. No version info: Date docs, note versions 9. Missing error cases: Document what can go wrong 10. No maintenance: Update regularly

Best practices

1. Write for your audience: Match their knowledge level 2. Start with why: Explain the purpose 3. Show, don't just tell: Use examples 4. Be consistent: Terminology, style, structure 5. Test your docs: Can someone follow them? 6. Version your docs: Track with code versions 7. Use templates: Consistency across docs 8. Link related docs: Help readers find more info 9. Update with code: Docs are part of the code 10. Review regularly: Quarterly doc review

Tools

Diagram tools:

• Mermaid (markdown-based)
• Draw.io
• Lucidchart
• PlantUML

Documentation platforms:

• GitBook
• Docusaurus
• MkDocs
• Sphinx

Style checkers:

• Grammarly
• Hemingway Editor
• Vale

Screenshot tools:

• Snagit
• CloudApp
• Loom (for videos)

Examples (where to look in this skill)

• Spec or design write-up: use the Technical Specification and Detailed Design patterns in Step 2 and the Technical Spec Template in Document templates; fill [placeholders] with repo-specific names and decisions.
• Runbook or ops doc: use the Runbook block in Step 2; replace links, service names, and commands with the user’s environment.
• API reference: use the API Documentation block in Step 2; add endpoints, request/response bodies, and error tables from the actual API.
• Release notes: use Changelog Template; set versions and dates to match the project’s release process.

Do not leave HTML comments or “TODO” placeholders in the document you hand off—either complete a section or remove it and say what is out of scope.