distributor/docs/roadmap/documentation.md

Documentation Roadmap

Purpose

This roadmap tracks the remaining work required to verify that project documentation complies with docs/policy/documentation.md and accurately reflects the current implementation.

The documentation migration has rewritten the current user, operator, integration, and internal component docs. This file now records only remaining validation work. Current behavior belongs outside docs/roadmap/; deferred or unimplemented work belongs under docs/roadmap/.

Current Documentation Set

Current documentation outside roadmap:

• README.md: concise project orientation and quickstart.
• docs/cli.md: canonical CLI command, flag, workflow, and output reference.
• docs/config.md: canonical YAML configuration reference.
• docs/operations.md: operating, safety, state, upload, and recovery guidance.
• docs/troubleshooting.md: symptom-oriented diagnostic and safe-fix guide.
• docs/policy/architecture.md: architecture and invariant policy.
• docs/policy/development.md: contributor and coding workflow policy.
• docs/policy/documentation.md: controlling documentation policy.
• docs/integrations/*.md: implemented external/file-format/protocol contracts.
• docs/internal/*.md: implemented internal component contracts.
• examples/*.yml and examples/source-bundle/*: maintained example configs and source bundle fixture.

Current roadmap files:

• docs/roadmap/documentation.md: this remaining documentation validation plan.
• docs/roadmap/http.md: deferred HTTP upload extensions only.

Removed completed roadmap artifacts:

• docs/roadmap/audit.md
• docs/roadmap/cleanup.md
• docs/roadmap/implementation.md

Remaining Documentation Validation

Goal: verify the rewritten docs against tests, examples, code, links, and the documentation policy checklist.

Files to create, update, delete, or move: fixes only if validation finds gaps.

Repository areas to inspect:

• README.md
• docs/cli.md
• docs/config.md
• docs/operations.md
• docs/troubleshooting.md
• docs/internal/
• docs/integrations/
• docs/policy/
• examples/
• CLI parser code under internal/cli
• config loading/defaulting/validation under internal/config
• app/report/upload behavior under internal/app
• source bundle, state, publish, storage, adapter, and transform packages

Acceptance criteria:

• Tests pass for the full repository.
• Maintained example configs load.
• CLI examples and flags match parser behavior.
• Config fields and defaults match internal/config.
• Operations and troubleshooting docs describe implemented behavior only.
• Internal docs preserve package boundaries and policy-required sections.
• Integration docs describe only implemented contracts.
• Roadmap files contain only remaining or deferred work.
• Links resolve.
• No secrets or private data are present.

Suggested validation commands:

go test ./...
go test ./internal/config ./internal/cli ./internal/app
go test ./pkg/bundle ./internal/bundle ./internal/state ./internal/publish ./internal/storage ./internal/storage/fake
go test ./internal/adapters/local ./internal/adapters/ssh ./internal/adapters/s3 ./internal/ingest ./internal/transform/markdown
rg -n -i "future|planned|deferred|experimental|deprecated|not implemented|old behavior" README.md docs --glob '!docs/roadmap/**' --glob '!docs/policy/**'
rg -n "\\b(Stages?|Phases?)\\b" README.md docs --glob '!docs/roadmap/**' --glob '!docs/policy/**'
rg -n -- "--config|--dry-run|--force|--format|--pipeline|--bundle|--id|--file|--created|--overwrite" docs/cli.md internal/cli
rg -n "examples/" README.md docs examples internal/config/load_test.go

Manual review items:

• Confirm README remains concise and orientation-focused.
• Confirm docs/config.md is the only full config field/default reference.
• Confirm docs/cli.md is the only full command/flag reference.
• Confirm docs/operations.md focuses on operating and recovery.
• Confirm docs/troubleshooting.md remains symptom-first.
• Confirm docs/internal/ describes implemented component contracts and boundaries.
• Confirm integration docs do not claim support for unimplemented external features.
• Confirm examples contain no secrets and distinguish local runnable examples from environment-gated remote examples.

Open Questions

No open questions block the remaining validation work.