Added a documentation update roadmap
This commit is contained in:
237
docs/roadmap/documentation.md
Normal file
237
docs/roadmap/documentation.md
Normal file
@@ -0,0 +1,237 @@
|
||||
# Roadmap: 1.0 Documentation Pass
|
||||
|
||||
Status: Planned
|
||||
|
||||
## Goal
|
||||
|
||||
Prepare Narratio documentation for a 1.0 release by reviewing and rewriting
|
||||
every non-policy document under `docs/` against the implemented codebase.
|
||||
|
||||
The finished documentation set should be accurate, concise, complete for its
|
||||
audience, and compliant with:
|
||||
|
||||
- `docs/policy/documentation.md`
|
||||
- `docs/policy/architecture.md`
|
||||
- `docs/policy/development.md`
|
||||
|
||||
Do not modify files under `docs/policy/` during this pass.
|
||||
|
||||
Current behavior belongs in canonical docs. Future, planned, aspirational, or
|
||||
unimplemented behavior belongs only under `docs/roadmap/`.
|
||||
|
||||
## Scope
|
||||
|
||||
In scope:
|
||||
|
||||
- `docs/*.md`
|
||||
- `docs/internal/*.md`
|
||||
- `docs/integrations/*.md`
|
||||
- `docs/roadmap/*.md`
|
||||
- documentation references to files under `examples/`
|
||||
- test expectation fixes when the documentation review exposes stale or
|
||||
incorrect doc/example/path expectations
|
||||
|
||||
Out of scope:
|
||||
|
||||
- product/runtime code changes
|
||||
- feature implementation
|
||||
- edits under `docs/policy/`
|
||||
- adding roadmap behavior to current-behavior docs before that behavior is
|
||||
implemented
|
||||
|
||||
## Implementation Stages
|
||||
|
||||
### Stage 1: Inventory and Source-of-Truth Audit
|
||||
|
||||
Status: Planned
|
||||
|
||||
Create a file-by-file inventory of all non-policy docs before rewriting.
|
||||
|
||||
Implementation requirements:
|
||||
|
||||
- List every non-policy documentation file and assign its intended audience.
|
||||
- Identify each document's canonical scope using `docs/policy/documentation.md`.
|
||||
- Compare docs against the current code and tests, especially:
|
||||
- `internal/app`
|
||||
- `internal/config`
|
||||
- `internal/stage`
|
||||
- `internal/artifacts`
|
||||
- `examples`
|
||||
- relevant tests under `internal/**`
|
||||
- Record stale terminology, broken links, stale example paths, duplicate
|
||||
content, and roadmap-only behavior that leaked into current-behavior docs.
|
||||
- Record stale test expectations related to docs, examples, paths, or command
|
||||
text.
|
||||
- Do not rewrite content in this stage except obvious broken links or test
|
||||
corrections needed to make documentation validation meaningful.
|
||||
|
||||
Acceptance criteria:
|
||||
|
||||
- The rewrite has a concrete file inventory and source-of-truth map.
|
||||
- The team knows which docs are canonical and which should link elsewhere.
|
||||
- Known stale terms and broken references are identified before broad edits.
|
||||
|
||||
### Stage 2: User and Operator Docs
|
||||
|
||||
Status: Planned
|
||||
|
||||
Rewrite the user-facing and operator-facing docs first.
|
||||
|
||||
Implementation requirements:
|
||||
|
||||
- Rewrite these docs as fresh, concise current-behavior references:
|
||||
- `README.md`, if present
|
||||
- `docs/cli.md`
|
||||
- `docs/config.md`
|
||||
- `docs/operations.md`
|
||||
- `docs/troubleshooting.md`
|
||||
- Verify every command, flag, config field, discovery rule, path, and workflow
|
||||
against implemented behavior.
|
||||
- Cover implemented 1.0 behavior, including:
|
||||
- campaign registry selection;
|
||||
- concrete session loading and template-driven `session init`;
|
||||
- session-oriented helper commands;
|
||||
- clean, restore, analyze, and publish workflows;
|
||||
- artifact selection behavior;
|
||||
- locks and published output behavior;
|
||||
- workspace, spool, and cache behavior;
|
||||
- secrets loading and S3-backed operation.
|
||||
- Keep examples short and link to maintained files under `examples/` instead
|
||||
of duplicating large config blocks.
|
||||
- Fix tests only when they assert stale doc paths, example paths, command
|
||||
names, or current-behavior text.
|
||||
|
||||
Acceptance criteria:
|
||||
|
||||
- User/operator docs are task-oriented and match actual CLI/config behavior.
|
||||
- Current-behavior docs do not depend on roadmaps for normal usage.
|
||||
- No current-behavior doc describes unimplemented roadmap items.
|
||||
|
||||
### Stage 3: Internal Developer Docs
|
||||
|
||||
Status: Planned
|
||||
|
||||
Rewrite implemented internal component docs after public docs stabilize.
|
||||
|
||||
Implementation requirements:
|
||||
|
||||
- Rewrite:
|
||||
- `docs/internal/README.md`
|
||||
- `docs/internal/adapters.md`
|
||||
- `docs/internal/artifacts.md`
|
||||
- `docs/internal/command-restore.md`
|
||||
- `docs/internal/manifest.md`
|
||||
- `docs/internal/stage-*.md`
|
||||
- `docs/internal/storage.md`
|
||||
- `docs/internal/workspace.md`
|
||||
- Verify stage docs against current stage names, stage ordering, manifest
|
||||
records, declared inputs/outputs, adapters, path helpers, storage behavior,
|
||||
publish/current-state behavior, restore behavior, cache behavior, and
|
||||
workspace cleanup.
|
||||
- Keep implementation details in `docs/internal/`, not in user-facing docs.
|
||||
- Avoid turning internal docs into duplicate config or CLI references; link to
|
||||
canonical docs when needed.
|
||||
|
||||
Acceptance criteria:
|
||||
|
||||
- Internal docs are accurate enough for developers and LLM coding agents to
|
||||
change the system safely.
|
||||
- Stage and adapter boundaries match `docs/policy/architecture.md`.
|
||||
- Manifest, path, storage, and publish invariants are explicit and current.
|
||||
|
||||
### Stage 4: Integrations and Examples
|
||||
|
||||
Status: Planned
|
||||
|
||||
Review integration docs and maintained examples after core docs are rewritten.
|
||||
|
||||
Implementation requirements:
|
||||
|
||||
- Rewrite:
|
||||
- `docs/integrations/README.md`
|
||||
- `docs/integrations/audita.md`
|
||||
- `docs/integrations/scriptorium.md`
|
||||
- `docs/integrations/seriatim.md`
|
||||
- Verify integration docs against current adapter contracts and expected
|
||||
downstream tool behavior.
|
||||
- Confirm every referenced example file exists.
|
||||
- Confirm examples match current schema and command usage.
|
||||
- Run or rely on example validation tests.
|
||||
- Fix tests when they reference moved, renamed, or intentionally retired
|
||||
examples.
|
||||
|
||||
Acceptance criteria:
|
||||
|
||||
- Integration docs describe only implemented adapter expectations.
|
||||
- Maintained examples are valid, secret-free, and linked from canonical docs.
|
||||
- Example validation tests reflect the documented example set.
|
||||
|
||||
### Stage 5: Roadmap Cleanup and Final Sweep
|
||||
|
||||
Status: Planned
|
||||
|
||||
Clean up roadmap state and run final documentation validation.
|
||||
|
||||
Implementation requirements:
|
||||
|
||||
- Review `docs/roadmap/**` for implemented items that should be marked
|
||||
implemented, retired, or left planned.
|
||||
- Keep historical and planned behavior in roadmaps only.
|
||||
- Run final link/path/term sweeps.
|
||||
- Run validation commands:
|
||||
- `go test ./internal/config -run TestExamplesLoadAndValidate -v`
|
||||
- `go test ./internal/app -run TestExecute -v`
|
||||
- `go test ./...`
|
||||
|
||||
Acceptance criteria:
|
||||
|
||||
- All non-policy docs are current for the 1.0 release.
|
||||
- Roadmaps do not serve as required user/operator documentation.
|
||||
- Tests pass after allowed documentation-related test expectation fixes.
|
||||
|
||||
## Required Checks
|
||||
|
||||
Run searches for stale terminology and references during the pass.
|
||||
|
||||
Stale terminology:
|
||||
|
||||
- `archive`
|
||||
- `promote`
|
||||
- `promoted`
|
||||
- `promote_artifacts`
|
||||
- legacy campaign path/discovery language
|
||||
- old transcript names and paths
|
||||
- removed CLI commands or aliases
|
||||
|
||||
Broken or stale references:
|
||||
|
||||
- missing local doc links;
|
||||
- stale `examples/` paths;
|
||||
- stale internal doc filenames;
|
||||
- references to `docs/policy/**` as editable targets;
|
||||
- command examples that no longer match the CLI.
|
||||
|
||||
Policy checks:
|
||||
|
||||
- Current-behavior docs mention only implemented behavior.
|
||||
- Planned behavior appears only under `docs/roadmap/`.
|
||||
- Docs do not expose raw secrets or recommend storing secrets in config.
|
||||
- Docs use canonical homes:
|
||||
- `docs/config.md` for config schema;
|
||||
- `docs/cli.md` for command syntax;
|
||||
- `docs/operations.md` for operator workflows;
|
||||
- `docs/troubleshooting.md` for failure diagnosis;
|
||||
- `docs/internal/` for implementation contracts;
|
||||
- `docs/integrations/` for downstream tool integration notes;
|
||||
- `docs/roadmap/` for future work.
|
||||
|
||||
## Assumptions
|
||||
|
||||
- `docs/policy/**` is read-only for this documentation pass.
|
||||
- This pass is for 1.0 release readiness, not feature implementation.
|
||||
- Product and runtime code changes are out of scope.
|
||||
- Test fixes are in scope when they correct stale documentation, example, path,
|
||||
command, or current-behavior expectations uncovered during the review.
|
||||
- Roadmap files may remain as planning and historical records.
|
||||
- Current-behavior docs must be sufficient for normal use without requiring
|
||||
readers to consult roadmaps.
|
||||
Reference in New Issue
Block a user