docs: journey-first documentation refactor - #490
Merged
Merged
Conversation
Reorganize the docs site into start/, guides/, reference/, and internals/ groups with a top-level security page. Each concept is single-sourced on one page and cross-linked, every page leads with the common path and carries a prerequisite and next-step block, and every field's emission status (emitted, validated-only, or reserved) is stated accurately. Retire the flat page set (workflows, simulate, configuration, cli-reference, and the rest) and rewrite the sidebar to mirror the reader journey. Signed-off-by: Joshua Temple <joshua.temple@stablekernel.com>
The README now orients and links: pitch, a one-screen how-it-works, a fit self-check, a minimal quickstart, the accurate generated-file set, a capabilities snapshot, and a links block into the site groups. The full CLI table, the duplicate walkthrough, and the stale roadmap prose move out; deep topics link to their single-source page. Fix the quickstart step order (callbacks before generate), the generated-file list, the runs_on capability claim, and the version pin. Signed-off-by: Joshua Temple <joshua.temple@stablekernel.com>
Add a documentation-quality rule to CONTRIBUTING: pages are typed to one Diataxis mode, depth is layered common-path-first, each concept is single-sourced, every field's emission status is stated accurately, and every page carries a prerequisite and next-step link. Update the SECURITY.md links to the relocated versioning and security pages. Signed-off-by: Joshua Temple <joshua.temple@stablekernel.com>
Contributor
|
All PR Validation checks passed. |
Signed-off-by: Joshua Temple <joshua.temple@stablekernel.com>
Signed-off-by: Joshua Temple <joshua.temple@stablekernel.com>
Signed-off-by: Joshua Temple <joshua.temple@stablekernel.com>
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
1 participant
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.
Problem
The docs had grown fragmented and had drifted from the code: install steps
duplicated across three pages, workflow flow narrated in three places, phantom
CLI flags and env vars, dead
@masterrefs and stale version pins, and a setof manifest fields that were never documented or documented with the wrong
emission status.
What this does
Restructures the site into a journey-first, Diataxis-typed information
architecture:
start/(why, how-it-works, getting-started),guides/(operator how-tos: adopt, environments, promote, hotfix, rollback, simulate,
multi-repo, visualize),
reference/(manifest, callbacks, CLI,generated-workflows, versioning), a top-level
securitypage, andinternals/. Each concept is single-sourced on one page and cross-linked,every page leads with the common path and carries a prerequisite and next-step
block, and every manifest field states its true emission status. The README
shrinks to orientation and points into the site.
Verification
npm run buildexits 0, 23 pages built.pages.
every field's emission status were checked against the code, not the old
docs. Where the two disagreed, the code won (for example the generated
orchestrate and promote filenames carry no
cascade-prefix).