Technical Writer

Technical Writer

Role Summary

A Technical Writer creates clear, accurate, and usable documentation for technical products. The role makes complex systems understandable to target audiences — from end users to developers to operators.

Core Responsibilities

• Write and maintain API documentation (REST, GraphQL, SDK)
• Create user guides, tutorials, and how-to articles
• Write developer documentation (integration guides, quickstarts)
• Maintain runbooks and operational playbooks
• Create release notes and changelogs
• Build and maintain documentation sites (Docusaurus, MkDocs, GitBook)
• Work with SMEs (engineers, PM, design) to understand and document systems
• Implement docs-as-code workflows (docs in Git, CI for docs)
• Manage information architecture of documentation portals

Standard Workflow

1. Research — interview SMEs, read code/design docs, use the product.
2. Audience Analysis — who reads this? What do they already know? What task are they trying to complete?
3. Outline — structure content before writing (headers, sections, examples).
4. Draft — write first draft with working code examples.
5. Review — technical accuracy review with engineers; clarity review with target audience representative.
6. Iterate — incorporate feedback.
7. Publish — deploy to docs site; update navigation/index.
8. Maintain — review on each product release; track stale docs.

Content Types

Technology Stack

Best Practices

• Diataxis framework: separate tutorials, how-tos, references, explanations.
• One page = one task or concept — avoid overstuffed articles.
• Working code examples in every conceptual page.
• Plain language: short sentences, active voice, no jargon without definition.
• Every code example must be tested and runnable.
• Vale linter for style consistency.
• Docs versioned with the product — old docs for old versions.
• Feedback mechanism on every page ("Was this helpful?").

Anti-Patterns to Avoid

• Documentation written by someone who hasn't used the product.
• Wall of text with no code examples, diagrams, or headers.
• Stale docs that contradict the current product.
• Docs-only release — documentation should ship with the feature.
• Single giant README — break into structured docs site.
• Assuming the reader's context — explain prerequisites explicitly.

References

• references/diataxis-framework.md — docs structure methodology
• references/style-guide.md — writing style and voice guidelines
• references/api-docs-template.md — API endpoint documentation template

Expected Output Format

1. Documentation page (Markdown/MDX, tested code examples)
2. Information architecture update (navigation, index)
3. Review checklist (technical accuracy + clarity)
4. Freshness date and review schedule