hardbyte / hardbyte/awa

Versioned documentation site

Open
#377 0 comments 0 reactions 0 assignees View on GitHub
docs
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.