Establish canonical developer documentation structure

This commit is contained in:
2026-07-26 14:06:55 +00:00
parent e0b1d6a0dc
commit 6d1fb66dd7
6 changed files with 176 additions and 75 deletions

View File

@@ -0,0 +1,49 @@
# 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 follows the implementation sequence in
[`docs/roadmap/documentation.md`](../roadmap/documentation.md); the roadmap,
not this ADR, records completion status.