[Docs] Give the alpha one findable page saying what it is not yet #610

New issue

Closed

opened 2026-07-22 16:19:54 +00:00 by brenno · 1 comment

brenno commented

2026-07-22 16:19:54 +00:00

Owner

Found in the pre-publication product review.

Evidence: docs/FAQ.md:277-283 is the only roadmap, and it is stale: it lists "Additional chart visualizations and data types" as planned while README.md already enumerates thirteen chart types, and "Improved performance for large presentations" without saying what currently goes wrong. There is no ROADMAP.md and no KNOWN_ISSUES.md.

The honesty that does exist is scattered across five files: the translation gaps in the README feature line, export accessibility in docs/ACCESSIBILITY.md, web limitations in docs/HOSTING.md §5, "nothing to download yet" in docs/FAQ.md:36.

Why this matters now: expectation management that a reader has to assemble from five files does not work. A critic finds the gaps first and presents them as a discovery rather than as your openness. For a 0.1.0 alpha, "what is broken" is a feature, not an embarrassment — this project is unusually good at that kind of candour and gets no credit for it because the candour is not in one place.

Proposal: one KNOWN_LIMITATIONS.md of at most one screen that gathers the five existing admissions with a pointer to each source, plus a line at the top of the README. Replace the stale roadmap section in docs/FAQ.md with a link to it — a roadmap you do not maintain is worse than none.

Found in the pre-publication product review. **Evidence:** `docs/FAQ.md:277-283` is the only roadmap, and it is stale: it lists "Additional chart visualizations and data types" as planned while `README.md` already enumerates thirteen chart types, and "Improved performance for large presentations" without saying what currently goes wrong. There is no `ROADMAP.md` and no `KNOWN_ISSUES.md`. The honesty that does exist is scattered across five files: the translation gaps in the README feature line, export accessibility in `docs/ACCESSIBILITY.md`, web limitations in `docs/HOSTING.md` §5, "nothing to download yet" in `docs/FAQ.md:36`. **Why this matters now:** expectation management that a reader has to assemble from five files does not work. A critic finds the gaps first and presents them as a discovery rather than as your openness. For a 0.1.0 alpha, "what is broken" is a *feature*, not an embarrassment — this project is unusually good at that kind of candour and gets no credit for it because the candour is not in one place. **Proposal:** one `KNOWN_LIMITATIONS.md` of at most one screen that gathers the five existing admissions with a pointer to each source, plus a line at the top of the README. Replace the stale roadmap section in `docs/FAQ.md` with a link to it — a roadmap you do not maintain is worse than none.

brenno added the

docs

label

2026-07-22 16:19:54 +00:00

brenno referenced this issue from a commit

2026-07-22 17:07:09 +00:00

docs: geef de alfa één vindbare pagina met wat er nog niet is (#610)

brenno referenced this issue from a commit

2026-07-22 17:12:52 +00:00

docs: geef de alfa één vindbare pagina met wat er nog niet is (#610)

brenno referenced this issue

2026-07-22 17:14:10 +00:00