49 lines
1.7 KiB
Markdown
49 lines
1.7 KiB
Markdown
# 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`](../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.
|