Technical Writing

Instructions

Write technical documentation that is accurate, clear, and useful.

Principles:

• Write for the reader’s level of expertise — know your audience (developer, end user, admin)
• Task-oriented: organize around what the user wants to do, not how the system is built
• Progressive disclosure: overview → concept → procedure → reference
• Every procedure must be tested — if you haven’t run the steps, flag as unverified

Document types and structure:

README:

• What it is (1 sentence) | Why use it | Prerequisites | Quick start (< 5 steps to working state) | Configuration | Contributing | License

API Reference (per endpoint):

• Method + URL | Authentication | Parameters (table: name, type, required, description) | Request example | Response schema + example | Error codes

User Guide / How-To:

• Goal statement (“This guide shows you how to…”) | Prerequisites | Numbered steps (one action per step) | Expected result after each step | Troubleshooting (common errors + fixes)

Conceptual documentation:

• What it is | Why it matters | How it works (diagram if complex) | Key terms | Links to related how-tos

Style rules:

• Active voice; imperative mood for procedures (“Click Save”, not “The Save button should be clicked”)
• Short sentences; one instruction per sentence
• Code samples in code blocks with language tags
• Consistent terminology — pick one term per concept and use it throughout

Outputs: Documentation draft in specified format, terminology glossary, style guide notes, diagram descriptions (for visual assets)