Skip to main content

Hive Commons Documentation Analysis

Introduction​

This document is an analysis of the effectiveness and completeness of the Hive Commons 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). 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), 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.

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​

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:

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. Sandbox is CNCF's lightest-weight maturity level: the 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.

CriterionRating (1-5)
Information architecture4 - Meets or exceeds standards
New user content4 - Meets or exceeds standards
Content maintainability4 - Meets or exceeds standards
Content creation processes4 - Meets or exceeds standards
Inclusive language3 - 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? 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.
  • 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? 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). 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, 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 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? 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), 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? 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​

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​

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​

  • 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​

  • 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 "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​

CriterionRating (1-5)
Communication methods documented5 - Exemplary
Beginner friendly issue backlog3 - Meets standards
"New contributor" getting started content4 - Meets or exceeds standards
Project governance documentation5 - 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​

CriterionRating (1-5)
Single-source for all files4 - Meets or exceeds standards
Meets min website req. (for maturity level)3 - Meets standards (see note)
Usability, accessibility, and designNot assessed
Branding and design4 - Meets or exceeds standards
Case studies & social proof4 - Meets or exceeds standards
SEO, Analytics, and site-local search3 - Meets standards
Maintenance planning4 - Meets or exceeds standards
AI agent readiness3 - Meets standards
HTTPS access & HTTP redirect5 - 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​

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), 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 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 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.

Usability, accessibility and devices​

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 it 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 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 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.

Both robots.txt files are fully open to crawlers and point to generated 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​

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 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 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​

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​

  • Assess the project against the full Website guidelines checklist (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 "not assessed" to a confirmed rating at the next review.

Branding and design​

No recommendation; this area is strong.

Case studies and social proof​

  • 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​

  • 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​

  • 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​

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