technical-writing

Select the architectural overview profile, which structures the document around system scope, domain model, subsystem architecture, runtime lifecycles, and failure modes. Describe the target architecture in present tense and verify every behavioral claim against the implementation source.

Use the API documentation profile: state the caller-visible action, parameter bounds, return guarantees, error conditions, and concurrency contract. Inspect implementations, callers, and tests first, and avoid restating signatures or exposing private internals.

An RFC proposes and evaluates a change against alternatives before acceptance. An ADR records one accepted decision with its constraints and consequences. An implementation plan sequences an accepted design into dependency-ordered, verifiable engineering tasks.

Add comments only when correctness depends on context the syntax cannot convey, such as non-obvious domain rules, safety preconditions, concurrency protocols, or hardware quirks. State the invariant preserved and the failure mode prevented, and delete comments once refactoring makes constraints explicit.

Use the tutorial profile: pin exact tool versions, build one runnable project through small milestones, and end each milestone with a deterministic verification command. Execute the entire tutorial in a clean environment before publishing.