98 lines
4.2 KiB
Markdown
98 lines
4.2 KiB
Markdown
# 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:
|
|
|
|
```sh
|
|
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/**'
|
|
rg -n -i "Stage|Phase" README.md docs --glob '!docs/roadmap/**'
|
|
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.
|