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
- Project website: hivecommons.dev
- Documentation site: docs.hivecommons.dev
- Website/doc repository: https://github.com/hivecommons/docs
- Website source repository: https://github.com/hivecommons/hivecommons.github.io (source for hivecommons.dev)
- https://github.com/hivecommons/hive -
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.devlinks into them. - Source code and tests outside
hivecommons/hive'ssrc/docs/. - The org-level
hivecommons/.githubrepository, which hosts the canonicalGOVERNANCE.mdandMAINTAINERS.mdreferenced 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.
| 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? 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.mdandcrux-cli.mdexist 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,
sededit, 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/searchroute 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-intlwith 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/docsURL and redirects to the unprefixed, English page (confirmed: visiting/fr/docs/hive/overview/getting-startedredirects to the English page), and the documentation layout hardcodeslang="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'slatest(v5, rendered on the docs site),v6("Edge," links externally to GitHub for unreleased docs), andv4("Frozen," links externally). Sibling projects are pinned tomainonly (unversioned), which is reasonable given their current scope. - Is release-specific information documented in release notes? Yes, a
CHANGELOG.mdplus 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 intohivecommons/docsat build time byscripts/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 ondocs.hivecommons.devis not actually in thehivecommons/docsrepository, 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/OWNERSfiles in each repo, but these are not fully reconciled withhivecommons/.project/maintainers.yaml, the source of truth for project ownership and maintainership (five maintainers:@clubanderson,@hanthor,@Danathar,@nicholasjackson,@kellyaa).hivecommons/docs'sOWNERSnames only@clubanderson(a bus-factor risk), while itsCODEOWNERSalso names@KPRoche, who is not on the maintainer roster and whose entry is currently rejected by GitHub's CODEOWNERS validator.hivecommons.github.iohas 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.mdandcrux-cli.mdtogether, 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 inREADME.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'sCODEOWNERSandOWNERSwithhivecommons/.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@KPRocheto 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 ifsrc/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 inhivecommons/docsandhivecommons.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) tohivecommons/docsandhivecommons.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.mdandhivecommons.github.io:README.mdstating that project governance is defined at the organization level (with a link tohivecommons/.github:GOVERNANCE.md), so a reader who starts from either support repository does not have to discover this indirectly through cross-references inhive's ownGOVERNANCE.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) | 3 - Meets standards (see note) |
| Usability, accessibility, and design | Not assessed |
| Branding and design | 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 | 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
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.
SEO, Analytics and site-local search
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.txtdoes 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
.mdto a sampled getting-started URL returned 404, confirmed directly. - The
llms.txtcommunity-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
GoogleAnalyticscomponent in the documentation layout (src/app/docs/layout.tsx), not only the locale layout, so page views on/docspages are actually collected rather than only on non-documentation pages. - If analytics on the marketing site is ever desired, update its CSP
script-srcallowlist (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@KPRocheCODEOWNERS entry and the single-ownerOWNERSfile.
AI Agent Readiness
- Add the llmstxt.org-required blockquoted summary to
llms.txton the docs site. - Point
llms.txtlinks 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
.mdappended) for the docs site. - Extend the
llms.txtcommunity-link test to check content parity with the linked pages, not just URL presence. - Re-run the CLOMonitor /
afdocs checkassessment againstdocs.hivecommons.devspecifically, since the current CLOMonitor score is scoped tohive.hivecommons.dev.
References and notes
Rating values
The numeric rating values used in this document are as follows:
- Not present
- Needs improvement
- Meets standards
- Meets or exceeds standards
- Exemplary