# 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/)