From d0ce8ec073dd33125494e83c9c1413e88f74ad81 Mon Sep 17 00:00:00 2001 From: Zayden369 Date: Tue, 22 Sep 2026 04:40:48 +0530 Subject: [PATCH 1/2] docs: add repository vision and calibration artifacts Signed-off-by: Zayden369 --- VISION.md | 46 ++++++++++ docs/vision/vision-evidence.md | 94 ++++++++++++++++++++ docs/vision/vision-hypotheticals.md | 133 ++++++++++++++++++++++++++++ 3 files changed, 273 insertions(+) create mode 100644 VISION.md create mode 100644 docs/vision/vision-evidence.md create mode 100644 docs/vision/vision-hypotheticals.md diff --git a/VISION.md b/VISION.md new file mode 100644 index 00000000000..094de20a15f --- /dev/null +++ b/VISION.md @@ -0,0 +1,46 @@ +# Vision + +Layer5 Docs exists to give users and contributors a trustworthy path through Layer5 products and their public developer resources. +It publishes the documentation at `docs.layer5.io`, with first-party Cloud and Kanvas content in this repository and clear routes to canonical documentation for projects such as Meshery and Nighthawk. +It owns the public documentation contract for the content maintained here. Product implementations remain the authority for what the software actually does. + +## Shipped behavior is the source of truth + +Layer5 Docs documents behavior that can be verified in the relevant implementation or released product. +When summaries, runbooks, API descriptions, or older prose disagree with shipped behavior, documentation follows the implementation and flags the mismatch instead of repeating it. +For Layer5 Cloud, behavior claims are checked against the handlers and UI that produce the behavior, not only against secondary descriptions. +Private implementation repositories are evidence for maintainers, not public destinations for readers; public pages cite released versions or other reader-accessible references instead. +Release-note automation tracks released Cloud and Kanvas versions so version history remains tied to published artifacts. + +## Public links are compatibility contracts + +Published URLs and heading anchors are treated as interfaces because product UIs, external sites, bookmarks, and existing documentation can link to them. +When a page moves, its previous path is preserved with Hugo aliases rather than being allowed to become a 404. +When an externally referenced heading is renamed, its established anchor is retained explicitly. +Redirects and anchors are verified from built output so source changes are not considered safe merely because the Markdown looks correct. +Documentation restructuring should improve navigation without silently invalidating known entry points. + +## Information architecture serves distinct user journeys + +Layer5 Docs organizes content for readers with different goals and experience levels, including beginners, developers, administrators, operators, security specialists, and contributors. +The documentation separates task guidance, concepts, tutorials, and reference material so readers can move from learning a product to operating and extending it. +The site acts as a Layer5 documentation entry point while directing readers to canonical project documentation when that material is maintained elsewhere. +Content should favor clear task outcomes and product-specific terminology over generic prose that could belong to any documentation site. + +## Documentation changes are reproducible and reviewable + +Layer5 Docs is built with Hugo and Docsy, with the published content rooted in `content/en` and repository configuration defining the site. +Contributors can build and preview changes locally before review, and pull requests that affect documentation are built by the docs-preview workflow. +Documentation work follows the repository's issue-first contribution flow so planned changes remain visible and can be continued by other contributors. +Changes should preserve the repository's DCO, review, build, and contribution requirements rather than bypassing them for documentation-only work. + +## Scope + +Layer5 Docs is not the authority for product behavior when the relevant implementation says otherwise. +Layer5 Docs does not publish links to private implementation artifacts as reader-facing evidence. +Layer5 Docs does not knowingly break established public URLs or heading anchors when compatible redirects or explicit anchors can preserve them. +Layer5 Docs does not present planned or inferred behavior as shipped behavior without clearly identifying its status. +Layer5 Docs does not duplicate another project's canonical documentation merely to make this repository appear self-contained when a maintained canonical destination already exists. + +A change aligns when it makes product behavior more accurate, preserves public link compatibility, improves a real reader journey, or strengthens reproducible review and validation. +A change should be resisted when it relies on stale secondary descriptions over implementation evidence, exposes inaccessible references, breaks known URLs or anchors without compatibility handling, or adds generic documentation without a clear Layer5-specific purpose. diff --git a/docs/vision/vision-evidence.md b/docs/vision/vision-evidence.md new file mode 100644 index 00000000000..eb7dedfebf9 --- /dev/null +++ b/docs/vision/vision-evidence.md @@ -0,0 +1,94 @@ +# Layer5 Docs Vision Evidence Sheet + +This document provides claim-by-claim traceability for `VISION.md` to concrete evidence in `layer5io/docs` and, where product behavior is concerned, to the repository guidance that defines which downstream implementation is authoritative. + +--- + +## Identity and purpose + +* **Claim**: "Layer5 Docs exists to give users and contributors a trustworthy path through Layer5 products and their public developer resources." + * **Evidence**: `README.md` describes `docs.layer5.io` as documentation and developer resources for Layer5 products and explicitly welcomes contributions. +* **Claim**: "It publishes the documentation at `docs.layer5.io`, with first-party Cloud and Kanvas content in this repository and clear routes to canonical documentation for projects such as Meshery and Nighthawk." + * **Evidence**: `package.json` identifies the project as "Layer5 Product Documentation" with homepage `https://docs.layer5.io`; `content/en/_index.md` links to Cloud Docs and Kanvas Docs in this site, and links readers to `docs.meshery.io` and `getnighthawk.dev`. +* **Claim**: "It owns the public documentation contract for the content maintained here. Product implementations remain the authority for what the software actually does." + * **Evidence**: `AGENTS.md` states that Layer5 Cloud behavior must be verified against `meshery-cloud` implementation and that server behavior is the arbiter when documentation or API descriptions disagree. + +--- + +## Principle 1: Shipped behavior is the source of truth + +* **Claim**: "Layer5 Docs documents behavior that can be verified in the relevant implementation or released product." + * **Evidence**: `AGENTS.md`, "Documenting Layer5 Cloud behavior", requires product claims to be verified against `origin/master` in `meshery-cloud`. +* **Claim**: "When summaries, runbooks, API descriptions, or older prose disagree with shipped behavior, documentation follows the implementation and flags the mismatch instead of repeating it." + * **Evidence**: `AGENTS.md` says repository reference material is a starting point rather than the arbiter and gives `data/openapi.yml` as a concrete example where server behavior must win. +* **Claim**: "For Layer5 Cloud, behavior claims are checked against the handlers and UI that produce the behavior, not only against secondary descriptions." + * **Evidence**: `AGENTS.md` points contributors to `ui/components/identity/org-management/` for screen strings and `server/handlers/` for behavior. +* **Claim**: "Private implementation repositories are evidence for maintainers, not public destinations for readers; public pages cite released versions or other reader-accessible references instead." + * **Evidence**: `AGENTS.md` explicitly prohibits linking private `meshery-cloud` pull requests, issues, or files from public content and directs contributors to cite released versions instead. +* **Claim**: "Release-note automation tracks released Cloud and Kanvas versions so version history remains tied to published artifacts." + * **Evidence**: `.github/workflows/cloud-release-docs.yml` retrieves the latest `meshery-cloud` release and writes Cloud release notes. `.github/workflows/meshery-extension-release-docs.yml` does the same for Kanvas releases from `meshery-extensions-packages`. + +--- + +## Principle 2: Public links are compatibility contracts + +* **Claim**: "Published URLs and heading anchors are treated as interfaces because product UIs, external sites, bookmarks, and existing documentation can link to them." + * **Evidence**: `AGENTS.md`, "Keeping old URLs alive", records both external URL dependencies and a concrete Layer5 Cloud UI dependency on a heading anchor at `docs.layer5.io`. +* **Claim**: "When a page moves, its previous path is preserved with Hugo aliases rather than being allowed to become a 404." + * **Evidence**: `AGENTS.md` requires dead paths to be added to `aliases:`; working examples include `content/en/kanvas/operator/_index.md` and `content/en/kanvas/operator/views/index.md`. Alias usage is also present throughout the Kanvas and Cloud sections. +* **Claim**: "When an externally referenced heading is renamed, its established anchor is retained explicitly." + * **Evidence**: `AGENTS.md` directs contributors to preserve old anchors with Goldmark heading attributes. `hugo.toml` enables Goldmark parser attributes. +* **Claim**: "Redirects and anchors are verified from built output so source changes are not considered safe merely because the Markdown looks correct." + * **Evidence**: `AGENTS.md` instructs contributors to verify generated redirect stubs and compare built heading IDs between master and a change branch. +* **Claim**: "Documentation restructuring should improve navigation without silently invalidating known entry points." + * **Evidence**: The alias and preserved-anchor requirements in `AGENTS.md` establish backward-compatible navigation as a repository maintenance rule. + +--- + +## Principle 3: Information architecture serves distinct user journeys + +* **Claim**: "Layer5 Docs organizes content for readers with different goals and experience levels, including beginners, developers, administrators, operators, security specialists, and contributors." + * **Evidence**: `README.md`, "Documentation Structure", explicitly lists these personas and states a goal of comprehensive, organized, and accessible documentation for audiences from new users to expert contributors. +* **Claim**: "The documentation separates task guidance, concepts, tutorials, and reference material so readers can move from learning a product to operating and extending it." + * **Evidence**: `README.md` documents the Cloud and Kanvas information architecture with Getting Started, Concepts, Tutorials or Core Tasks, and Reference sections. +* **Claim**: "The site acts as a Layer5 documentation entry point while directing readers to canonical project documentation when that material is maintained elsewhere." + * **Evidence**: `content/en/_index.md` presents Cloud Docs and Kanvas Docs locally while linking Meshery Docs to `docs.meshery.io` and Nighthawk Docs to `getnighthawk.dev`. +* **Claim**: "Content should favor clear task outcomes and product-specific terminology over generic prose that could belong to any documentation site." + * **Evidence**: `README.md` defines product-specific information architectures and task categories for Layer5 Cloud and Kanvas; issue #1272 also sets the quality bar that repository vision content must not be generic. + +--- + +## Principle 4: Documentation changes are reproducible and reviewable + +* **Claim**: "Layer5 Docs is built with Hugo and Docsy, with the published content rooted in `content/en` and repository configuration defining the site." + * **Evidence**: `CONTRIBUTING.md` states that Layer5 documentation is built with Hugo and the Docsy theme. `hugo.toml` sets `contentDir = "content/en"` and imports Docsy. +* **Claim**: "Contributors can build and preview changes locally before review, and pull requests that affect documentation are built by the docs-preview workflow." + * **Evidence**: `README.md` and `CONTRIBUTING.md` document local setup and site commands. `package.json` defines build and preview scripts. `.github/workflows/build-docs-preview.yml` builds PR previews for documentation-related changes. +* **Claim**: "Documentation work follows the repository's issue-first contribution flow so planned changes remain visible and can be continued by other contributors." + * **Evidence**: `CONTRIBUTING.md` says all pull requests should reference an open issue and tells contributors to create a new issue when needed. +* **Claim**: "Changes should preserve the repository's DCO, review, build, and contribution requirements rather than bypassing them for documentation-only work." + * **Evidence**: `CONTRIBUTING.md` requires DCO sign-off for each commit, documents local tests and preview steps, and describes the fork-and-pull-request review flow. + +--- + +## Scope and non-goals + +* **Claim**: "Layer5 Docs is not the authority for product behavior when the relevant implementation says otherwise." + * **Evidence**: `AGENTS.md` identifies implementation handlers as the arbiter for behavior. +* **Claim**: "Layer5 Docs does not publish links to private implementation artifacts as reader-facing evidence." + * **Evidence**: `AGENTS.md` explicitly prohibits public content from linking private `meshery-cloud` pull requests, issues, or files. +* **Claim**: "Layer5 Docs does not knowingly break established public URLs or heading anchors when compatible redirects or explicit anchors can preserve them." + * **Evidence**: `AGENTS.md` requires aliases for moved pages and preserved IDs for externally referenced headings. +* **Claim**: "Layer5 Docs does not present planned or inferred behavior as shipped behavior without clearly identifying its status." + * **Evidence**: `AGENTS.md` requires a concrete producer in Go or TSX before documenting a capability as shipped and warns that a contract enum or runbook sentence alone is not proof. +* **Claim**: "Layer5 Docs does not duplicate another project's canonical documentation merely to make this repository appear self-contained when a maintained canonical destination already exists." + * **Evidence**: `content/en/_index.md` deliberately routes Meshery and Nighthawk readers to their separate canonical documentation sites rather than mirroring those docs here. + +--- + +## Alignment and resistance criteria + +* **Claim**: "A change aligns when it makes product behavior more accurate, preserves public link compatibility, improves a real reader journey, or strengthens reproducible review and validation." + * **Evidence**: This summarizes the documented maintenance rules in `AGENTS.md`, information architecture goals in `README.md`, and contribution and validation flow in `CONTRIBUTING.md` and `.github/workflows/build-docs-preview.yml`. +* **Claim**: "A change should be resisted when it relies on stale secondary descriptions over implementation evidence, exposes inaccessible references, breaks known URLs or anchors without compatibility handling, or adds generic documentation without a clear Layer5-specific purpose." + * **Evidence**: `AGENTS.md` covers source authority, private links, URL and anchor preservation; issue #1272 establishes the repository-specific quality bar. diff --git a/docs/vision/vision-hypotheticals.md b/docs/vision/vision-hypotheticals.md new file mode 100644 index 00000000000..81b9d03dd75 --- /dev/null +++ b/docs/vision/vision-hypotheticals.md @@ -0,0 +1,133 @@ +# Layer5 Docs Vision Hypotheticals and Calibration Record + +This document records ten stress-test scenarios used to calibrate `VISION.md`. Each scenario tests whether the vision gives a clear answer when accuracy, compatibility, information architecture, or contribution process is under pressure. + +--- + +## Hypothetical 1: Document a behavior from a stale runbook + +* **Proposal**: Add a Cloud guide based on an internal runbook even though the current server handler behaves differently. +* **Tested Principle**: Shipped behavior is the source of truth. +* **For**: The runbook is easier to read and already describes the intended workflow. +* **Against**: Readers would receive instructions that do not match the product they are using. +* **Verdict**: **RESIST** +* **Reasoning**: + > "If the handler and the runbook disagree, the guide must follow the shipped handler behavior and record the mismatch rather than publish the easier secondary description." +* **Changelog Impact**: The vision explicitly makes implementation behavior authoritative over summaries, runbooks, and stale reference material. + +--- + +## Hypothetical 2: Link a private implementation pull request from a public guide + +* **Proposal**: Cite a private `meshery-cloud` pull request as proof of a Cloud capability because it contains the clearest implementation discussion. +* **Tested Principle**: Shipped behavior is the source of truth and Scope. +* **For**: Maintainers can verify the implementation quickly from the pull request. +* **Against**: Most readers cannot open the private link, so the public documentation would contain unusable evidence. +* **Verdict**: **RESIST** +* **Reasoning**: + > "Private implementation evidence can inform the maintainer, but the published page must point readers to evidence they can access, such as a released version or public documentation." +* **Changelog Impact**: The vision separates maintainer evidence from reader-facing references. + +--- + +## Hypothetical 3: Rename a heading that a product UI links to + +* **Proposal**: Improve a heading title and allow Hugo to generate a new anchor, even though Layer5 Cloud currently links directly to the old anchor. +* **Tested Principle**: Public links are compatibility contracts. +* **For**: The new generated anchor is cleaner and matches the revised wording. +* **Against**: Existing product links would land on the page without reaching the intended section. +* **Verdict**: **RESIST** +* **Reasoning**: + > "The wording may change, but a known external anchor is part of the public documentation interface. Preserve the old ID explicitly." +* **Changelog Impact**: The vision names heading anchors alongside page URLs as compatibility surfaces. + +--- + +## Hypothetical 4: Move a page and preserve its old URL + +* **Proposal**: Reorganize a Kanvas page into a clearer section and keep the previous path in Hugo `aliases:`. +* **Tested Principle**: Public links are compatibility contracts. +* **For**: Readers get a better information architecture without losing bookmarks or inbound links. +* **Against**: The repository carries an additional redirect entry. +* **Verdict**: **ACCEPT** +* **Reasoning**: + > "A better location is worthwhile when the old route continues to resolve. The alias is the compatibility cost of improving the structure safely." +* **Changelog Impact**: The vision requires compatible redirects when pages move. + +--- + +## Hypothetical 5: Publish documentation for an inferred future capability + +* **Proposal**: Document a feature as available because an enum, schema field, or planning document suggests that support is coming soon. +* **Tested Principle**: Shipped behavior is the source of truth and Scope. +* **For**: The documentation could be ready before launch and reduce release-day work. +* **Against**: A declaration or schema entry does not prove the user-facing behavior ships. +* **Verdict**: **RESIST** +* **Reasoning**: + > "A future or inferred capability must not be written as current product behavior. Verify a producer in the implementation or clearly label the material as non-shipped direction." +* **Changelog Impact**: The scope now rejects presenting planned or inferred behavior as shipped. + +--- + +## Hypothetical 6: Use released versions to support public behavior claims + +* **Proposal**: Verify a Cloud behavior against implementation, then cite the released version that contains it rather than a private source link. +* **Tested Principle**: Shipped behavior is the source of truth. +* **For**: Maintainers retain implementation confidence while readers get a reference they can actually use. +* **Against**: Release references can be less granular than a pull request. +* **Verdict**: **ACCEPT** +* **Reasoning**: + > "Verification and citation serve different audiences. Use implementation to establish truth, then use an accessible released artifact for the public reference." +* **Changelog Impact**: The vision explicitly distinguishes private maintainer evidence from public destinations. + +--- + +## Hypothetical 7: Copy another project's canonical docs into this repository + +* **Proposal**: Copy a substantial Meshery guide into `layer5io/docs` so every Layer5 product appears to have complete documentation in one repository. +* **Tested Principle**: Information architecture serves distinct user journeys and Scope. +* **For**: Readers could remain on one domain and search one repository. +* **Against**: Duplicate documentation can drift while Meshery already maintains its own canonical documentation destination. +* **Verdict**: **RESIST** +* **Reasoning**: + > "The Layer5 docs site should be a reliable entry point, not a reason to fork canonical documentation. Route readers to the maintained project source when ownership lives elsewhere." +* **Changelog Impact**: The vision defines the site as an entry point that can direct readers to canonical external project docs. + +--- + +## Hypothetical 8: Reorganize content around a real reader journey + +* **Proposal**: Split a long page into concept, task, and reference content for operators while preserving old URLs and anchors. +* **Tested Principle**: Information architecture serves distinct user journeys and Public links are compatibility contracts. +* **For**: Operators can find task instructions faster while deeper explanation and reference material remain available. +* **Against**: The change touches several pages and requires compatibility checks. +* **Verdict**: **ACCEPT** +* **Reasoning**: + > "Information architecture should follow reader goals. A larger edit is justified when it improves the journey and preserves the public routes readers already depend on." +* **Changelog Impact**: The vision ties structural improvement to user journeys and compatibility verification. + +--- + +## Hypothetical 9: Open a documentation pull request without an issue + +* **Proposal**: Skip the GitHub issue because the change only adds documentation and can be reviewed directly in the pull request. +* **Tested Principle**: Documentation changes are reproducible and reviewable. +* **For**: The contributor can move from idea to patch faster. +* **Against**: The repository explicitly requires pull requests to reference open issues, and untracked work is harder for other contributors to discover or continue. +* **Verdict**: **RESIST** +* **Reasoning**: + > "Documentation work follows the same visible contribution flow as other repository changes. Open the issue first so intent, scope, and ownership are discoverable." +* **Changelog Impact**: The vision includes the issue-first workflow as part of reviewability. + +--- + +## Hypothetical 10: Validate a documentation-only change through the normal build path + +* **Proposal**: For a Markdown-only change, run the repository build or preview path and let the PR preview workflow validate the rendered result instead of treating source review as sufficient. +* **Tested Principle**: Documentation changes are reproducible and reviewable. +* **For**: Rendering catches problems that plain Markdown review can miss, including broken raw HTML, anchors, and Hugo behavior. +* **Against**: Validation takes more time than reviewing the source diff alone. +* **Verdict**: **ACCEPT** +* **Reasoning**: + > "Rendered documentation is the product. A documentation-only change still needs the repository's build and preview path because source text alone cannot prove the published result." +* **Changelog Impact**: The vision treats reproducible builds and pull-request previews as part of documentation correctness. From 6862de1ac32cdee61ec6e20e49eec7964008509a Mon Sep 17 00:00:00 2001 From: Zayden369 Date: Tue, 22 Sep 2026 04:46:00 +0530 Subject: [PATCH 2/2] docs: tighten vision traceability claims Signed-off-by: Zayden369 --- VISION.md | 4 ++-- docs/vision/vision-evidence.md | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/VISION.md b/VISION.md index 094de20a15f..c9bd8fe6d07 100644 --- a/VISION.md +++ b/VISION.md @@ -2,12 +2,12 @@ Layer5 Docs exists to give users and contributors a trustworthy path through Layer5 products and their public developer resources. It publishes the documentation at `docs.layer5.io`, with first-party Cloud and Kanvas content in this repository and clear routes to canonical documentation for projects such as Meshery and Nighthawk. -It owns the public documentation contract for the content maintained here. Product implementations remain the authority for what the software actually does. +It owns the public documentation contract for the content maintained here. For Layer5 Cloud content, the implementation remains the authority for what the software actually does. ## Shipped behavior is the source of truth Layer5 Docs documents behavior that can be verified in the relevant implementation or released product. -When summaries, runbooks, API descriptions, or older prose disagree with shipped behavior, documentation follows the implementation and flags the mismatch instead of repeating it. +When repository reference material disagrees with shipped behavior, documentation follows the implementation and flags the mismatch instead of repeating it. For Layer5 Cloud, behavior claims are checked against the handlers and UI that produce the behavior, not only against secondary descriptions. Private implementation repositories are evidence for maintainers, not public destinations for readers; public pages cite released versions or other reader-accessible references instead. Release-note automation tracks released Cloud and Kanvas versions so version history remains tied to published artifacts. diff --git a/docs/vision/vision-evidence.md b/docs/vision/vision-evidence.md index eb7dedfebf9..a3e361406c9 100644 --- a/docs/vision/vision-evidence.md +++ b/docs/vision/vision-evidence.md @@ -10,7 +10,7 @@ This document provides claim-by-claim traceability for `VISION.md` to concrete e * **Evidence**: `README.md` describes `docs.layer5.io` as documentation and developer resources for Layer5 products and explicitly welcomes contributions. * **Claim**: "It publishes the documentation at `docs.layer5.io`, with first-party Cloud and Kanvas content in this repository and clear routes to canonical documentation for projects such as Meshery and Nighthawk." * **Evidence**: `package.json` identifies the project as "Layer5 Product Documentation" with homepage `https://docs.layer5.io`; `content/en/_index.md` links to Cloud Docs and Kanvas Docs in this site, and links readers to `docs.meshery.io` and `getnighthawk.dev`. -* **Claim**: "It owns the public documentation contract for the content maintained here. Product implementations remain the authority for what the software actually does." +* **Claim**: "It owns the public documentation contract for the content maintained here. For Layer5 Cloud content, the implementation remains the authority for what the software actually does." * **Evidence**: `AGENTS.md` states that Layer5 Cloud behavior must be verified against `meshery-cloud` implementation and that server behavior is the arbiter when documentation or API descriptions disagree. --- @@ -19,8 +19,8 @@ This document provides claim-by-claim traceability for `VISION.md` to concrete e * **Claim**: "Layer5 Docs documents behavior that can be verified in the relevant implementation or released product." * **Evidence**: `AGENTS.md`, "Documenting Layer5 Cloud behavior", requires product claims to be verified against `origin/master` in `meshery-cloud`. -* **Claim**: "When summaries, runbooks, API descriptions, or older prose disagree with shipped behavior, documentation follows the implementation and flags the mismatch instead of repeating it." - * **Evidence**: `AGENTS.md` says repository reference material is a starting point rather than the arbiter and gives `data/openapi.yml` as a concrete example where server behavior must win. +* **Claim**: "When repository reference material disagrees with shipped behavior, documentation follows the implementation and flags the mismatch instead of repeating it." + * **Evidence**: `AGENTS.md` says repository reference material is a starting point rather than the arbiter and requires contributors to document handler responses and flag the `data/openapi.yml` mismatch. * **Claim**: "For Layer5 Cloud, behavior claims are checked against the handlers and UI that produce the behavior, not only against secondary descriptions." * **Evidence**: `AGENTS.md` points contributors to `ui/components/identity/org-management/` for screen strings and `server/handlers/` for behavior. * **Claim**: "Private implementation repositories are evidence for maintainers, not public destinations for readers; public pages cite released versions or other reader-accessible references instead."