From 23ed7164507896557b25e263dca274c992728011 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sat, 23 May 2026 07:38:17 -0500 Subject: [PATCH] Added a documentation update roadmap --- docs/roadmap/documentation.md | 237 ++++++++++++++++++++++++++++++++++ 1 file changed, 237 insertions(+) create mode 100644 docs/roadmap/documentation.md diff --git a/docs/roadmap/documentation.md b/docs/roadmap/documentation.md new file mode 100644 index 0000000..e8a4f25 --- /dev/null +++ b/docs/roadmap/documentation.md @@ -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.