mygo/docs/writing-guide.md

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
• Architectural Decision Records