Technical Writer

Technical Writer

Create clear, comprehensive technical documentation for any audience.

Contents

• references/templates.md — structure templates (user guide, tutorial, architecture)
• references/best-practices.md — clarity, structure, visuals, code, and quality checklist
• references/special-types.md — README, release notes, troubleshooting guide requirements
• references/output-format.md — final delivery wrapper and maintenance notes

Workflow

1. Identify the documentation type. See references/special-types.md for the full type list and type-specific section requirements.

2. Determine the audience:

• Technical level (beginner, intermediate, expert)
• Role (end user, developer, admin, stakeholder)
• Prior knowledge assumptions
• Context (internal team, external customers, open source community)

3. Select and fill the matching structure template from references/templates.md. Start simple, then layer in complexity.

4. Apply technical writing best practices from references/best-practices.md: short sentences, active voice, specific instructions, scannable structure, runnable code examples, and a user-focused angle.

5. Verify the draft against the output quality checklist in references/best-practices.md.

6. Deliver using the wrapper in references/output-format.md, including the documentation checklist and maintenance notes.

Example Triggers

• "Write user documentation for my feature"
• "Create a tutorial for setting up the development environment"
• "Document this system architecture"
• "Write a troubleshooting guide"
• "Create onboarding documentation for new developers"
• "Write a README for this project"

Generate professional, comprehensive technical documentation that enables users to succeed.

Technical Writing Best Practices

Apply these standards to every documentation deliverable.

Clarity

• Use short sentences (aim for 15-20 words).
• Avoid jargon, or define it when first used.
• Use active voice ("Click the button" not "The button should be clicked").
• Be specific ("Set timeout to 30 seconds" not "Set a reasonable timeout").

Structure

• Use descriptive headings.
• Break content into scannable sections.
• Use numbered lists for sequences.
• Use bullet points for unordered items.
• Add a table of contents for long docs.

Visuals

• Include screenshots with annotations.
• Add code examples with syntax highlighting.
• Use diagrams for complex concepts.
• Show expected outputs.
• Add tables for comparison or reference.

Code Examples

• Include the language identifier.
• Show both good and bad examples.
• Add comments explaining complex parts.
• Use realistic, runnable examples.
• Include error handling.

User-Focused

• Start with the most common use case.
• Include "why" not just "how".
• Anticipate user questions.
• Address common pitfalls.
• Provide troubleshooting.

Output Quality Checklist

Confirm the documentation:

• Has a clear, descriptive title.
• Starts with overview/context.
• Lists prerequisites upfront.
• Uses consistent formatting.
• Includes code examples where appropriate.
• Shows expected outputs.
• Has a troubleshooting section.
• Uses the appropriate technical level for the audience.
• Is structured logically (simple to complex).
• Includes visual aids (diagrams, screenshots).
• Has a table of contents for long docs.
• Links to related documentation.
• Is easy to scan.
• Uses active voice.
• Avoids ambiguity.
• Includes examples from the user perspective.

Output Format

Wrap the completed documentation in this delivery structure.

TECHNICAL DOCUMENTATION
Type: [User Guide/Tutorial/Architecture/etc.]
Audience: [Target audience]
Level: [Beginner/Intermediate/Advanced]

----------------------------------------
[Full markdown documentation]
----------------------------------------

DOCUMENTATION CHECKLIST
----------------------------------------

- Clear overview and purpose
- Prerequisites listed
- Step-by-step instructions
- Code examples included
- Expected outputs shown
- Troubleshooting section
- Links to related docs
- Scannable structure
- Appropriate for audience level

MAINTENANCE NOTES
----------------------------------------

Review Triggers:
- [When to update this doc]
- [Dependencies that might change]

Related Documentation:
- [Link to related docs]

Special Documentation Types

Section requirements for common document types.

README.md

• Project name and description
• Installation instructions
• Quick start example
• Features list
• Documentation links
• Contributing guidelines
• License

Release Notes

• Version number and date
• New features
• Improvements
• Bug fixes
• Breaking changes
• Migration guide
• Deprecation notices

Troubleshooting Guide

• Symptom-based organization
• Root cause analysis
• Step-by-step resolution
• Prevention tips
• When to escalate

Documentation Type Reference

Identify which type applies before drafting:

• User guide / end-user documentation
• Developer documentation / API docs
• System architecture documentation
• Tutorial / how-to guide
• Troubleshooting guide
• README file
• Release notes / changelog
• Onboarding documentation
• Knowledge base article
• Standard Operating Procedure (SOP)

Documentation Structure Templates

Use the template that matches the documentation type. Replace all bracketed placeholders with real content.

User Guide Format

# [Product/Feature Name]

## Overview
[What it is, what it does, why use it - 2-3 sentences]

## Prerequisites
- [Required knowledge]
- [Required tools/access]
- [System requirements]

## Getting Started
[Quick start guide with minimal steps to first success]

### Step 1: [Action]
[Detailed instructions with screenshots/code]

### Step 2: [Action]
[Detailed instructions]

## Key Concepts
### [Concept 1]
[Explanation with examples]

## Common Tasks
### How to [Task]
1. [Step]
2. [Step]
3. [Expected result]

## Advanced Features
[Optional advanced functionality]

## Troubleshooting
### Problem: [Common issue]
**Symptoms**: [What users see]
**Solution**: [How to fix]

## FAQ
**Q: [Question]**
A: [Answer]

## Additional Resources
- [Link to related docs]
- [Support channels]

Tutorial Format

# How to [Accomplish Goal]

**Time required**: [X minutes]
**Difficulty**: [Beginner/Intermediate/Advanced]

## What You'll Learn
- [Learning objective 1]
- [Learning objective 2]

## Prerequisites
- [Required knowledge]
- [Tools needed]

## Step-by-Step Instructions

### 1. [First Major Step]
[Explanation of why this step matters]

[Code example]

**Expected output**:

[What users should see]

### 2. [Next Major Step]
[Continue pattern]

## Verification
[How to confirm it worked]

## Next Steps
[What to learn next]

## Troubleshooting
[Common issues]

Architecture Documentation Format

# [System Name] Architecture

## Overview
[High-level description, purpose, key characteristics]

## Architecture Diagram
[ASCII diagram or description for diagram]

## Components
### [Component 1]
**Purpose**: [What it does]
**Technology**: [Stack/framework]
**Responsibilities**:
- [Responsibility 1]
- [Responsibility 2]

**Interfaces**:
- Input: [Data/requests it receives]
- Output: [Data/responses it produces]

## Data Flow
1. [Step-by-step flow through system]

## Technology Stack
- **Frontend**: [Technologies]
- **Backend**: [Technologies]
- **Database**: [Technologies]
- **Infrastructure**: [Technologies]

## Design Decisions
### Why [Technology/Pattern]?
[Rationale, alternatives considered, trade-offs]

## Scalability Considerations
[How system scales, bottlenecks, mitigation strategies]

## Security
[Authentication, authorization, data protection]

## Monitoring and Observability
[Logging, metrics, alerting]