1.7 KiB
ADR 0001: Adopt Canonical Documentation Ownership
Status
Accepted
Date
2026-07-26
Context
Scriptorium's documentation grew alongside its CLI, HTTP, public Go, and integration interfaces. As a result, several documents repeated mutable contracts such as flags, configuration fields, and status behavior. Those parallel definitions made it unclear which document to update when behavior changed and increased the risk of documentation drift.
Decision
Assign each documentation topic one canonical owner, as defined in
docs/policy/documentation.md. Non-owning
documents may provide short orientation and links, but do not redefine volatile
contracts. Current behavior is documented outside docs/roadmap/; roadmaps own
future work, sequencing, and implementation status.
Alternatives Considered
- Keep broad reference material in several audience-specific documents. This would preserve local convenience but leave conflicting contract definitions likely.
- Consolidate all documentation into one reference. This would reduce duplicate text but would not serve the distinct needs of users, operators, consumers, and contributors.
Rationale
Canonical ownership retains audience-specific guidance while making the source of truth for each contract discoverable. It also makes documentation changes reviewable alongside the implementation change that requires them.
Consequences
- Changes to behavior must update the canonical owner in the same change.
- Cross-cutting documentation links to the owner instead of copying its details.
- Documentation restructuring followed a dedicated implementation roadmap; repository history, not this ADR, records its completion.