46 lines
1.6 KiB
Markdown
46 lines
1.6 KiB
Markdown
# 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.
|