1.6 KiB
1.6 KiB
Technical Documentation
Purpose
Create or update documentation that helps developers, operators, or advanced users understand how the system works and how to use it correctly.
When to use
- Updating docs after engineering changes
- Writing usage guides, architecture notes, or operational docs
- Explaining APIs, workflows, configuration, or system behavior
- Improving stale or incomplete technical documentation
Inputs to gather
- The current implementation and the user-visible workflow
- Existing docs, terminology, and structure in the repo
- Intended audience and their technical depth
- Any setup steps, caveats, or common failure points
How to work
- Document the real behavior of the system, not the hoped-for design.
- Prefer task-oriented structure when users need to get something done.
- Use precise terminology that matches the code and UI.
- Include examples, prerequisites, and pitfalls when they materially improve clarity.
- Keep docs aligned with adjacent pages and avoid fragmenting the source of truth.
Output expectations
- Clear, accurate documentation update or new draft
- Audience-appropriate level of technical detail
- Explicit caveats, prerequisites, and compatibility notes when relevant
Quality checklist
- Instructions are accurate against the current implementation.
- The document helps someone complete a real task or understand a real concept.
- Terms and examples are consistent with the product and codebase.
- Important caveats are easy to find.
Handoff notes
- Mention what was verified directly in code versus inferred from context.
- Note any related docs that should be updated later to stay consistent.