66 lines
2.6 KiB
Markdown
66 lines
2.6 KiB
Markdown
# Documentation Writing Guide
|
|
|
|
## Goals
|
|
|
|
Repository documentation must be accurate, concise, and useful to both people and coding agents.
|
|
|
|
## Document Roles
|
|
|
|
| Document type | Content |
|
|
|---------------|---------|
|
|
| README | Project entry point and runnable paths |
|
|
| Architecture | Current structure, responsibilities, and enforced boundaries |
|
|
| Development | Commands and operational procedures |
|
|
| Roadmap | Available, planned, and future capabilities |
|
|
| Architecture Decision Record (ADR) | One technical decision, its context, and its consequences |
|
|
| `AGENTS.md` | Durable agent workflow, conventions, verification, and constraints |
|
|
|
|
Keep each fact in its canonical document. Link to that document from other locations.
|
|
|
|
## Current-State Writing
|
|
|
|
- Use English, active voice, and present tense.
|
|
- Name the component that performs each action.
|
|
- Put one fact or instruction in each sentence or list item.
|
|
- Prefer short sections, lists, and tables.
|
|
- State the supported path before optional details.
|
|
- Use `must` for requirements, `can` for optional behavior, and present tense for existing behavior.
|
|
- Use current commands, symbols, routes, and examples.
|
|
|
|
## Constraints and Anti-Patterns
|
|
|
|
Keep a negative rule **only when** it prevents a current and plausible mistake with a meaningful cost. This includes:
|
|
|
|
- Tooling traps that reduce reproducibility or pollute context
|
|
- Architecture boundaries enforced by tests
|
|
- Security, authorization, and destructive-action limits
|
|
- Commit and dependency-change authorization
|
|
|
|
Place the rule near the affected workflow and provide the supported path. Keep one canonical copy when the same audience reads multiple documents.
|
|
|
|
Remove or move a negative statement when it describes a hypothetical design, repeats a positive contract, or explains an obsolete implementation. Preserve material history in the relevant ADR instead.
|
|
|
|
## Decision Records
|
|
|
|
- Record one logical decision per ADR.
|
|
- Put the status before the body.
|
|
- Describe requirements and forces in Context.
|
|
- State the selected design in Decision.
|
|
- Record current trade-offs in Consequences.
|
|
- Link superseded records to their replacement.
|
|
- Use past tense for historical implementation details.
|
|
|
|
## Review Checklist
|
|
|
|
1. Confirm the document type and audience.
|
|
2. Verify facts against code and configuration.
|
|
3. Remove duplicated current-state information.
|
|
4. Check every negative statement for a current action or decision.
|
|
5. Verify commands, examples, and local links.
|
|
6. Run `git diff --check`.
|
|
|
|
## References
|
|
|
|
- [OpenAI Codex best practices](https://learn.chatgpt.com/guides/best-practices)
|
|
- [Architectural Decision Records](https://adr.github.io/)
|