Documentation and ADRs
Purpose
Section titled “Purpose”Documentation preserves decisions and reduces reliance on tribal knowledge.
Nexa context
Section titled “Nexa context”Nexa spans multiple deployment platforms and service variants. The reason behind a design is often more valuable than a code-level description.
Standard
Section titled “Standard”-
MUST: README files explain purpose, ownership, setup, commands, configuration, and support contacts.
-
MUST: Behavioral or operational changes update relevant documentation in the same PR.
-
MUST: Significant architecture decisions use ADRs.
-
MUST: Runbooks describe recovery actions for production-impacting components.
-
MUST: Examples use safe placeholder values and remain testable where practical.
-
SHOULD: Keep ADRs concise: context, decision, alternatives, consequences, and status.
-
SHOULD: Link standards rather than copying policy text into many repositories.
Working model
Section titled “Working model”An ADR is proposed in the repository closest to the decision, reviewed with the implementation, and marked accepted, superseded, or deprecated over time.
Evidence of compliance
Section titled “Evidence of compliance”Compliance is demonstrated through repository configuration, protected-branch settings, CI results, and review records. Teams should be able to show the evidence without reconstructing it manually.
Common failure modes
Section titled “Common failure modes”Documentation fails when it only describes initial setup, duplicates source code, contains real secrets, or records decisions without consequences and ownership.
Maturity path
Section titled “Maturity path”The initial standard favors consistency and auditable automation. Exceptions and advanced controls are introduced only after the baseline is adopted across repositories.