docs: add documentation layout audit and proposal - #2190
Merged
Conversation
geetikabatra
reviewed
Aug 5, 2026
|
Apart from a comment or two, it looks good to me otherwise. |
Records the current docs layout, its problems, and a phased proposal to restructure it around the project's three audiences: operators, contributors and evaluators. The headline finding is that contributors and evaluators have no front door: there is no contributor section and no CONTRIBUTING.md, so developer docs live in 58 unlinked markdown files outside docs/, and Overview is a grab-bag rather than an evaluator's on-ramp. The proposal is phased so the nav rewrite that adds the front doors needs no file moves, with moves deferred and governed by one rule: move a file only when its audience changes. This is a planning artifact, to be deleted once the phases land or are rejected. It lives at the repository root because every file under docs/ is published.
cardoe
force-pushed
the
docs-layout-audit
branch
from
August 10, 2026 20:05
e596389 to
fa54fc5
Compare
Contributor
Author
|
Ah merge when ready used Milan's review. |
cardoe
added a commit
that referenced
this pull request
Sep 4, 2026
The audit landed in #2190, just before the release-notes work in #2191. Re-check every claim against main: counts move to 137 pages, 8 nav entries, 61 external markdown files and v0.4.28. Add three mechanics the reorg must respect -- the generated-but-navigated unreleased.md, include_dir_to_nav's global sort toggle, and the published release-body URLs that pin docs/release-notes/ permanently. Grow the proposal a seventh tab. Also fix the audit's own errors: the rename impact lists, Phase 3's link count, and a component table row that was never there.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Records the current docs layout, its problems, and a phased proposal to
restructure it around the project's three audiences: operators, contributors
and evaluators.
The headline finding is that contributors and evaluators have no front door:
there is no contributor section and no CONTRIBUTING.md, so developer docs live
in 58 unlinked markdown files outside docs/, and Overview is a grab-bag rather
than an evaluator's on-ramp. The proposal is phased so the nav rewrite that adds
the front doors needs no file moves, with moves deferred and governed by one
rule: move a file only when its audience changes.
This is a planning artifact, to be deleted once the phases land or are rejected.
It lives at the repository root because every file under docs/ is published.