docs: add documentation layout audit and proposal - #2190
Open
cardoe wants to merge 1 commit into
Open
Conversation
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.
geetikabatra
reviewed
Aug 5, 2026
| - **evaluators** deciding whether UnderStack fits. | ||
|
|
||
| Short answer: the layout has drifted in specific, fixable ways, and two of the | ||
| three audiences have no front door at all. |
Contributor
Author
There was a problem hiding this comment.
Contributors. It was also suppose to be architectural or deep dive into areas. But Claude reworded me a bit. I'm going to fix that.
|
|
||
| ### Duplication that costs readers | ||
|
|
||
| - **Argo Workflows is explained three times**: `docs/component-argo-workflows.md`, |
|
|
||
| Each phase is a separate reviewable PR. | ||
|
|
||
| - **Phase 1 — nav rewrite plus the three front doors.** This is the phase that |
There was a problem hiding this comment.
I think, we should also review what parts are no longer valid and need to be removed from the documentation.
|
Apart from a comment or two, it looks good to me otherwise. |
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.