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..3fd81fb6 --- /dev/null +++ b/analyses/2026/hivecommons/analysis.md @@ -0,0 +1,749 @@ +--- +title: Hive Commons Documentation Analysis +created: 2026-11-17 +modified: 2026-11-18 +toc_max_heading_level: 4 +author: + AI-assisted draft (pilot). Not yet reviewed by a human; (@clubanderson) is a + Hive Commons project maintainer, not a CNCF TechDocs technical writer. +--- + + + +## 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]). 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. + +### 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: + [https://github.com/hivecommons/docs](https://github.com/hivecommons/docs) +- Website source repository: + [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 + +- 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?** 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 + +| 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) | 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][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 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](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. 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][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 "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 + +[criteria]: ../../../docs/analysis/criteria.md +[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 new file mode 100644 index 00000000..ec007501 --- /dev/null +++ b/analyses/2026/hivecommons/implementation.md @@ -0,0 +1,101 @@ +--- +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 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 + +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 + +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..9c955c3a --- /dev/null +++ b/analyses/2026/hivecommons/issues.md @@ -0,0 +1,153 @@ +--- +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: +[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). + +## Umbrella issue + +> 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 + +### 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: Reconcile hivecommons/docs code ownership with the maintainer roster + +Audience: Project maintainers (bus-factor/maintenance planning, governance +accuracy). + +Type: Process. + +`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` + +### 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," 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: + +- 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. + +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` + +### 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`