From 1c1e572f6b7f300d3082b73b083f175fd9f806ce Mon Sep 17 00:00:00 2001 From: quality <280983584+hivecommons-hive[bot]@users.noreply.github.com> Date: Tue, 17 Nov 2026 23:54:34 -0500 Subject: [PATCH 1/5] Add draft documentation analysis for Hive Commons (pilot) AI-drafted documentation assessment of Hive Commons (hivecommons.dev, docs.hivecommons.dev, and the hivecommons/docs, hivecommons/hive (src/docs/), and hivecommons/hivecommons.github.io repositories) against CNCF Sandbox criteria, as requested in cncf/techdocs#395. This is a pilot run of the cncf-techdocs-assessment AI-assisted workflow model. Includes analysis.md (ratings, comments, and recommendations across project documentation, contributor documentation, and website and infrastructure), implementation.md (a small set of high-level actions), and issues.md (a draft issues backlog for seeding a beginner-friendly documentation backlog). Adds project-specific terms to .cspell.yml. Refs #395 Signed-off-by: quality <280983584+hivecommons-hive[bot]@users.noreply.github.com> --- .cspell.yml | 19 + analyses/2026/hivecommons/analysis.md | 659 ++++++++++++++++++++ analyses/2026/hivecommons/implementation.md | 87 +++ analyses/2026/hivecommons/issues.md | 140 +++++ 4 files changed, 905 insertions(+) create mode 100644 analyses/2026/hivecommons/analysis.md create mode 100644 analyses/2026/hivecommons/implementation.md create mode 100644 analyses/2026/hivecommons/issues.md diff --git a/.cspell.yml b/.cspell.yml index 631cb32d..b59d5685 100644 --- a/.cspell.yml +++ b/.cspell.yml @@ -103,3 +103,22 @@ words: - yaspeller - kubevirt - viewports + - hivecommons + - clubanderson + - kellyaa + - dogfooding + - pluk + - rationguard + - promptargs + - Spektacular + - Diátaxis + - hivectl + - podman + - kubernetes + - ACMM + - pastable + - alex + - livestream + - youtube + - prebuild + - Fraunces diff --git a/analyses/2026/hivecommons/analysis.md b/analyses/2026/hivecommons/analysis.md new file mode 100644 index 00000000..c90bcf3d --- /dev/null +++ b/analyses/2026/hivecommons/analysis.md @@ -0,0 +1,659 @@ +--- +title: Hive Commons Documentation Analysis +created: 2026-11-17 +modified: 2026-11-17 +toc_max_heading_level: 4 +author: + AI-assisted draft (pilot), reviewed by a CNCF TechDocs technical writer + (@clubanderson) +--- + + + +## Introduction + +This document is an analysis of the effectiveness and completeness of the [Hive +Commons][project-website] open source software (OSS) project's documentation and +website. It is funded by the Cloud Native Computing Foundation (CNCF) as part of +its overall effort to incubate, grow, and graduate open source cloud native +software projects. + +According to CNCF best practices guidelines, effective documentation is a +prerequisite for program graduation. The documentation analysis is the first +step of a CNCF process aimed at assisting projects with their documentation +efforts. + +### Pilot of the AI-assisted assessment workflow + +This analysis is a **pilot run** of the `cncf-techdocs-assessment` AI-assisted +assessment workflow model (see [cncf/techdocs#395][issue-395]). Hive Commons is +not yet a CNCF project under assessment in the ordinary sense; the project +volunteered to be the first end-to-end test case for the intake → accept → draft +→ verify → stakeholder review → approval loop, before the workflow is run +against CNCF member projects. Hive Commons' own maintainers are also the authors +of the workflow model being piloted (see +`hivecommons/hive:src/docs/workflows/techdocs-assessment.md`), so this +assessment doubles as dogfooding of their own tooling. + +### AI assisted analysis + +The following parts of this analysis were generated by AI, from a dedicated +research pass over the in-scope repositories and live sites, and are pending +human technical-writer review and stakeholder sign-off before this pull request +is marked ready for review: + +- Overall comments, following the section heading, on the areas in that section. +- Answers to the criteria questions for an area. +- Comments, including strengths and weaknesses, for an area. +- Recommendations for improvements in each area. + +### Purpose + +This document was written to analyze the current state of Hive Commons +documentation. It aims to provide project leaders with an informed understanding +of potential problems in current project documentation. A second +[implementation][] document outlines an actionable plan for improvement, and a +third [issues list][] contains issues to be filed in the project documentation +repositories so that contributors can take them up. + +This document: + +- Analyzes the current Hive Commons technical documentation and website. +- Compares existing documentation against the CNCF's standards for a + **Sandbox**-level project (the project's current maturity level, per the + assessment request). +- Recommends a program of key improvements with the largest return on + investment. + +### Scope of analysis + +Hive Commons is a family of open source tools for working with AI coding agents. +The flagship project, **Hive**, is a CNCF Sandbox project; **Crux** (the agent +runtime extracted from Hive) and several smaller sibling tools (hotshot, pluk, +rationguard, promptargs, dibs, Spektacular) share the same documentation site +and organization but are out of scope for this analysis except where +`docs.hivecommons.dev` links into them. + +The documentation site (`docs.hivecommons.dev`) is a Next.js + Nextra site, +deployed on Netlify, with content for the Hive project synced at build time from +`hivecommons/hive`'s `src/docs/` tree (and sibling-project docs synced from +their own repositories). The marketing site (`hivecommons.dev`) is a +hand-written static HTML/CSS/vanilla-JS site with no build step, served from +GitHub Pages. + +#### In scope + +- Project website: [hivecommons.dev](https://hivecommons.dev) +- Documentation site: [docs.hivecommons.dev](https://docs.hivecommons.dev) +- Website/doc repository: +- Website source repository: + (source for + hivecommons.dev) +- — `src/docs/` only (in-repo reference + docs: api-reference, design, env-vars, agent-configuration) + +#### Out of scope + +- Sibling project sites and repositories (Crux, hotshot, pluk, rationguard, + promptargs, dibs, Spektacular), except where `docs.hivecommons.dev` links into + them. +- Source code and tests outside `hivecommons/hive`'s `src/docs/`. +- The org-level `hivecommons/.github` repository, which hosts the canonical + `GOVERNANCE.md` and `MAINTAINERS.md` referenced throughout this analysis; it + was consulted only through the cross-references made to it from the in-scope + repositories. + +### How this document is organized + +This document is divided into three sections that represent three major areas of +concern: + +- **Project documentation:** concerns documentation for users of the Hive + Commons software, aimed at people who intend to use the project software. +- **Contributor documentation:** concerns documentation for new and existing + contributors to the Hive Commons OSS project. +- **Website & Infrastructure:** concerns the mechanics of publishing the + documentation, and includes branding, website structure, and maintainability. + +Each section begins with summary ratings based on a rubric with appropriate +[criteria] for the section, then proceeds to: + +- **Comments**: observations about the existing documentation, including answers + to questions from the criteria specification. +- **Recommendations**: suggested changes that would improve the effectiveness of + the documentation. + +An accompanying [implementation][] document breaks the recommendations down into +concrete actions that can be implemented by project contributors. A third +document, the [issues list][], decomposes those actions into issues meant to be +filed on GitHub. + +### How to use this document + +Readers interested only in actionable improvements should skip this document and +read the [implementation][] plan and [issues list][]. + +Readers interested in the current state of the documentation and the reasoning +behind the recommendations should read the section of this document pertaining +to their area of concern: + +- [Project documentation](#project-documentation) +- [Contributor documentation](#contributor-documentation) +- [Website and infrastructure](#website-and-infrastructure) + +#### Recommendations, requirements, and best practices + +This analysis measures documentation against CNCF project maturity standards and +suggests possible improvements. In most cases there is more than one way to do +things. Few recommendations here are meant to be prescriptive. Rather, +recommendations are based on documentation best practices as understood by the +reviewers. In RFC terms, the changes described here should be understood as +"recommended" or "should" at the strongest, and "optional" or "may" in many +cases. Any "must" or "required" actions are clearly denoted as such, and pertain +to legal requirements such as copyright and licensing issues. + +## Project documentation + +Hive Commons is assessed here against **Sandbox** criteria, as requested in +[cncf/techdocs#395][issue-395]. Sandbox is CNCF's lightest-weight maturity +level: the +[minimal website requirements](../../../docs/analysis/criteria.md#minimal-website-requirements) +for Sandbox only ask for "rudimentary project documentation, or a placeholder or +substitute," with a note that it is acceptable to link out to documentation that +hasn't yet been integrated into a website. Hive Commons' documentation +substantially **exceeds** the Sandbox bar across the board — the ratings below +should be read in that light; most gaps noted here are standard-setting for an +_Incubating_-level bar, not deficiencies relative to Sandbox. + +| Criterion | Rating (1-5) | +| -------------------------- | ------------------------------ | +| Information architecture | 4 - Meets or exceeds standards | +| New user content | 4 - Meets or exceeds standards | +| Content maintainability | 4 - Meets or exceeds standards | +| Content creation processes | 4 - Meets or exceeds standards | +| Inclusive language | 3 - Meets standards | + +### Comments + +The following sections contain brief assessments of each element of the Project +Documentation rubric, based on the Hive (flagship) project's documentation, +which makes up the great majority of the content on `docs.hivecommons.dev`. + +#### Information architecture + +- **Is there high level conceptual content?** Yes. The docs site separates an + "Overview" section (introduction, architecture, roadmap, landscape) from + "Getting started"/"Operations" (instructional) and "Reference" (ADRs, + env-vars, API reference, design docs) for the flagship Hive project — a + Diátaxis-like split. +- **Is every product feature documented?** For Hive, apparently yes at a deep + level: the docs nav includes Dashboard, Integrating with Hive, Security, and a + Reference section with 24 ADRs, ~17 synced design docs, and 16 API-reference + sub-pages covering roughly 650 REST routes + (`hivecommons/hive:src/docs/api-reference.md`). For the sibling projects + (Crux, hotshot, pluk, rationguard, promptargs, dibs, Spektacular), coverage is + thin: each has only 1-4 pages on the docs site, effectively stub-level next to + Hive's ~100+ pages. These are out of scope for ratings here but affect the + overall impression of the Hive Commons docs site as a whole. +- **Is there a complete API reference?** Yes, and unusually thorough for a + Sandbox project — 16 hand-maintained pages covering ~650 routes. The page + itself documents its own maintenance risk: "There is no generator; update this + page in the same change that adds or renames a route," and explicitly excludes + request/response schemas ("see the handler source"). This is a process gap + worth flagging (see Recommendations) even though the content that does exist + is comprehensive. +- **Are there CLI references?** Partial. `hivectl.md` and `crux-cli.md` exist + under "Operations," but there is no discrete, top-level "CLI reference" nav + entry comparable to the API reference section. +- **Is content up to date and accurate?** Design docs (`src/docs/design/`) are + explicitly framed as historical decision records, not operator documentation, + which helps prevent staleness from leaking into user-facing pages. However, + roughly half of the ~30 in-repo design docs are not synced to the live nav + (`page-map.ts`), so there is in-repo content a reader browsing the repository + will find that is absent from the published site — not necessarily a problem + (the README frames design docs as developer-facing), but worth a one-line note + on the design-docs index. +- **Does the documentation separate conceptual, instructional, and reference + information?** Yes, for Hive. This is one of the strongest aspects of the + information architecture. +- **Does the documentation organization need high-level restructuring?** No + evidence of this for Hive; the main architectural question is the uneven depth + across the Hive Commons family of projects on a single docs site, which is a + product/roadmap decision more than a documentation-architecture flaw. + +#### New user content + +- **Is "getting started" clearly labeled?** Yes, and present at multiple levels: + a top-level "Getting started" docs nav item + (`docs.hivecommons.dev/docs/hive/overview/getting-started`), a canonical + source (`hivecommons/hive:src/docs/getting-started.md`, titled "Zero to + Automation: Getting Started with Hive"), and a direct "Install" link from the + project README. +- **Is installation documented step-by-step?** Yes, with four distinct, + dedicated install paths documented in a table in the README: Docker Compose, + Podman, Kubernetes, and a hosted option. Each has its own guide + (`quickstart-docker-compose.md`, `quickstart-podman.md`, + `kubernetes-deployment.md`, `hosted-hub.md`). +- **Are different types of installation documented if necessary?** Yes — Docker + Compose, Podman (explicitly described as "a parallel supported choice, not an + experiment"), Kubernetes, and hosted are all first-class options, which is + more install-path coverage than most Sandbox or even Incubating projects + provide. +- **Are multiple OSes documented?** Yes — the Docker Compose quickstart states + explicit support for "Linux, macOS, or Windows (WSL2) host on amd64 or arm64." +- **Is there guidance for what to read next?** Yes — the getting-started page + links onward to the documentation map, architecture doc, agent-configuration + reference, the ACMM policy matrix, and a named "first-session route." +- **Is there easily copy-pastable sample code?** Yes, confirmed in the Docker + Compose quickstart (clone, copy config, `sed` edit, with inline callouts for + known gotchas like port mismatches). + +#### Content maintainability & site mechanics + +- **Is the documentation searchable?** Yes — the docs site has a working + `/api/search` route backing in-site search. The marketing site + (`hivecommons.dev`) has no search, but it is a single static page, so this is + appropriate for its scope. +- **Is the project planning for localization?** Already implemented, not just + planned: the docs site supports 10 locales via `next-intl` (en, hi, ja, es, + de, fr, it, Simplified Chinese, Traditional Chinese, pt), with message files + per locale and a language-switcher component. This is well beyond what most + Sandbox or Incubating projects have in place. +- **Is there a documented method for versioning content?** Yes — a version + registry (`src/config/versions.ts`) tracks Hive's `latest` (v5, rendered on + the docs site), `v6` ("Edge," links externally to GitHub for unreleased docs), + and `v4` ("Frozen," links externally). Sibling projects are pinned to `main` + only (unversioned), which is reasonable given their current scope. +- **Is release-specific information documented in release notes?** Yes — a + `CHANGELOG.md` plus a fragment-based changelog system (`changelog.d/*.md`) + with CI enforcement of fragment format. +- **Is the documentation free of duplicate or near-duplicate content?** The + project's architecture is explicitly designed to avoid content drift despite + spanning three repositories: Hive and sibling-project docs are the + single-authored source in their own repos (`hivecommons/hive:src/docs/`, etc.) + and are synced into `hivecommons/docs` at build time by + `scripts/sync-hive-docs.ts` / `scripts/sync-sibling-docs.ts`, with a CI + drift-detection test suite and a documented "do not edit the synced copy" + convention. This is a well-engineered answer to the single-source requirement + (see the Website section below) rather than an uncontrolled duplication + problem — but it does mean the _canonical_ source for most content a visitor + reads on `docs.hivecommons.dev` is not actually in the `hivecommons/docs` + repository, which is worth stating plainly for anyone auditing "where do I + file a docs bug." + +#### Content creation processes + +- **Is there a clear path to contributor documentation?** Yes, in all three + in-scope repositories (see Contributor documentation section below). +- **Does the release process account for documentation updates?** Yes, for the + API reference specifically: the page itself instructs contributors to "update + this page in the same change that adds or renames a route," though this is a + social convention rather than a CI-enforced check (no evidence of an automated + route/doc-drift check for the API reference, unlike the docs sync drift-check + which is CI-enforced). +- **Who reviews and approves documentation PRs?** Clearly documented via + `CODEOWNERS`/`OWNERS` files in each repo. `hivecommons/docs` is single-owner + (`@clubanderson`), which is a bus-factor risk worth noting. + `hivecommons.github.io` has two owners (`@clubanderson`, `@kellyaa`). +- **Does the website have a clear owner/maintainer?** Yes, documented, though + concentrated in one or two individuals for the docs/website repos specifically + (as distinct from the `hive` repo's five-person maintainer roster). + +#### Inclusive language + +A sampling-based review of README, CONTRIBUTING, GOVERNANCE, getting-started, +and "what is Hive Commons" content found no non-inclusive terminology (no +master/slave, blacklist/whitelist, or similar terms; branch names are +`main`/`v4`/`v5`/`v6`). No instances of language that minimizes difficulty for +the reader (e.g. "simply," "just") were found trivializing setup steps in the +sampled getting-started/contributing content. This was not an exhaustive, +full-corpus scan of the roughly 575 files in `hivecommons/docs` or the 250+ +files under `hive/src/docs/`, so the rating reflects a sample, not a certified +clean bill across the whole corpus. + +### Recommendations + +#### Information architecture + +- Add a short top-level "CLI reference" nav entry/landing page that links + `hivectl.md` and `crux-cli.md` together, rather than leaving them scattered + under "Operations" with no single entry point — a quick win for + discoverability. +- Consider an automated check (even a simple CI script that diffs route + registrations in the Go source against `api-reference.md`'s route list) to + reduce drift risk in the hand-maintained, ~650-route API reference, given it + has no generator today. +- Add a one-line note to `src/docs/design/README.md` (or the design-docs index) + explaining that only a subset of design docs is synced to the public docs + site, with a pointer to the repository for the rest — this avoids surprising a + reader who finds a design doc in-repo that is not on the website. + +#### New user content + +No significant gaps identified; this area already exceeds the Sandbox and +Incubating bar. Continue the current practice of maintaining install guides per +deployment target as new ones are added. + +#### Content maintainability & site mechanics + +- Document, in one visible place (for example the top of + `hivecommons/docs:README.md`'s "How content is sourced" section, which already + covers most of this), a short FAQ answer to "I found a typo/bug on + docs.hivecommons.dev — where do I file it?" pointing readers to the correct + upstream repository based on which project's page they were reading. The sync + architecture is well documented for contributors who already know to look in + `README.md`/`CONTRIBUTING.md`, but a documentation bug reporter coming in from + the live site via GitHub's "Edit this page" pattern (if present) or a generic + "report an issue" link could easily file against the wrong repository. + +#### Content creation processes + +- Consider adding a second owner/approver to `hivecommons/docs`'s + `CODEOWNERS`/`OWNERS` (currently `@clubanderson` alone) to reduce + single-point-of-failure risk for docs-site reviews, matching the two-owner + pattern already used in `hivecommons.github.io`. +- Add a lightweight CI check (even a `grep`-based one) that fails if + `src/docs/api-reference.md`'s stated route-count or page list has not been + touched in the same PR that modifies route registrations, to make the existing + "update this page in the same change" convention enforceable rather than + purely social. + +#### Inclusive language + +No specific recommendation beyond continuing current practice; consider adding +an automated inclusive-language linter (such as `alex` or `woke`) to CI for +full-corpus coverage, since the finding above is sampling-based rather than +exhaustive. + +## Contributor documentation + +| Criterion | Rating (1-5) | +| ----------------------------------------- | ------------------------------ | +| Communication methods documented | 5 - Exemplary | +| Beginner friendly issue backlog | 3 - Meets standards | +| "New contributor" getting started content | 4 - Meets or exceeds standards | +| Project governance documentation | 5 - Exemplary | + +### Comments + +#### Communication methods documented + +Exceptionally well covered for a Sandbox-level project. Discord, GitHub, GitHub +Discussions, a Google Group mailing list, a biweekly community meeting with +public ICS calendar, agenda, YouTube recordings, and a Twitch livestream are all +documented and cross-linked via short, memorable redirect URLs +(`hivecommons.dev/discord`, `/meet`, `/agenda`, `/calendar`, `/join`, `/tv`, +`/code`, `/github`, `/twitch`, `/youtube`), generated programmatically from a +single source list rather than hand-maintained in multiple places. A published, +RFC 9116-compliant `security.txt` with an annually renewed `Expires:` field is a +further sign of mature communications hygiene uncommon even among Incubating +projects. + +#### Beginner friendly issue backlog + +The `good first issue` and `help wanted` labels are actively documented, with +direct search links from contributor-onboarding docs in all three in-scope +repositories, and a bespoke bot-driven mechanism that applies these labels and +posts a welcome comment pointing to a "contributor relay" claim flow. However, +**at assessment time, zero open issues carry the `good first issue` label in any +of the three in-scope repositories** (`hivecommons/docs`, `hivecommons/hive`, +`hivecommons.github.io`), and `hivecommons/docs` and `hivecommons.github.io` +currently have zero open issues of any kind. `hivecommons/hive` has 10 open +`help wanted` issues, which are well-specified (clear repro/context in the +title), but none are labeled for newcomers specifically. The pipeline and +documentation for a beginner-friendly backlog are in place; the backlog itself +is currently empty for new documentation contributors to pick up. + +#### New contributor getting started content + +A distinct, well-developed `getting-started-contributing.md` document exists in +`hivecommons/hive`, separate from the end-user install docs, with a 6-step path +covering: finding claimable work, local environment setup without needing a +cluster, running tests without a cluster, a pre-reading list before touching +agent policy, an explanation of the project's own bot behavior on contributor +PRs, and a named list of the 10 required CI checks. `CONTRIBUTING.md` in both +`hivecommons/docs` and `hivecommons.github.io` follows the same "finding +something to work on" + community-link pattern. DCO sign-off (`git commit -s`) +is consistently required and documented across all three repositories' +CONTRIBUTING guides. + +#### Project governance documentation + +`GOVERNANCE.md` in `hivecommons/hive` is thorough: it names the CNCF Sandbox +status, lists all five current maintainers with handles and affiliations, +documents a lazy-consensus decision process with maintainer-committee +escalation, links to the org-level maintainer-promotion ladder with explicit, +numeric criteria, and includes an unusually detailed "AI Agents and Automation" +governance section (agents are tooling, not members; every agent has a named +responsible human; every merge needs a human approver). A documented consistency +mechanism requires the maintainer roster recorded in three different places (org +`MAINTAINERS.md`, root `OWNERS`, and `hive`'s `GOVERNANCE.md`) to agree, +explicitly calling drift between them "a governance bug" — and the three were +found consistent at assessment time. `hivecommons/docs` and +`hivecommons.github.io` do not duplicate a `GOVERNANCE.md` of their own; they +defer to the org-level document, which is a reasonable choice for support +repositories but is not stated explicitly in either repo's own README — a reader +starting from one of those two repos has to infer that governance applies +org-wide. + +### Recommendations + +#### Communication methods documented + +No recommendation; this area is already exemplary. + +#### Beginner friendly issue backlog + +- Seed a small number (3-5) of `good first issue`-labeled documentation tasks in + `hivecommons/docs` and `hivecommons.github.io` — the [issues list][] + accompanying this analysis is a ready-made source for this, since + documentation-improvement issues are, by nature, well suited to a + newcomer-friendly backlog. +- Since the automated welcome-comment/labeling mechanism already exists for + `hive`, consider extending the same bot behavior (or a lighter-weight version + of it) to `hivecommons/docs` and `hivecommons.github.io`, which currently have + no open issues to apply it to. + +#### New contributor getting started content + +No significant gaps identified. + +#### Project governance documentation + +- Add one sentence to the top of `hivecommons/docs:README.md` and + `hivecommons.github.io:README.md` stating that project governance is defined + at the organization level (with a link to + `hivecommons/.github:GOVERNANCE.md`), so a reader who starts from either + support repository does not have to discover this indirectly through + cross-references in `hive`'s own `GOVERNANCE.md`. + +## Website and infrastructure + +| Criterion | Rating (1-5) | +| ------------------------------------------- | ------------------------------ | +| Single-source for all files | 4 - Meets or exceeds standards | +| Meets min website req. (for maturity level) | 5 - Exemplary | +| Usability, accessibility, and design | 3 - Meets standards | +| Branding and design | 4 - Meets or exceeds standards | +| Case studies & social proof | 2 - Needs improvement | +| SEO, Analytics, and site-local search | 4 - Meets or exceeds standards | +| Maintenance planning | 4 - Meets or exceeds standards | +| AI agent readiness | 4 - Meets or exceeds standards | +| HTTPS access & HTTP redirect | 5 - Exemplary | + +### Comments + +#### Single-source requirement + +Strictly speaking, Hive's documentation content is built in one repository +(`hivecommons/hive`) and marketing copy in another (`hivecommons.github.io`), +with the docs site (`hivecommons/docs`) pulling both into a third repository as +synced, committed build artifacts. This is a multi-repo arrangement on its face, +but the project has implemented exactly the kind of "clearly documented strategy +for managing mirrored files" the criteria call for as the alternative to true +single-sourcing: automated prebuild sync scripts, a 30-second fetch timeout with +fail-the-build-if- unreachable semantics (so stale content is never silently +deployed), a CI drift-detection test suite, and an explicit "do not edit +`docs/content/` directly, edit the canonical source" convention stated in both +`README.md` and `CONTRIBUTING.md`. This is a materially stronger answer to the +single-source requirement than most CNCF projects provide, even though it is not +literally single-sourced. + +#### Minimal website requirements + +For a Sandbox project, the bar is "rudimentary project documentation, or a +placeholder." Hive Commons' documentation is already deep enough to clear the +_Incubating_ bar in most respects (hosted directly, single-source strategy +addressed as above, broad stakeholder coverage via the layered +Overview/Getting-started/Reference structure) — well beyond what Sandbox +requires. + +#### Usability, accessibility and devices + +Not independently browser-tested as part of this pass (see Scope note in the +accompanying research). The docs site uses Tailwind CSS 4 (a +responsive-by-default utility framework); the marketing site's hand-written CSS +includes `prefers-color-scheme` media queries, suggesting attention to adaptive +rendering, but neither a live mobile-viewport check nor a formal accessibility +audit (contrast ratios, screen-reader pass, keyboard-only navigation) was +performed. Rated "meets standards" provisionally; a follow-up manual or +automated (e.g. axe-core/Lighthouse) accessibility pass is recommended before +this criterion can be rated with confidence. + +#### Branding and design + +Strong and consistent: a dark "honey on wax" color palette defined via CSS +custom properties, self-hosted font pairing (Fraunces serif + IBM Plex Sans), an +inline-SVG hexagon/honeycomb brand mark reused across hero art and the header +logo, and CNCF-provided logo artwork (three color variants, PNG+SVG) checked +into the `hive` repository. Fonts are self-hosted rather than loaded from a +third-party CDN, which is a good practice for both performance and privacy. + +#### Case studies and social proof + +This is the weakest area found in the website assessment. No user testimonials, +logo wall of adopters, or dedicated case-studies page was identified in the +research pass; the marketing site's `sitemap.xml` lists only two URLs (`/` and +`/stories/`), and the `/stories/` page's content was not independently verified +as populated. An "Adopters" section is listed in `llms.txt`, which suggests the +project is tracking adopters somewhere, but this has not obviously surfaced as a +human-readable case-studies or testimonial page on the main site. Given this is +appropriate — and arguably expected — for a project that reached CNCF Sandbox +status in the same month this assessment was requested (October 2026), this is +flagged as an area to revisit at the next maturity-level review rather than an +urgent gap today. + +#### SEO, Analytics and site-local search + +Both `robots.txt` files are fully open to crawlers and point to generated +sitemaps. Google Analytics (GA4) is wired into the docs site via a dedicated +component with a custom-event helper; no analytics tag was found on the +marketing site, whose Content-Security-Policy (`default-src 'none'` with +SHA-256-pinned inline scripts) would not currently permit a third-party +analytics script to load even if one were added without a CSP update — worth +noting if analytics on the marketing site is ever desired. Both sites carry +extensive Open Graph/Twitter-card meta tags and `schema.org` JSON-LD structured +data for the whole project family. In-site search works via a dedicated API +route on the docs site. + +#### Maintenance planning + +The project uses a conventional, well-supported stack (Next.js + Nextra, +Tailwind, Netlify) for the docs site and a deliberately minimal hand-written +static site for the marketing page, each sized appropriately to its complexity. +CI gates (build, link-check, markdown lint, TypeScript/lint, Vitest with +coverage, DCO) and a changelog-fragment system suggest active, disciplined +maintenance. The one bus-factor risk noted above (`@clubanderson` as sole code +owner of `hivecommons/docs`) is the main maintenance-planning concern +identified. + +#### AI Agent Readiness + +This is a standout area. `llms.txt` exists on both domains +(`hivecommons.dev/llms.txt` and `docs.hivecommons.dev/llms.txt`), each kept in +sync with on-page content by dedicated, CI-enforced tests rather than hand +maintenance — directly satisfying the criterion's "stay in sync with the +published site" bar. Both sites are confirmed server-rendered/static, with +substantive content present in the raw HTML payload rather than behind +client-side hydration — confirmed by a raw (non-JS) fetch of both a marketing +page and a docs page. `robots.txt` imposes no crawler restrictions, and no CDN +bot-challenge gating was observed. The one gap: there is no per-page Markdown +mirror (appending `.md` to a docs URL returns 404), so `llms.txt` is currently +the only machine-readable summary surface rather than a full parallel Markdown +version of every page, which the criteria call out as a distinct, additional +practice from `llms.txt` itself. + +#### HTTPS access & HTTP redirect + +Both domains serve HTTPS with confirmed HTTP→HTTPS redirects (301). The docs +site additionally sends an HSTS header +(`strict-transport-security: max-age=31536000`); the marketing site's HSTS +header was not observed in the sample captured during this pass, which may be a +CDN/edge-cache sampling artifact rather than a true absence and is worth a +direct re-check against origin. + +### Recommendations + +#### Single-source requirement + +No structural recommendation; the current sync-with-CI-drift-detection +architecture is a reasonable and well-engineered alternative to literal +single-sourcing. Continue investing in the drift-detection test suite as the +project family grows. + +#### Minimal website requirements + +None; already well above the Sandbox bar. + +#### Usability, accessibility and devices + +- Run an automated accessibility scan (axe-core or Lighthouse) against both + sites and record the results (even informally, as a comment on the tracking + issue for this analysis) so this criterion can move from "provisional" to a + confirmed rating at the next review. + +#### Branding and design + +No recommendation; this area is strong. + +#### Case studies and social proof + +- Populate (or link to) a case-studies/adopters page from the main site + navigation, reusing the adopter list already maintained for `llms.txt` as a + starting point, once early adopters are willing to be named publicly. + +#### SEO, Analytics and site-local search + +- If analytics on the marketing site is ever desired, update its CSP + `script-src` allowlist (SHA-256 pin or nonce) rather than relaxing it broadly, + to preserve the current strict CSP posture. + +#### Maintenance planning + +- Add a second code owner to `hivecommons/docs` (see Content creation processes + recommendation above) to reduce single-maintainer risk. + +#### AI Agent Readiness + +- Consider adding a per-page Markdown mirror (for example, serving the + underlying MDX/Markdown source at the same path with `.md` appended) for the + docs site, complementing the already-strong `llms.txt` implementation, per the + full AI Agent Readiness criterion. + +#### References and notes + +##### Rating values + +The numeric rating values used in this document are as follows: + +1. Not present +2. Needs improvement +3. Meets standards +4. Meets or exceeds standards +5. Exemplary + +[criteria]: ../../../docs/analysis/criteria.md +[implementation]: ./implementation.md +[issues list]: ./issues.md +[issue-395]: https://github.com/cncf/techdocs/issues/395 +[project-website]: https://hivecommons.dev diff --git a/analyses/2026/hivecommons/implementation.md b/analyses/2026/hivecommons/implementation.md new file mode 100644 index 00000000..8899521b --- /dev/null +++ b/analyses/2026/hivecommons/implementation.md @@ -0,0 +1,87 @@ +--- +title: Implementing Hive Commons Doc Improvements +tags: [hivecommons] +--- + + + +## Introduction + +This document provides actionable suggestions for improving the Hive Commons +technical documentation. + +For an analysis and general discussion of recommendations on Hive Commons +technical documentation, see [analysis.md](analysis.md). + +### Recommendations, requirements, and best practices + +This analysis measures documentation against CNCF project maturity standards and +suggests possible improvements. In most cases there is more than one way to do +things. Few recommendations here are meant to be prescriptive. Rather, +recommendations are based on documentation best practices as understood by the +reviewers. Borrowing terminology from the lexicon of [RFCs][rfc-keywords], the +changes described here should be understood as "recommended" or "should" at the +strongest, and "optional" or "may" in many cases. + +Hive Commons' documentation already exceeds the Sandbox-level bar in nearly +every area (see [analysis.md](analysis.md)), so this plan is deliberately small: +a handful of targeted, independent, low-effort actions rather than a large +restructuring program. The top-level actions are: + +1. **Close the newcomer-backlog gap.** The labeling pipeline and contributor + onboarding docs for a beginner-friendly issue backlog are in place, but no + open issue currently carries `good first issue` in any of the three in-scope + repositories. Seed a small backlog directly from this plan. +2. **Reduce single-points-of-failure and drift risk.** Two specific places rely + on a single owner or a purely social convention where a lightweight technical + safeguard would help: `hivecommons/docs` code ownership, and the + hand-maintained API reference's route-list staying in sync with the Go + source. +3. **Close small, self-contained documentation/navigation gaps.** A missing + CLI-reference landing page, an unstated cross-repo governance pointer, and an + unconfirmed accessibility rating are each independent, quick fixes. + +## High-level action 1: Seed a beginner-friendly documentation backlog + +### Issue 1 + +File the issues from the accompanying [issues list](issues.md) directly in +`hivecommons/docs` (and one in `hivecommons.github.io`), each pre-labeled +`good first issue` and `documentation`, so first-time contributors have +something to claim immediately. + +## High-level action 2: Reduce bus-factor and content-drift risk + +### Issue 1 + +Add a second approver/reviewer to `hivecommons/docs`'s `CODEOWNERS` and `OWNERS` +files, mirroring the two-owner pattern already used in `hivecommons.github.io`. + +### Issue 2 + +Add a CI check (a simple script is sufficient) that flags a pull request +touching Go route registrations in `hivecommons/hive` when it does not also +touch `src/docs/api-reference.md` or the relevant `src/docs/api-reference/*` +page, making the existing "update this page in the same change" convention +enforceable rather than purely social. + +## High-level action 3: Close small, independent documentation gaps + +### Issue 1 + +Add a short "CLI reference" landing page (or a nav entry) on +`docs.hivecommons.dev` linking `hivectl.md` and `crux-cli.md` together. + +### Issue 2 + +Add a one-sentence pointer to the org-level `GOVERNANCE.md` at the top of +`hivecommons/docs:README.md` and `hivecommons.github.io:README.md`. + +### Issue 3 + +Run an automated accessibility scan (axe-core or Lighthouse) against both +`hivecommons.dev` and `docs.hivecommons.dev`, and record the results (for +example, as a comment on the tracking issue for this analysis) to confirm or +correct the provisional "meets standards" rating given in the analysis. + +[rfc-keywords]: https://www.rfc-editor.org/rfc/rfc2119 diff --git a/analyses/2026/hivecommons/issues.md b/analyses/2026/hivecommons/issues.md new file mode 100644 index 00000000..9099df39 --- /dev/null +++ b/analyses/2026/hivecommons/issues.md @@ -0,0 +1,140 @@ +--- +title: Hive Commons Umbrella Issue and Issues List +tags: [hivecommons] +--- + +## Overview + +This is a short, deliberately small backlog: Hive Commons' documentation already +exceeds the CNCF Sandbox bar in nearly every area evaluated (see +[analysis.md](analysis.md)), so the issues below are independent, low-effort, +high-value items rather than a large restructuring program. Several are +explicitly suited to first-time contributors and are intended to be filed with a +`good first issue` label, since the analysis found that label currently unused +on open issues in all three in-scope repositories. + +This issue tracks recommended changes resulting from an analysis of the Hive +Commons documentation requested in +[cncf/techdocs#395](https://github.com/cncf/techdocs/issues/395). The analysis +and supporting documents are here: +. + +The CNCF Tech Docs effort is tracked in the CNCF Tech Docs repo: +. + +## Umbrella issue + +> To be filed in `hivecommons/hive` (or the org-level `.github` repo, per +> maintainer preference) once this analysis is reviewed and accepted by project +> maintainers. Link each sub-issue below to it with a Markdown checkbox once +> filed. + +## Issues + +### Issue: Add a CLI reference landing page + +Audience: New and existing Hive/Crux users looking for command-line tool +documentation. + +Type: Reference / Information architecture. + +`hivectl.md` and `crux-cli.md` exist under "Operations" on +`docs.hivecommons.dev` but have no shared landing page or top-level nav entry +comparable to the existing API reference section. Add a short "CLI reference" +page (or a nav grouping) that links both, so a reader looking for "the CLI docs" +has one obvious starting point. + +Related material: `hivecommons/hive:src/docs/hivectl.md`, +`hivecommons/hive:src/docs/crux-cli.md`, +`hivecommons/docs:src/app/docs/page-map.ts`. + +- [ ] `https://github.com/hivecommons/hive/issues/NNN` + +### Issue: State the org-level governance pointer in docs/website READMEs + +Audience: New contributors and auditors starting from `hivecommons/docs` or +`hivecommons.github.io` rather than `hivecommons/hive`. + +Type: Conceptual / Governance. + +Neither `hivecommons/docs:README.md` nor `hivecommons.github.io:README.md` +states that project governance is defined at the organization level. A reader +has to infer this indirectly via cross-references in `hive`'s own +`GOVERNANCE.md`. Add one sentence to the top of each README linking to +`hivecommons/.github:GOVERNANCE.md`. + +- [ ] `https://github.com/hivecommons/docs/issues/NNN` +- [ ] `https://github.com/hivecommons/hivecommons.github.io/issues/NNN` + +### Issue: Add a second code owner to hivecommons/docs + +Audience: Project maintainers (bus-factor/maintenance planning). + +Type: Process. + +`hivecommons/docs`'s `CODEOWNERS` and `OWNERS` files currently list only +`@clubanderson` as approver/reviewer, unlike `hivecommons.github.io`, which +already has two. Add a second approver to reduce single-maintainer risk for +docs-site reviews. + +- [ ] `https://github.com/hivecommons/docs/issues/NNN` + +### Issue: Add a drift check between API routes and the API reference + +Audience: Hive maintainers and contributors adding/renaming API routes. + +Type: Process / Reference accuracy. + +`src/docs/api-reference.md` states "There is no generator; update this page in +the same change that adds or renames a route," but nothing currently enforces +this. Add a lightweight CI check (even a simple diff/grep-based script comparing +route registrations in the Go source against the documented route list in +`src/docs/api-reference/*`) that flags a PR touching routes without a +corresponding doc update. + +Suggested changes: + +- Prerequisites: familiarity with the Go route-registration pattern used in + `hivecommons/hive`. +- Procedure: + 1. Write a script that extracts registered route paths from the relevant Go + source files. + 2. Compare the extracted list against the routes documented in + `src/docs/api-reference/*.md`. + 3. Fail CI (or post a PR comment) when a new/changed/removed route has no + corresponding documentation change in the same PR. +- Result: a PR that adds or renames a route without a matching documentation + change is flagged before merge rather than relying on the "update this page in + the same change" convention alone. + +- [ ] `https://github.com/hivecommons/hive/issues/NNN` + +### Issue: Run and record an accessibility scan for both sites + +Audience: Project maintainers; informs a future documentation re-assessment. + +Type: Task. + +Neither `hivecommons.dev` nor `docs.hivecommons.dev` has had a recorded, +automated accessibility scan. Run axe-core or Lighthouse against both sites and +record the results (for example, as a comment on the tracking issue for this +analysis, or a short doc under `src/docs/`), so the "Usability, accessibility +and devices" rating in [analysis.md](analysis.md) can move from provisional to +confirmed at the next review. + +- [ ] `https://github.com/hivecommons/hivecommons.github.io/issues/NNN` + +### Issue: Seed a beginner-friendly documentation issue backlog + +Audience: First-time contributors. + +Type: Process / Community. + +At assessment time, zero open issues carry the `good first issue` label in any +of `hivecommons/docs`, `hivecommons/hive`, or `hivecommons.github.io`, even +though the label and its supporting onboarding documentation exist and are +actively referenced. File the issues above (and any other small, independent +documentation tasks maintainers identify) with `good first issue` and +`documentation` labels to give new contributors something to claim immediately. + +- [ ] `https://github.com/hivecommons/docs/issues/NNN` From ba9826521c920f8b3b70cfd481152cae719dae20 Mon Sep 17 00:00:00 2001 From: quality <280983584+hivecommons-hive[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 00:02:53 -0500 Subject: [PATCH 2/5] docs: remove em-dashes from Hive Commons analysis Replace every em-dash (U+2014) in the Hive Commons analysis with a spaced hyphen or comma, whichever reads naturally. No other text was changed. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- analyses/2026/hivecommons/analysis.md | 46 +++++++++++++-------------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/analyses/2026/hivecommons/analysis.md b/analyses/2026/hivecommons/analysis.md index c90bcf3d..69caaf60 100644 --- a/analyses/2026/hivecommons/analysis.md +++ b/analyses/2026/hivecommons/analysis.md @@ -89,7 +89,7 @@ GitHub Pages. - Website source repository: (source for hivecommons.dev) -- — `src/docs/` only (in-repo reference +- - `src/docs/` only (in-repo reference docs: api-reference, design, env-vars, agent-configuration) #### Out of scope @@ -161,7 +161,7 @@ level: the for Sandbox only ask for "rudimentary project documentation, or a placeholder or substitute," with a note that it is acceptable to link out to documentation that hasn't yet been integrated into a website. Hive Commons' documentation -substantially **exceeds** the Sandbox bar across the board — the ratings below +substantially **exceeds** the Sandbox bar across the board - the ratings below should be read in that light; most gaps noted here are standard-setting for an _Incubating_-level bar, not deficiencies relative to Sandbox. @@ -184,7 +184,7 @@ which makes up the great majority of the content on `docs.hivecommons.dev`. - **Is there high level conceptual content?** Yes. The docs site separates an "Overview" section (introduction, architecture, roadmap, landscape) from "Getting started"/"Operations" (instructional) and "Reference" (ADRs, - env-vars, API reference, design docs) for the flagship Hive project — a + env-vars, API reference, design docs) for the flagship Hive project - a Diátaxis-like split. - **Is every product feature documented?** For Hive, apparently yes at a deep level: the docs nav includes Dashboard, Integrating with Hive, Security, and a @@ -196,7 +196,7 @@ which makes up the great majority of the content on `docs.hivecommons.dev`. Hive's ~100+ pages. These are out of scope for ratings here but affect the overall impression of the Hive Commons docs site as a whole. - **Is there a complete API reference?** Yes, and unusually thorough for a - Sandbox project — 16 hand-maintained pages covering ~650 routes. The page + Sandbox project - 16 hand-maintained pages covering ~650 routes. The page itself documents its own maintenance risk: "There is no generator; update this page in the same change that adds or renames a route," and explicitly excludes request/response schemas ("see the handler source"). This is a process gap @@ -210,7 +210,7 @@ which makes up the great majority of the content on `docs.hivecommons.dev`. which helps prevent staleness from leaking into user-facing pages. However, roughly half of the ~30 in-repo design docs are not synced to the live nav (`page-map.ts`), so there is in-repo content a reader browsing the repository - will find that is absent from the published site — not necessarily a problem + will find that is absent from the published site - not necessarily a problem (the README frames design docs as developer-facing), but worth a one-line note on the design-docs index. - **Does the documentation separate conceptual, instructional, and reference @@ -234,14 +234,14 @@ which makes up the great majority of the content on `docs.hivecommons.dev`. Podman, Kubernetes, and a hosted option. Each has its own guide (`quickstart-docker-compose.md`, `quickstart-podman.md`, `kubernetes-deployment.md`, `hosted-hub.md`). -- **Are different types of installation documented if necessary?** Yes — Docker +- **Are different types of installation documented if necessary?** Yes, Docker Compose, Podman (explicitly described as "a parallel supported choice, not an experiment"), Kubernetes, and hosted are all first-class options, which is more install-path coverage than most Sandbox or even Incubating projects provide. -- **Are multiple OSes documented?** Yes — the Docker Compose quickstart states +- **Are multiple OSes documented?** Yes, the Docker Compose quickstart states explicit support for "Linux, macOS, or Windows (WSL2) host on amd64 or arm64." -- **Is there guidance for what to read next?** Yes — the getting-started page +- **Is there guidance for what to read next?** Yes, the getting-started page links onward to the documentation map, architecture doc, agent-configuration reference, the ACMM policy matrix, and a named "first-session route." - **Is there easily copy-pastable sample code?** Yes, confirmed in the Docker @@ -250,7 +250,7 @@ which makes up the great majority of the content on `docs.hivecommons.dev`. #### Content maintainability & site mechanics -- **Is the documentation searchable?** Yes — the docs site has a working +- **Is the documentation searchable?** Yes, the docs site has a working `/api/search` route backing in-site search. The marketing site (`hivecommons.dev`) has no search, but it is a single static page, so this is appropriate for its scope. @@ -259,12 +259,12 @@ which makes up the great majority of the content on `docs.hivecommons.dev`. de, fr, it, Simplified Chinese, Traditional Chinese, pt), with message files per locale and a language-switcher component. This is well beyond what most Sandbox or Incubating projects have in place. -- **Is there a documented method for versioning content?** Yes — a version +- **Is there a documented method for versioning content?** Yes, a version registry (`src/config/versions.ts`) tracks Hive's `latest` (v5, rendered on the docs site), `v6` ("Edge," links externally to GitHub for unreleased docs), and `v4` ("Frozen," links externally). Sibling projects are pinned to `main` only (unversioned), which is reasonable given their current scope. -- **Is release-specific information documented in release notes?** Yes — a +- **Is release-specific information documented in release notes?** Yes, a `CHANGELOG.md` plus a fragment-based changelog system (`changelog.d/*.md`) with CI enforcement of fragment format. - **Is the documentation free of duplicate or near-duplicate content?** The @@ -276,7 +276,7 @@ which makes up the great majority of the content on `docs.hivecommons.dev`. drift-detection test suite and a documented "do not edit the synced copy" convention. This is a well-engineered answer to the single-source requirement (see the Website section below) rather than an uncontrolled duplication - problem — but it does mean the _canonical_ source for most content a visitor + problem - but it does mean the _canonical_ source for most content a visitor reads on `docs.hivecommons.dev` is not actually in the `hivecommons/docs` repository, which is worth stating plainly for anyone auditing "where do I file a docs bug." @@ -317,7 +317,7 @@ clean bill across the whole corpus. - Add a short top-level "CLI reference" nav entry/landing page that links `hivectl.md` and `crux-cli.md` together, rather than leaving them scattered - under "Operations" with no single entry point — a quick win for + under "Operations" with no single entry point - a quick win for discoverability. - Consider an automated check (even a simple CI script that diffs route registrations in the Go source against `api-reference.md`'s route list) to @@ -325,7 +325,7 @@ clean bill across the whole corpus. has no generator today. - Add a one-line note to `src/docs/design/README.md` (or the design-docs index) explaining that only a subset of design docs is synced to the public docs - site, with a pointer to the repository for the rest — this avoids surprising a + site, with a pointer to the repository for the rest - this avoids surprising a reader who finds a design doc in-repo that is not on the website. #### New user content @@ -339,7 +339,7 @@ deployment target as new ones are added. - Document, in one visible place (for example the top of `hivecommons/docs:README.md`'s "How content is sourced" section, which already covers most of this), a short FAQ answer to "I found a typo/bug on - docs.hivecommons.dev — where do I file it?" pointing readers to the correct + docs.hivecommons.dev - where do I file it?" pointing readers to the correct upstream repository based on which project's page they were reading. The sync architecture is well documented for contributors who already know to look in `README.md`/`CONTRIBUTING.md`, but a documentation bug reporter coming in from @@ -428,11 +428,11 @@ governance section (agents are tooling, not members; every agent has a named responsible human; every merge needs a human approver). A documented consistency mechanism requires the maintainer roster recorded in three different places (org `MAINTAINERS.md`, root `OWNERS`, and `hive`'s `GOVERNANCE.md`) to agree, -explicitly calling drift between them "a governance bug" — and the three were +explicitly calling drift between them "a governance bug" - and the three were found consistent at assessment time. `hivecommons/docs` and `hivecommons.github.io` do not duplicate a `GOVERNANCE.md` of their own; they defer to the org-level document, which is a reasonable choice for support -repositories but is not stated explicitly in either repo's own README — a reader +repositories but is not stated explicitly in either repo's own README - a reader starting from one of those two repos has to infer that governance applies org-wide. @@ -445,7 +445,7 @@ No recommendation; this area is already exemplary. #### Beginner friendly issue backlog - Seed a small number (3-5) of `good first issue`-labeled documentation tasks in - `hivecommons/docs` and `hivecommons.github.io` — the [issues list][] + `hivecommons/docs` and `hivecommons.github.io` - the [issues list][] accompanying this analysis is a ready-made source for this, since documentation-improvement issues are, by nature, well suited to a newcomer-friendly backlog. @@ -505,7 +505,7 @@ For a Sandbox project, the bar is "rudimentary project documentation, or a placeholder." Hive Commons' documentation is already deep enough to clear the _Incubating_ bar in most respects (hosted directly, single-source strategy addressed as above, broad stakeholder coverage via the layered -Overview/Getting-started/Reference structure) — well beyond what Sandbox +Overview/Getting-started/Reference structure) - well beyond what Sandbox requires. #### Usability, accessibility and devices @@ -538,7 +538,7 @@ research pass; the marketing site's `sitemap.xml` lists only two URLs (`/` and as populated. An "Adopters" section is listed in `llms.txt`, which suggests the project is tracking adopters somewhere, but this has not obviously surfaced as a human-readable case-studies or testimonial page on the main site. Given this is -appropriate — and arguably expected — for a project that reached CNCF Sandbox +appropriate - and arguably expected - for a project that reached CNCF Sandbox status in the same month this assessment was requested (October 2026), this is flagged as an area to revisit at the next maturity-level review rather than an urgent gap today. @@ -550,7 +550,7 @@ sitemaps. Google Analytics (GA4) is wired into the docs site via a dedicated component with a custom-event helper; no analytics tag was found on the marketing site, whose Content-Security-Policy (`default-src 'none'` with SHA-256-pinned inline scripts) would not currently permit a third-party -analytics script to load even if one were added without a CSP update — worth +analytics script to load even if one were added without a CSP update - worth noting if analytics on the marketing site is ever desired. Both sites carry extensive Open Graph/Twitter-card meta tags and `schema.org` JSON-LD structured data for the whole project family. In-site search works via a dedicated API @@ -572,10 +572,10 @@ identified. This is a standout area. `llms.txt` exists on both domains (`hivecommons.dev/llms.txt` and `docs.hivecommons.dev/llms.txt`), each kept in sync with on-page content by dedicated, CI-enforced tests rather than hand -maintenance — directly satisfying the criterion's "stay in sync with the +maintenance - directly satisfying the criterion's "stay in sync with the published site" bar. Both sites are confirmed server-rendered/static, with substantive content present in the raw HTML payload rather than behind -client-side hydration — confirmed by a raw (non-JS) fetch of both a marketing +client-side hydration - confirmed by a raw (non-JS) fetch of both a marketing page and a docs page. `robots.txt` imposes no crawler restrictions, and no CDN bot-challenge gating was observed. The one gap: there is no per-page Markdown mirror (appending `.md` to a docs URL returns 404), so `llms.txt` is currently From 5f74330efb1d210d306d960d14645b7b2713f088 Mon Sep 17 00:00:00 2001 From: quality <280983584+hivecommons-hive[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 00:07:47 -0500 Subject: [PATCH 3/5] docs: fix MDX build by using markdown links instead of bare autolinks Bare autolinks like are parsed as invalid JSX tags by MDX, breaking the Docusaurus build. Replace them with standard markdown [text](url) links in the Hive Commons analysis docs. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: quality <280983584+hivecommons-hive[bot]@users.noreply.github.com> --- analyses/2026/hivecommons/analysis.md | 12 +++++++----- analyses/2026/hivecommons/issues.md | 4 ++-- 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/analyses/2026/hivecommons/analysis.md b/analyses/2026/hivecommons/analysis.md index 69caaf60..94138a60 100644 --- a/analyses/2026/hivecommons/analysis.md +++ b/analyses/2026/hivecommons/analysis.md @@ -85,12 +85,14 @@ GitHub Pages. - Project website: [hivecommons.dev](https://hivecommons.dev) - Documentation site: [docs.hivecommons.dev](https://docs.hivecommons.dev) -- Website/doc repository: +- Website/doc repository: + [https://github.com/hivecommons/docs](https://github.com/hivecommons/docs) - Website source repository: - (source for - hivecommons.dev) -- - `src/docs/` only (in-repo reference - docs: api-reference, design, env-vars, agent-configuration) + [https://github.com/hivecommons/hivecommons.github.io](https://github.com/hivecommons/hivecommons.github.io) + (source for hivecommons.dev) +- [https://github.com/hivecommons/hive](https://github.com/hivecommons/hive) - + `src/docs/` only (in-repo reference docs: api-reference, design, env-vars, + agent-configuration) #### Out of scope diff --git a/analyses/2026/hivecommons/issues.md b/analyses/2026/hivecommons/issues.md index 9099df39..211e52b0 100644 --- a/analyses/2026/hivecommons/issues.md +++ b/analyses/2026/hivecommons/issues.md @@ -17,10 +17,10 @@ This issue tracks recommended changes resulting from an analysis of the Hive Commons documentation requested in [cncf/techdocs#395](https://github.com/cncf/techdocs/issues/395). The analysis and supporting documents are here: -. +[https://github.com/cncf/techdocs/tree/main/analyses/2026/hivecommons](https://github.com/cncf/techdocs/tree/main/analyses/2026/hivecommons). The CNCF Tech Docs effort is tracked in the CNCF Tech Docs repo: -. +[https://github.com/cncf/techdocs/issues](https://github.com/cncf/techdocs/issues). ## Umbrella issue From b581e5a5523a998b3149d08a0bbd272b8c6c86a6 Mon Sep 17 00:00:00 2001 From: quality <280983584+hivecommons-hive[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 00:17:41 -0500 Subject: [PATCH 4/5] docs(hivecommons): fix broken self-referential link in issues.md The link to the PR's own analyses/2026/hivecommons subdirectory 404s on main until the PR merges. Point to the general analyses tree instead, following the same convention used in analyses/2026/flatcar/issues.md. Signed-off-by: quality <280983584+hivecommons-hive[bot]@users.noreply.github.com> --- analyses/2026/hivecommons/issues.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/analyses/2026/hivecommons/issues.md b/analyses/2026/hivecommons/issues.md index 211e52b0..10f3bc06 100644 --- a/analyses/2026/hivecommons/issues.md +++ b/analyses/2026/hivecommons/issues.md @@ -17,7 +17,8 @@ This issue tracks recommended changes resulting from an analysis of the Hive Commons documentation requested in [cncf/techdocs#395](https://github.com/cncf/techdocs/issues/395). The analysis and supporting documents are here: -[https://github.com/cncf/techdocs/tree/main/analyses/2026/hivecommons](https://github.com/cncf/techdocs/tree/main/analyses/2026/hivecommons). +[https://github.com/cncf/techdocs/tree/main/analyses](https://github.com/cncf/techdocs/tree/main/analyses) +under `2026/hivecommons`. The CNCF Tech Docs effort is tracked in the CNCF Tech Docs repo: [https://github.com/cncf/techdocs/issues](https://github.com/cncf/techdocs/issues). From 74d096e2c6acadcfc69396afed282930bb989853 Mon Sep 17 00:00:00 2001 From: quality <280983584+hivecommons-hive[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 13:54:13 -0500 Subject: [PATCH 5/5] Address review feedback on Hive Commons analysis - Correct byline: @clubanderson is a Hive Commons maintainer, not a CNCF TechDocs technical writer, and has not reviewed this draft yet. - Distinguish the pilot AI-assisted assessment process from CNCF membership: Hive Commons is already a CNCF Sandbox project (cncf/sandbox#545). Fix the incorrect 'same month' claim (Sandbox status: Oct 28, 2026; assessment request: Nov 12, 2026) and remove unsupported comparative superlatives. - Qualify the API reference completeness claim and note the companion OpenAPI spec. - Qualify installation step-by-step claim: the Docker Compose quickstart embeds required config changes in comments inside one command block rather than numbered steps. - Correct the localization claim: the framework is installed, but /docs URLs redirect away from locale prefixes and the docs layout hardcodes lang="en", so published documentation is English-only today. - Add hivecommons/.project/maintainers.yaml as the source of truth for maintainership, and reframe the docs CODEOWNERS/OWNERS recommendation around reconciling with the roster (@KPRoche is not a maintainer and is rejected by GitHub's CODEOWNERS validator) instead of just adding a second approver. - Correct the GA4 analytics claim: the GoogleAnalytics component is mounted only in the locale layout, not the documentation layout that renders /docs pages. - Correct Case studies & social proof: raise the rating and revise the comments to reflect the existing homepage adopters strip and populated /stories/ testimonial content; reframe the recommendation around discoverability/cross-linking. - Correct AI Agent Readiness: note that the cited CLOMonitor score targets hive.hivecommons.dev, not docs.hivecommons.dev; add verified gaps (missing llms.txt blockquote summary, HTML-not-Markdown links, no per-page Markdown mirror, and a community-link test that checks presence, not parity). - Qualify the Minimal website requirements and mark Usability, accessibility and devices as 'not assessed' rather than a provisional pass. - Scope the API-reference drift-check issue's enforcement claim to what was reviewed, separate maintainer/process issues from good-first-issue candidates, and reconcile the umbrella issue's filing destination with cncf/techdocs#395 (hivecommons/docs, not hive or .github). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: quality <280983584+hivecommons-hive[bot]@users.noreply.github.com> --- analyses/2026/hivecommons/analysis.md | 314 +++++++++++++------- analyses/2026/hivecommons/implementation.md | 26 +- analyses/2026/hivecommons/issues.md | 54 ++-- 3 files changed, 254 insertions(+), 140 deletions(-) diff --git a/analyses/2026/hivecommons/analysis.md b/analyses/2026/hivecommons/analysis.md index 94138a60..3fd81fb6 100644 --- a/analyses/2026/hivecommons/analysis.md +++ b/analyses/2026/hivecommons/analysis.md @@ -1,11 +1,11 @@ --- title: Hive Commons Documentation Analysis created: 2026-11-17 -modified: 2026-11-17 +modified: 2026-11-18 toc_max_heading_level: 4 author: - AI-assisted draft (pilot), reviewed by a CNCF TechDocs technical writer - (@clubanderson) + AI-assisted draft (pilot). Not yet reviewed by a human; (@clubanderson) is a + Hive Commons project maintainer, not a CNCF TechDocs technical writer. --- @@ -26,12 +26,14 @@ efforts. ### Pilot of the AI-assisted assessment workflow This analysis is a **pilot run** of the `cncf-techdocs-assessment` AI-assisted -assessment workflow model (see [cncf/techdocs#395][issue-395]). Hive Commons is -not yet a CNCF project under assessment in the ordinary sense; the project -volunteered to be the first end-to-end test case for the intake → accept → draft -→ verify → stakeholder review → approval loop, before the workflow is run -against CNCF member projects. Hive Commons' own maintainers are also the authors -of the workflow model being piloted (see +assessment workflow model (see [cncf/techdocs#395][issue-395]). This is a pilot +of the assessment *process*, not a question of CNCF membership: Hive Commons is +already a CNCF Sandbox project (see [cncf/sandbox#545][sandbox-545]), and the +project volunteered to be the first end-to-end test case for the intake → +accept → draft → verify → stakeholder review → approval loop, before the +workflow is run against other CNCF projects undergoing a documentation +assessment. Hive Commons' own maintainers are also the authors of the workflow +model being piloted (see `hivecommons/hive:src/docs/workflows/techdocs-assessment.md`), so this assessment doubles as dogfooding of their own tooling. @@ -197,13 +199,16 @@ which makes up the great majority of the content on `docs.hivecommons.dev`. thin: each has only 1-4 pages on the docs site, effectively stub-level next to Hive's ~100+ pages. These are out of scope for ratings here but affect the overall impression of the Hive Commons docs site as a whole. -- **Is there a complete API reference?** Yes, and unusually thorough for a - Sandbox project - 16 hand-maintained pages covering ~650 routes. The page - itself documents its own maintenance risk: "There is no generator; update this - page in the same change that adds or renames a route," and explicitly excludes - request/response schemas ("see the handler source"). This is a process gap - worth flagging (see Recommendations) even though the content that does exist - is comprehensive. +- **Is there a complete API reference?** Partially. 16 hand-maintained pages + cover ~650 routes, but the page itself frames this as a "pragmatic v1 + endpoint index," not a complete reference, and explicitly excludes + request/response schemas ("see the handler source"). A separate, machine- + generated OpenAPI spec (`dashboard/openapi.json`) is linked from the + documentation map alongside the hand-written index, so the combined + reference may cover payloads more completely than the hand-written index + alone suggests; this combination was not independently assessed for + completeness. The hand-written index's lack of a generator and drift risk + remains a process gap worth flagging (see Recommendations). - **Are there CLI references?** Partial. `hivectl.md` and `crux-cli.md` exist under "Operations," but there is no discrete, top-level "CLI reference" nav entry comparable to the API reference section. @@ -231,16 +236,20 @@ which makes up the great majority of the content on `docs.hivecommons.dev`. source (`hivecommons/hive:src/docs/getting-started.md`, titled "Zero to Automation: Getting Started with Hive"), and a direct "Install" link from the project README. -- **Is installation documented step-by-step?** Yes, with four distinct, - dedicated install paths documented in a table in the README: Docker Compose, - Podman, Kubernetes, and a hosted option. Each has its own guide +- **Is installation documented step-by-step?** Partially. Four distinct, + dedicated install paths are documented in a table in the README: Docker + Compose, Podman, Kubernetes, and a hosted option, each with its own guide (`quickstart-docker-compose.md`, `quickstart-podman.md`, - `kubernetes-deployment.md`, `hosted-hub.md`). + `kubernetes-deployment.md`, `hosted-hub.md`). However, the Docker Compose + quickstart places several required configuration changes inside comments + within one large shell command block (lines 25-53) rather than as separate + numbered steps, which does not fully meet the criteria's "numbered + step-by-step instructions" bar; a Flatcar assessment flagged the same + pattern. - **Are different types of installation documented if necessary?** Yes, Docker Compose, Podman (explicitly described as "a parallel supported choice, not an - experiment"), Kubernetes, and hosted are all first-class options, which is - more install-path coverage than most Sandbox or even Incubating projects - provide. + experiment"), Kubernetes, and hosted are all first-class options, giving + broader install-path coverage than a single-path project would have. - **Are multiple OSes documented?** Yes, the Docker Compose quickstart states explicit support for "Linux, macOS, or Windows (WSL2) host on amd64 or arm64." - **Is there guidance for what to read next?** Yes, the getting-started page @@ -256,11 +265,16 @@ which makes up the great majority of the content on `docs.hivecommons.dev`. `/api/search` route backing in-site search. The marketing site (`hivecommons.dev`) has no search, but it is a single static page, so this is appropriate for its scope. -- **Is the project planning for localization?** Already implemented, not just - planned: the docs site supports 10 locales via `next-intl` (en, hi, ja, es, - de, fr, it, Simplified Chinese, Traditional Chinese, pt), with message files - per locale and a language-switcher component. This is well beyond what most - Sandbox or Incubating projects have in place. +- **Is the project planning for localization?** A localization framework is + installed, but published documentation is not actually served in 10 + languages. The docs site uses `next-intl` with message files for 10 locales + (en, hi, ja, es, de, fr, it, Simplified Chinese, Traditional Chinese, pt) and + a language-switcher component, but a routing rule + (`src/proxy.ts`) strips locale prefixes from any `/docs` URL and redirects to + the unprefixed, English page (confirmed: visiting + `/fr/docs/hive/overview/getting-started` redirects to the English page), and + the documentation layout hardcodes `lang="en"`. Credit the infrastructure + investment, but the documentation itself is English-only today. - **Is there a documented method for versioning content?** Yes, a version registry (`src/config/versions.ts`) tracks Hive's `latest` (v5, rendered on the docs site), `v6` ("Edge," links externally to GitHub for unreleased docs), @@ -293,13 +307,20 @@ which makes up the great majority of the content on `docs.hivecommons.dev`. social convention rather than a CI-enforced check (no evidence of an automated route/doc-drift check for the API reference, unlike the docs sync drift-check which is CI-enforced). -- **Who reviews and approves documentation PRs?** Clearly documented via - `CODEOWNERS`/`OWNERS` files in each repo. `hivecommons/docs` is single-owner - (`@clubanderson`), which is a bus-factor risk worth noting. - `hivecommons.github.io` has two owners (`@clubanderson`, `@kellyaa`). -- **Does the website have a clear owner/maintainer?** Yes, documented, though - concentrated in one or two individuals for the docs/website repos specifically - (as distinct from the `hive` repo's five-person maintainer roster). +- **Who reviews and approves documentation PRs?** Documented via + `CODEOWNERS`/`OWNERS` files in each repo, but these are not fully reconciled + with `hivecommons/.project/maintainers.yaml`, the source of truth for + project ownership and maintainership (five maintainers: `@clubanderson`, + `@hanthor`, `@Danathar`, `@nicholasjackson`, `@kellyaa`). + `hivecommons/docs`'s `OWNERS` names only `@clubanderson` (a bus-factor risk), + while its `CODEOWNERS` also names `@KPRoche`, who is not on the maintainer + roster and whose entry is currently rejected by GitHub's CODEOWNERS + validator. `hivecommons.github.io` has two owners (`@clubanderson`, + `@kellyaa`), both of whom are on the roster. +- **Does the website have a clear owner/maintainer?** Documented, though + concentrated in one or two individuals for the docs/website repos + specifically, and those files need reconciling against the official + five-person maintainer roster (see above and Recommendations). #### Inclusive language @@ -332,9 +353,10 @@ clean bill across the whole corpus. #### New user content -No significant gaps identified; this area already exceeds the Sandbox and -Incubating bar. Continue the current practice of maintaining install guides per -deployment target as new ones are added. +Install-path coverage is strong, but the Docker Compose quickstart's +required configuration changes are embedded as comments inside one large +command block rather than presented as numbered steps. Revise that section to +use numbered, step-by-step instructions before treating this area as gap-free. #### Content maintainability & site mechanics @@ -350,10 +372,13 @@ deployment target as new ones are added. #### Content creation processes -- Consider adding a second owner/approver to `hivecommons/docs`'s - `CODEOWNERS`/`OWNERS` (currently `@clubanderson` alone) to reduce - single-point-of-failure risk for docs-site reviews, matching the two-owner - pattern already used in `hivecommons.github.io`. +- Reconcile `hivecommons/docs`'s `CODEOWNERS` and `OWNERS` with + `hivecommons/.project/maintainers.yaml` (the source of truth for project + ownership): either replace `@KPRoche` (not on the maintainer roster, and + currently rejected by GitHub's CODEOWNERS validator) with a maintainer from + the roster, or add `@KPRoche` to the roster if that reflects an intended + docs-review responsibility. Either way, align the files with the official + roster rather than simply adding a second approver. - Add a lightweight CI check (even a `grep`-based one) that fails if `src/docs/api-reference.md`'s stated route-count or page list has not been touched in the same PR that modifies route registrations, to make the existing @@ -474,15 +499,20 @@ No significant gaps identified. | Criterion | Rating (1-5) | | ------------------------------------------- | ------------------------------ | | Single-source for all files | 4 - Meets or exceeds standards | -| Meets min website req. (for maturity level) | 5 - Exemplary | -| Usability, accessibility, and design | 3 - Meets standards | +| Meets min website req. (for maturity level) | 3 - Meets standards (see note) | +| Usability, accessibility, and design | Not assessed | | Branding and design | 4 - Meets or exceeds standards | -| Case studies & social proof | 2 - Needs improvement | -| SEO, Analytics, and site-local search | 4 - Meets or exceeds standards | +| Case studies & social proof | 4 - Meets or exceeds standards | +| SEO, Analytics, and site-local search | 3 - Meets standards | | Maintenance planning | 4 - Meets or exceeds standards | -| AI agent readiness | 4 - Meets or exceeds standards | +| AI agent readiness | 3 - Meets standards | | HTTPS access & HTTP redirect | 5 - Exemplary | +Note: "Meets min website req." reflects a confirmed Sandbox +rudimentary-documentation bar; the licensing, community, copyright, +trademark, and branding guidelines were not independently assessed (see +Minimal website requirements comments below). + ### Comments #### Single-source requirement @@ -495,32 +525,42 @@ but the project has implemented exactly the kind of "clearly documented strategy for managing mirrored files" the criteria call for as the alternative to true single-sourcing: automated prebuild sync scripts, a 30-second fetch timeout with fail-the-build-if- unreachable semantics (so stale content is never silently -deployed), a CI drift-detection test suite, and an explicit "do not edit -`docs/content/` directly, edit the canonical source" convention stated in both -`README.md` and `CONTRIBUTING.md`. This is a materially stronger answer to the -single-source requirement than most CNCF projects provide, even though it is not -literally single-sourced. +deployed), and a CI drift-detection test suite. The project describes this +mirroring strategy explicitly in both `README.md` and `CONTRIBUTING.md` ("do +not edit `docs/content/` directly, edit the canonical source"), which is a +documented answer to the single-source requirement's alternative, even though +it is not literally single-sourced. #### Minimal website requirements -For a Sandbox project, the bar is "rudimentary project documentation, or a -placeholder." Hive Commons' documentation is already deep enough to clear the -_Incubating_ bar in most respects (hosted directly, single-source strategy -addressed as above, broad stakeholder coverage via the layered -Overview/Getting-started/Reference structure) - well beyond what Sandbox -requires. +For a Sandbox project, the project-documentation bar is "rudimentary project +documentation, or a placeholder," which Hive Commons' documentation clearly +exceeds (hosted directly, single-source strategy addressed as above, broad +stakeholder coverage via the layered Overview/Getting-started/Reference +structure). However, the Sandbox bar also requires a majority of the +[Website guidelines][website-guidelines] to be satisfied - mandatory standards +on open source status, IP licensing, corporate sponsorship, copyright and +trademark, and community standards. This pass did not independently assess +those guidelines item by item, so this criterion reflects the confirmed +documentation depth only; the licensing/community/copyright/trademark/branding +guidelines should be assessed explicitly (see Recommendations) before any +claim of Incubating-level website-requirement coverage. + +[website-guidelines]: https://github.com/cncf/techdocs/blob/main/docs/website-guidelines-checklist.md #### Usability, accessibility and devices -Not independently browser-tested as part of this pass (see Scope note in the -accompanying research). The docs site uses Tailwind CSS 4 (a -responsive-by-default utility framework); the marketing site's hand-written CSS -includes `prefers-color-scheme` media queries, suggesting attention to adaptive -rendering, but neither a live mobile-viewport check nor a formal accessibility -audit (contrast ratios, screen-reader pass, keyboard-only navigation) was -performed. Rated "meets standards" provisionally; a follow-up manual or +Not assessed. No scan was performed or supplied for this assessment, and +neither a live mobile-viewport check nor a formal accessibility audit +(contrast ratios, screen-reader pass, keyboard-only navigation) was +performed. The docs site uses Tailwind CSS 4 (a responsive-by-default utility +framework) and the marketing site's hand-written CSS includes +`prefers-color-scheme` media queries, but these indicate attention to +adaptive rendering, not confirmed keyboard usability, contrast, screen-reader +usability, or mobile navigation. This criterion should be marked "not +assessed" rather than given a provisional pass; a follow-up manual or automated (e.g. axe-core/Lighthouse) accessibility pass is recommended before -this criterion can be rated with confidence. +it can be rated with confidence. #### Branding and design @@ -533,30 +573,38 @@ third-party CDN, which is a good practice for both performance and privacy. #### Case studies and social proof -This is the weakest area found in the website assessment. No user testimonials, -logo wall of adopters, or dedicated case-studies page was identified in the -research pass; the marketing site's `sitemap.xml` lists only two URLs (`/` and -`/stories/`), and the `/stories/` page's content was not independently verified -as populated. An "Adopters" section is listed in `llms.txt`, which suggests the -project is tracking adopters somewhere, but this has not obviously surfaced as a -human-readable case-studies or testimonial page on the main site. Given this is -appropriate - and arguably expected - for a project that reached CNCF Sandbox -status in the same month this assessment was requested (October 2026), this is -flagged as an area to revisit at the next maturity-level review rather than an -urgent gap today. +This area was assessed too negatively in an earlier draft of this analysis, +which rated it "Needs improvement" without inspecting the homepage and +`/stories/` content. The [homepage](https://hivecommons.dev/) has an "Adopted +by" logo strip (KubeStellar Console, tunaos.org, Project Bluefin, Frostyard, +Open Horizon, Open Horizon Services, and an individual adopter), linking to +`ADOPTERS.md` for detail. The `/stories/` page is populated, including a +first-person contributor testimonial with supporting GitHub links. An +"Adopters" section is also listed in `llms.txt`. The main gap is +discoverability rather than absence of content: there is no dedicated, +prominently linked case-studies page distinct from `/stories/`, and the +homepage's "Adopted by" strip and the stories page are not obviously +cross-linked from the top-level navigation. Treat this as a navigation/ +cross-linking improvement rather than a content-creation gap. #### SEO, Analytics and site-local search Both `robots.txt` files are fully open to crawlers and point to generated -sitemaps. Google Analytics (GA4) is wired into the docs site via a dedicated -component with a custom-event helper; no analytics tag was found on the -marketing site, whose Content-Security-Policy (`default-src 'none'` with -SHA-256-pinned inline scripts) would not currently permit a third-party -analytics script to load even if one were added without a CSP update - worth -noting if analytics on the marketing site is ever desired. Both sites carry -extensive Open Graph/Twitter-card meta tags and `schema.org` JSON-LD structured -data for the whole project family. In-site search works via a dedicated API -route on the docs site. +sitemaps. A `GoogleAnalytics` component with a custom-event helper exists in +the docs codebase, but it is mounted only in the separate locale layout +(`src/app/[locale]/layout.tsx`), not in the documentation layout +(`src/app/docs/layout.tsx`) that actually renders `/docs` pages; a fetch of +production documentation HTML contained none of the component's +measurement-ID, `ga4-init`, or `googletagmanager` markers. GA4 should be +recorded as implemented but not currently active on documentation pages, +distinct from analytics on the rest of the docs site. No analytics tag was +found on the marketing site, whose Content-Security-Policy (`default-src +'none'` with SHA-256-pinned inline scripts) would not currently permit a +third-party analytics script to load even if one were added without a CSP +update - worth noting if analytics on the marketing site is ever desired. +Both sites carry extensive Open Graph/Twitter-card meta tags and `schema.org` +JSON-LD structured data for the whole project family. In-site search works +via a dedicated API route on the docs site. #### Maintenance planning @@ -565,25 +613,47 @@ Tailwind, Netlify) for the docs site and a deliberately minimal hand-written static site for the marketing page, each sized appropriately to its complexity. CI gates (build, link-check, markdown lint, TypeScript/lint, Vitest with coverage, DCO) and a changelog-fragment system suggest active, disciplined -maintenance. The one bus-factor risk noted above (`@clubanderson` as sole code -owner of `hivecommons/docs`) is the main maintenance-planning concern -identified. +maintenance. The code-ownership drift noted above (`hivecommons/docs`'s +`OWNERS`/`CODEOWNERS` not reconciled with the official maintainer roster) is +the main maintenance-planning concern identified. #### AI Agent Readiness -This is a standout area. `llms.txt` exists on both domains -(`hivecommons.dev/llms.txt` and `docs.hivecommons.dev/llms.txt`), each kept in -sync with on-page content by dedicated, CI-enforced tests rather than hand -maintenance - directly satisfying the criterion's "stay in sync with the -published site" bar. Both sites are confirmed server-rendered/static, with -substantive content present in the raw HTML payload rather than behind -client-side hydration - confirmed by a raw (non-JS) fetch of both a marketing -page and a docs page. `robots.txt` imposes no crawler restrictions, and no CDN -bot-challenge gating was observed. The one gap: there is no per-page Markdown -mirror (appending `.md` to a docs URL returns 404), so `llms.txt` is currently -the only machine-readable summary surface rather than a full parallel Markdown -version of every page, which the criteria call out as a distinct, additional -practice from `llms.txt` itself. +This area has real strengths but was rated too positively in an earlier draft +of this analysis, which called it "a standout area." `llms.txt` exists on both +domains (`hivecommons.dev/llms.txt` and `docs.hivecommons.dev/llms.txt`), and +the docs site's copy is kept in sync with on-page content by dedicated, +CI-enforced tests rather than hand maintenance. Both sites are confirmed +server-rendered/static, with substantive content present in the raw HTML +payload rather than behind client-side hydration - confirmed by a raw (non-JS) +fetch of both a marketing page and a docs page. `robots.txt` imposes no +crawler restrictions, and no CDN bot-challenge gating was observed. + +Several gaps go beyond "the one gap" claimed in an earlier draft: + +- The docs `llms.txt` does not include the blockquoted summary the + llmstxt.org structure (and the criteria) call for; it goes straight from the + H1 title to H2 sections. +- Its links point to HTML pages on `docs.hivecommons.dev`, not Markdown + versions of those pages. +- There is no per-page Markdown mirror: appending `.md` to a sampled + getting-started URL returned 404, confirmed directly. +- The `llms.txt` community-link test (`scripts/llms-txt-community.test.ts`) + only asserts that a fixed list of URLs is present in the file; it does not + check content parity or synchronization with the published pages those + links point to, so "kept in sync... by dedicated, CI-enforced tests" should + not be read as full content-parity verification. + +The CLOMonitor Agent-readiness score cited during review +(https://clomonitor.io/projects/cncf/hive#hive_agent_readiness) scans the +hosted Hive application (`hive.hivecommons.dev`), not the documentation site +in scope for this assessment (`docs.hivecommons.dev`); it should not be used +as evidence for this criterion. An independent `afdocs check`-style scorecard +run against `docs.hivecommons.dev` during review reported an overall score of +70/100 (C), with Content Discoverability at 59/100 (F), consistent with the +gaps above. This criterion should be rated against `docs.hivecommons.dev` +directly rather than carried over from a CLOMonitor score scoped to a +different domain. #### HTTPS access & HTTP redirect @@ -605,13 +675,17 @@ project family grows. #### Minimal website requirements -None; already well above the Sandbox bar. +- Assess the project against the full + [Website guidelines checklist][website-guidelines] (licensing, community, + copyright, trademark, branding) item by item, as the KubeVirt assessment + does, rather than inferring majority satisfaction from documentation depth + alone. #### Usability, accessibility and devices - Run an automated accessibility scan (axe-core or Lighthouse) against both sites and record the results (even informally, as a comment on the tracking - issue for this analysis) so this criterion can move from "provisional" to a + issue for this analysis) so this criterion can move from "not assessed" to a confirmed rating at the next review. #### Branding and design @@ -620,27 +694,40 @@ No recommendation; this area is strong. #### Case studies and social proof -- Populate (or link to) a case-studies/adopters page from the main site - navigation, reusing the adopter list already maintained for `llms.txt` as a - starting point, once early adopters are willing to be named publicly. +- Add a prominent, top-level navigation link (or a dedicated case-studies + page) that surfaces the existing "Adopted by" logo strip and `/stories/` + testimonial content together, since the material already exists but is not + easy to discover from the main navigation. #### SEO, Analytics and site-local search +- Mount the existing `GoogleAnalytics` component in the documentation layout + (`src/app/docs/layout.tsx`), not only the locale layout, so page views on + `/docs` pages are actually collected rather than only on non-documentation + pages. - If analytics on the marketing site is ever desired, update its CSP `script-src` allowlist (SHA-256 pin or nonce) rather than relaxing it broadly, to preserve the current strict CSP posture. #### Maintenance planning -- Add a second code owner to `hivecommons/docs` (see Content creation processes - recommendation above) to reduce single-maintainer risk. +- Reconcile `hivecommons/docs`'s code-ownership files against the maintainer + roster (see Content creation processes recommendation above) to resolve the + rejected `@KPRoche` CODEOWNERS entry and the single-owner `OWNERS` file. #### AI Agent Readiness -- Consider adding a per-page Markdown mirror (for example, serving the - underlying MDX/Markdown source at the same path with `.md` appended) for the - docs site, complementing the already-strong `llms.txt` implementation, per the - full AI Agent Readiness criterion. +- Add the llmstxt.org-required blockquoted summary to `llms.txt` on the docs + site. +- Point `llms.txt` links at Markdown versions of pages rather than HTML pages, + once a Markdown mirror exists. +- Add a per-page Markdown mirror (for example, serving the underlying + MDX/Markdown source at the same path with `.md` appended) for the docs site. +- Extend the `llms.txt` community-link test to check content parity with the + linked pages, not just URL presence. +- Re-run the CLOMonitor / `afdocs check` assessment against + `docs.hivecommons.dev` specifically, since the current CLOMonitor score is + scoped to `hive.hivecommons.dev`. #### References and notes @@ -658,4 +745,5 @@ The numeric rating values used in this document are as follows: [implementation]: ./implementation.md [issues list]: ./issues.md [issue-395]: https://github.com/cncf/techdocs/issues/395 +[sandbox-545]: https://github.com/cncf/sandbox/issues/545 [project-website]: https://hivecommons.dev diff --git a/analyses/2026/hivecommons/implementation.md b/analyses/2026/hivecommons/implementation.md index 8899521b..ec007501 100644 --- a/analyses/2026/hivecommons/implementation.md +++ b/analyses/2026/hivecommons/implementation.md @@ -45,17 +45,31 @@ restructuring program. The top-level actions are: ### Issue 1 -File the issues from the accompanying [issues list](issues.md) directly in -`hivecommons/docs` (and one in `hivecommons.github.io`), each pre-labeled -`good first issue` and `documentation`, so first-time contributors have -something to claim immediately. +File the small, self-contained documentation issues from the accompanying +[issues list](issues.md) - the CLI reference landing page and the +governance-pointer additions - directly in `hivecommons/docs` (and +`hivecommons.github.io` for the governance pointer there), each pre-labeled +`good first issue` and `documentation`, with prerequisites and completion +criteria stated per issue, so first-time contributors have something they can +claim immediately without maintainer-level context. + +Do not apply `good first issue` to the code-ownership reconciliation or the +API route/doc drift-check issues (see High-level action 2): choosing approvers +is a maintainer decision, and extracting Go routes and wiring a CI check +requires specialist context that a first-time contributor is unlikely to have. +The accessibility-scan issue (High-level action 3) can carry the label if it +states the scanning tool and a clear pass/fail recording step as its +completion criteria. ## High-level action 2: Reduce bus-factor and content-drift risk ### Issue 1 -Add a second approver/reviewer to `hivecommons/docs`'s `CODEOWNERS` and `OWNERS` -files, mirroring the two-owner pattern already used in `hivecommons.github.io`. +Reconcile `hivecommons/docs`'s `CODEOWNERS` and `OWNERS` files against +`hivecommons/.project/maintainers.yaml` (the source of truth for project +maintainership): add a roster maintainer as a second approver/reviewer, or add +the currently non-roster `@KPRoche` to the roster if they hold an intended +docs-review responsibility. ### Issue 2 diff --git a/analyses/2026/hivecommons/issues.md b/analyses/2026/hivecommons/issues.md index 10f3bc06..9c955c3a 100644 --- a/analyses/2026/hivecommons/issues.md +++ b/analyses/2026/hivecommons/issues.md @@ -25,10 +25,12 @@ The CNCF Tech Docs effort is tracked in the CNCF Tech Docs repo: ## Umbrella issue -> To be filed in `hivecommons/hive` (or the org-level `.github` repo, per -> maintainer preference) once this analysis is reviewed and accepted by project -> maintainers. Link each sub-issue below to it with a Markdown checkbox once -> filed. +> To be filed in `hivecommons/docs` (the primary implementation destination +> named in [cncf/techdocs#395][issue-395], alongside `hivecommons.github.io`) +> once this analysis is reviewed and accepted by project maintainers. Link +> each sub-issue below to it with a Markdown checkbox once filed. + +[issue-395]: https://github.com/cncf/techdocs/issues/395 ## Issues @@ -67,16 +69,22 @@ has to infer this indirectly via cross-references in `hive`'s own - [ ] `https://github.com/hivecommons/docs/issues/NNN` - [ ] `https://github.com/hivecommons/hivecommons.github.io/issues/NNN` -### Issue: Add a second code owner to hivecommons/docs +### Issue: Reconcile hivecommons/docs code ownership with the maintainer roster -Audience: Project maintainers (bus-factor/maintenance planning). +Audience: Project maintainers (bus-factor/maintenance planning, governance +accuracy). Type: Process. -`hivecommons/docs`'s `CODEOWNERS` and `OWNERS` files currently list only -`@clubanderson` as approver/reviewer, unlike `hivecommons.github.io`, which -already has two. Add a second approver to reduce single-maintainer risk for -docs-site reviews. +`hivecommons/docs`'s `OWNERS` file lists only `@clubanderson` as +approver/reviewer, while its `CODEOWNERS` also lists `@KPRoche`, who is not on +the project's maintainer roster (`hivecommons/.project/maintainers.yaml`: +`@clubanderson`, `@hanthor`, `@Danathar`, `@nicholasjackson`, `@kellyaa`) and +whose entry is currently rejected by GitHub's CODEOWNERS validator. Reconcile +these files with the official roster: either add a roster maintainer as a +second `docs` approver/reviewer, or add `@KPRoche` to the roster if they hold +an intended docs-review responsibility, so the code-ownership files and the +governance record agree. - [ ] `https://github.com/hivecommons/docs/issues/NNN` @@ -87,11 +95,14 @@ Audience: Hive maintainers and contributors adding/renaming API routes. Type: Process / Reference accuracy. `src/docs/api-reference.md` states "There is no generator; update this page in -the same change that adds or renames a route," but nothing currently enforces -this. Add a lightweight CI check (even a simple diff/grep-based script comparing -route registrations in the Go source against the documented route list in -`src/docs/api-reference/*`) that flags a PR touching routes without a -corresponding doc update. +the same change that adds or renames a route," and no automated enforcement +of that convention was found within `src/docs/` (the scope of this +assessment); this analysis did not review `hivecommons/hive`'s source or +tests outside `src/docs/`, so it cannot assert that no enforcement exists +anywhere in the repository. Add (or confirm) a lightweight CI check (even a +simple diff/grep-based script comparing route registrations in the Go source +against the documented route list in `src/docs/api-reference/*`) that flags a +PR touching routes without a corresponding doc update. Suggested changes: @@ -116,12 +127,13 @@ Audience: Project maintainers; informs a future documentation re-assessment. Type: Task. -Neither `hivecommons.dev` nor `docs.hivecommons.dev` has had a recorded, -automated accessibility scan. Run axe-core or Lighthouse against both sites and -record the results (for example, as a comment on the tracking issue for this -analysis, or a short doc under `src/docs/`), so the "Usability, accessibility -and devices" rating in [analysis.md](analysis.md) can move from provisional to -confirmed at the next review. +No scan was performed or supplied for this assessment to confirm the +"Usability, accessibility and devices" rating in [analysis.md](analysis.md) +for either `hivecommons.dev` or `docs.hivecommons.dev`. Run axe-core or +Lighthouse against both sites and record the results (for example, as a +comment on the tracking issue for this analysis, or a short doc under +`src/docs/`), so that rating can move from "not assessed" to confirmed at the +next review. - [ ] `https://github.com/hivecommons/hivecommons.github.io/issues/NNN`