131 lines
5.8 KiB
Markdown
131 lines
5.8 KiB
Markdown
# Documentation Policy Migration
|
|
|
|
The documentation ownership policy has been revised to assign each topic to one
|
|
canonical document. This roadmap organizes the likely migration work into three
|
|
ordered passes.
|
|
|
|
This is a planning inventory, not a review of the current documents. Each item
|
|
must be verified before content is moved, removed, or rewritten. Complete the
|
|
passes in order so canonical content is established before non-owning copies are
|
|
removed.
|
|
|
|
## Pass 1: User And Operator Contracts
|
|
|
|
Establish the canonical externally observable facts first. These documents will
|
|
become the targets linked from developer and internal documentation in the next
|
|
pass.
|
|
|
|
### Product And CLI
|
|
|
|
- Audit `README.md` so it owns product orientation and the single minimal
|
|
end-to-end quickstart without becoming a command or configuration reference.
|
|
- Audit `docs/cli.md` for material owned by the README, configuration reference,
|
|
or operations guide.
|
|
- Keep commands, arguments, flags, invocation semantics, and exit codes
|
|
canonical in `docs/cli.md`.
|
|
|
|
### Configuration And Examples
|
|
|
|
- Audit `docs/config.md` for complete example files, CLI syntax, runtime state
|
|
lifecycle, or implementation detail.
|
|
- Keep fields, defaults, precedence, environment overrides, validation, and
|
|
user-selectable module and validator keys canonical in `docs/config.md`.
|
|
- Audit minimal and production-oriented configuration examples, moving complete
|
|
copyable files under `examples/` and leaving only small illustrative fragments
|
|
in reference documentation.
|
|
- Inventory complete configuration, input, command, and output examples embedded
|
|
in prose documents.
|
|
- Select one maintained copy for each complete artifact under `examples/` where
|
|
practical, and verify important examples through automated tests.
|
|
|
|
### Operations And Integrations
|
|
|
|
- Audit `docs/operations.md` for duplicated CLI syntax, configuration field
|
|
definitions, logical output schemas, or implementation mechanics.
|
|
- Keep runtime workflows, physical state, retention, recovery, permissions, and
|
|
operational limits canonical in `docs/operations.md`.
|
|
- Audit `docs/integrations/` so external formats, protocols, logical output
|
|
paths, schemas, media types, and compatibility rules have one canonical home.
|
|
- Separate logical output bundle contracts from physical runtime placement and
|
|
lifecycle.
|
|
|
|
### Pass 1 Completion
|
|
|
|
- Confirm that README, CLI, configuration, operations, integrations, and
|
|
examples have non-overlapping ownership.
|
|
- Validate user-facing commands, fields, defaults, keys, schemas, paths, and
|
|
maintained examples against implemented behavior.
|
|
- Validate links among the user and operator documents.
|
|
|
|
## Pass 2: Developer And Internal Documentation
|
|
|
|
Use the canonical contracts established in Pass 1 to remove duplicated facts
|
|
from contributor and implementation documentation.
|
|
|
|
### Orientation And Architecture
|
|
|
|
- Audit `docs/development.md` so it routes contributors without maintaining a
|
|
parallel package inventory or architectural description.
|
|
- Audit `docs/internal/overview.md` so it owns the implemented component map
|
|
without restating normative architecture.
|
|
- Audit `docs/policy/architecture.md` so it contains current normative
|
|
architecture without implementation inventory, decision history, or future
|
|
behavior.
|
|
|
|
### Internal Components
|
|
|
|
- Audit internal component documents for repeated configuration definitions,
|
|
external input or output schemas, operator procedures, and global
|
|
architectural invariants.
|
|
- Replace duplicated external schemas or field definitions with links to the
|
|
canonical configuration or integration contracts from Pass 1.
|
|
- Keep implementation flow, internal collaborators, state transitions,
|
|
package-local guarantees, failures, and relevant tests in focused internal
|
|
documents.
|
|
- Identify task-specific contributor recipes that need a focused internal home
|
|
rather than the developer landing page.
|
|
- Retain production module and validator implementation details in module
|
|
internals while linking user-selectable keys to `docs/config.md`.
|
|
|
|
### Pass 2 Completion
|
|
|
|
- Confirm that development routes, architecture governs, internal overview
|
|
inventories, and focused internal docs explain implementation.
|
|
- Confirm that developer documents link to configuration, operations, and
|
|
integration contracts rather than redefining them.
|
|
- Validate developer-facing links and relevant focused tests.
|
|
|
|
## Pass 3: Lifecycle And Final Deduplication
|
|
|
|
Finish the migration by reconciling historical and future documentation, then
|
|
perform a repository-wide ownership audit.
|
|
|
|
### ADR And Roadmap Lifecycle
|
|
|
|
- Audit roadmap files for implemented behavior or completed status summaries
|
|
that should be removed or replaced with links to current canonical docs.
|
|
- Ensure ADRs own architectural rationale and supersession history without
|
|
becoming current behavior references or implementation trackers.
|
|
- Ensure accepted but unimplemented ADR decisions link to roadmap-owned
|
|
implementation status where appropriate.
|
|
- Distinguish rejected architectural alternatives in ADRs from rejected product
|
|
ideas in roadmap files.
|
|
|
|
### Repository-Wide Audit
|
|
|
|
- Inventory repeated commands, flags, defaults, module keys, validator keys,
|
|
file names, paths, schemas, retry semantics, and runtime guarantees.
|
|
- Assign each repeated fact to the canonical owner defined by the policy.
|
|
- Replace non-owning copies with short summaries and links where navigation is
|
|
useful.
|
|
- Retain only minimal illustrative snippets in prose and link them to maintained
|
|
examples.
|
|
- Validate local links and remove references to deleted or relocated material.
|
|
|
|
### Pass 3 Completion
|
|
|
|
- Confirm that every contractual or volatile fact has one canonical owner.
|
|
- Confirm that roadmap files contain future work and implementation status, ADRs
|
|
contain decision rationale, and current docs contain implemented behavior.
|
|
- Run final link, example, and documentation consistency checks.
|