Versioned documentation site
- Dominant language
- Rust
- Stars
- 32
- Forks
- 5
- Avg merge
- 15h 21m
- Merged PRs (30d)
- 21
Description
## Motivation
`docs/` now holds 20+ guides, 30+ ADRs, and a 25 KB README. The content is excellent; the navigation is a directory listing. With 0.7 adding surfaces (stability policy, SQL producer contract, operations handbook, upgrade guides per release), a versioned site becomes the difference between documentation that exists and documentation that gets used.
## Scope
- Static docs site (mdBook or equivalent — prefer minimal toolchain) built from `docs/` in CI, published per release tag with a version switcher (at minimum: latest stable + main).
- Information architecture:
- **Learn** — concepts, Rust/Python quickstarts
- **Operate** — deployment, managed Postgres, upgrade guides, troubleshooting, `awa doctor`, pooler matrix
- **Reference** — configuration, HTTP API (via #143 types), SQL producer contract, metrics catalog, stability policy, CLI
- **Internals** — architecture, ADRs, TLA+ models, benchmarking
- README slims to overview + quickstart + links into the site.
- Link-check in CI so cross-references stay valid.
## Acceptance
- Site builds and publishes automatically on tag; main branch preview available.
- All existing docs reachable through the IA; no orphaned pages; link-check green.
- README reduced without losing the delivery-contract and positioning content (moved, not deleted).
## References
Roadmap: `docs/0.7-roadmap.md` (WS-6, NEW-13). Related: stability policy issue, operations handbook issue, #342, #143.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start by reading docs/0.7-roadmap.md and inventorying docs/ plus the README against the proposed Learn, Operate, Reference, and Internals structure. Check the existing CI setup before choosing a minimal static-site toolchain. Done means the site builds and publishes on release tags, previews main, exposes every document without orphaned links, and leaves the README with the required content.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- postgresql, python, rust
- Domain
- build-system, ci-cd, documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100