From c58b2914aee370b392fb93f404f784c80ee4b442 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Sun, 14 Jun 2026 18:07:27 -0700 Subject: [PATCH 01/49] starting again Signed-off-by: Bruce Hamilton --- .github/workflows/format-check.yml | 3 + .github/workflows/link-check.yml | 3 + .github/workflows/spell-check.yml | 3 + .../trigger-contribute-site-netlify.yml | 2 + analyses/2026/kubevirt/analysis.md | 296 ++++++++++++++++++ 5 files changed, 307 insertions(+) create mode 100644 analyses/2026/kubevirt/analysis.md diff --git a/.github/workflows/format-check.yml b/.github/workflows/format-check.yml index 0a31794a..25a9d434 100644 --- a/.github/workflows/format-check.yml +++ b/.github/workflows/format-check.yml @@ -3,6 +3,9 @@ name: Format checks on: pull_request: +permissions: + contents: read + jobs: format-check: name: FILE FORMAT diff --git a/.github/workflows/link-check.yml b/.github/workflows/link-check.yml index bb003298..a3449c66 100644 --- a/.github/workflows/link-check.yml +++ b/.github/workflows/link-check.yml @@ -3,6 +3,9 @@ name: Link checks on: pull_request: +permissions: + contents: read + jobs: link-check: name: LINK checking diff --git a/.github/workflows/spell-check.yml b/.github/workflows/spell-check.yml index 71217d81..3a7d882a 100644 --- a/.github/workflows/spell-check.yml +++ b/.github/workflows/spell-check.yml @@ -3,6 +3,9 @@ name: Spelling checks on: pull_request: +permissions: + contents: read + jobs: spelling-check: name: SPELLING check diff --git a/.github/workflows/trigger-contribute-site-netlify.yml b/.github/workflows/trigger-contribute-site-netlify.yml index db819727..fd54d029 100644 --- a/.github/workflows/trigger-contribute-site-netlify.yml +++ b/.github/workflows/trigger-contribute-site-netlify.yml @@ -4,6 +4,8 @@ on: push: branches: [main] +permissions: {} + jobs: trigger: runs-on: ubuntu-latest diff --git a/analyses/2026/kubevirt/analysis.md b/analyses/2026/kubevirt/analysis.md new file mode 100644 index 00000000..866fd878 --- /dev/null +++ b/analyses/2026/kubevirt/analysis.md @@ -0,0 +1,296 @@ +--- +title: _PROJECT_Documentation Analysis +created: 2026-05-24 +modified: 2026-06-14 +author: iRaindrop +--- + + + +## Introduction + +This document is an analysis of the effectiveness and completeness of the open +source software (OSS) project's documentation and website. It is funded by the +Cloud Native Computing Foundation (CNCF) Foundation 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. + +### Purpose + +This document was written to analyze the current state of _PROJECT_ +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. A third +document is an \*\*issues list of issues to be added to the project +documentation repository. These issues can be taken up by contributors to +improve the documentation. + +This document: + +- Analyzes the current _PROJECT_ technical documentation and website +- Compares existing documentation against the CNCF’s standards +- Recommends a program of key improvements with the largest return on investment + +### Scope of analysis + +The documentation discussed here includes the entire contents of the website, +the technical documentation, and documentation for contributors and users on the +_PROJECT_ GitHub repository. + +The _PROJECT_ website and documentation are written in Markdown and are compiled +using the [Hugo, Docusaurus, Sphinx, other] static site generator with the +[Docsy, other] theme and served from [the Netlify platform, other]. The site's +code is stored on the _PROJECT_ GitHub repo. + +#### In scope + + + +#### Out of scope + +- Other _PROJECT_ GitHub repositories besides `user-guide`. + +### How this document is organized + +This document is divided into two sections that represent two major areas of +concern: + +- **Project documentation:** concerns documentation for users of the _PROJECT_ + software, aimed at people who intend to use the project software. +- **Contributor documentation:** concerns documentation for new and existing + contributors to the _PROJECT_ OSS project. + +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, with a focus on + how it does or does not help _PROJECT_ users achieve their goals. +- **Recommendations**: suggested changes that would improve the effectiveness of + the documentation. + +The accompanying **implementation** document breaks the recommendations down +into concrete actions that can be implemented by project contributors. Its focus +is on drilling down to specific, achievable work that can be completed in +constrained blocks of time. Ultimately, the implementation items are decomposed +into a series of issues and entered on GitHub. + +(provide link) + +### 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) + +Examples of CNCF documentation that demonstrate the analysis criteria are linked +from the [criteria] specification. + +#### 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, the +recommended implementations represent the reviewers' experience with how to +apply documentation best practices. In other words, borrowing terminology from +the lexicon of RFCs, 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 + +_PROJECT_ is an **incubating** project of CNCF. This means that the project +should be developing professional-quality documentation alongside the project +code. + +| Criterion | [Rating (1-5)] | +| -------------------------- | -------------- | +| Information architecture | [rating (1-5)] | +| New user content | [rating (1-5)] | +| Content maintainability | [rating (1-5)] | +| Content creation processes | [rating (1-5)] | +| Inclusive language | [rating (1-5)] | + +### Comments + +The following sections contain brief assessments of each element of the Project +Documentation rubric. + +#### Information architecture + +The overall structure (pages/subpages/sections/subsections) of your project +documentation. We evaluate on the following: + +- Is there high level conceptual/“About” content? Is the documentation feature + complete? (i.e., each product feature is documented) +- Are there step-by-step instructions (tasks, tutorials) documented for + features? +- Are there any key features which are documented but missing task + documentation? +- Is the “happy path”/most common use case documented? Does task and tutorial + content demonstrate atomicity and isolation of concerns? (Are tasks clearly + named according to user goals?) +- If the documentation does not suffice, is there a clear escalation path for + users needing more help? (FAQ, Troubleshooting) +- If the product exposes an API, is there a complete reference? +- Is content up to date and accurate? + +#### New user content + +New users are the most avid users of documentation, and need content +specifically for them. We evaluate on the following: + +- Is “getting started” clearly labeled? (“Getting started”, “Installation”, + “First steps”, etc.) +- Is installation documented step-by-step? +- If needed, are multiple OSes documented? +- Do users know where to go after reading the getting started guide? +- Is your new user content clearly signposted on your site’s homepage or at the + top of your information architecture? +- Is there sample code or other example content that can easily be copy-pasted? + +#### Content maintainability & site mechanics + +As a project scales, concerns like localized (translated) content and versioning +become large maintenance burdens, particularly if you don’t plan for them. + +We evaluate on the following: + +- Is your documentation searchable? +- Are you planning for localization/internationalization with regards to site + directory structure? Is a localization framework present? +- Do you have a clearly documented method for versioning your content? + +#### Content creation processes + +Documentation is only as useful as it is accurate and well-maintained, and +requires the same kind of review and approval processes as code. + +We evaluate on the following: + +- Is there a clearly documented (ongoing) contribution process for + documentation? +- Does your code release process account for documentation creation & updates? +- Who reviews and approves documentation pull requests? +- Does the website have a clear owner/maintainer? + +#### Inclusive language + +Creating inclusive project communities is a key goal for all CNCF projects. + +We evaluate on the following: + +- Are there any customer-facing utilities, endpoints, class names, or feature + names that use non-recommended words as documented by the + [Inclusive Naming Initiative](https://inclusivenaming.org) website? +- Does the project use language like "simple", "easy", etc.? + +### Recommendations + +> AUTHOR NOTE: Write general recommendations based on the comments from the +> previous section. + +#### Information architecture + +#### New user content + +#### Content maintainability & site mechanics + +#### Content creation processes + +#### Inclusive language + +## Contributor documentation + +_PROJECT_ is an **incubating** project of CNCF. This means that the project +should be developing professional-quality documentation alongside the project +code. + +| Criterion | [Rating (1-5)] | +| ----------------------------------------- | -------------- | +| Communication methods documented | [rating (1-5)] | +| Beginner friendly issue backlog | [rating (1-5)] | +| “New contributor” getting started content | [rating (1-5)] | +| Project governance documentation | [rating (1-5)] | + +### Comments + +The _PROJECT_ documentation provides a well-organized documentation set that can +accommodate recommended improvements without a major restructure. + +The following sections contain brief assessments of each element of the +Contributor Documentation rubric. + +> AUTHOR NOTE: For each heading below, discuss how well the in-scope items meet +> these criteria. Keep in mind that much of the contributor documentation might +> be contained in the documentation repository. + +#### Communication methods documented + +One of the easiest ways to attract new contributors is making sure they know how +to reach you. + +We evaluate on the following: + +- Is there a Slack/Discord/Discourse/etc. community and is it prominently linked + from your website? +- Is there a direct link to your GitHub organization/repository? +- Are weekly/monthly project meetings documented? Is it clear how someone can + join those meetings? +- Are mailing lists documented? + +#### Beginner friendly issue backlog + +We evaluate on the following: + +- Are docs issues well-triaged? +- Is there a clearly marked way for new contributors to make code or + documentation contributions (i.e. a “good first issue” label)? +- Are issues well-documented (i.e., more than just a title)? +- Are issues maintained for staleness? + +#### New contributor getting started content + +Open source is complex and projects have many processes to manage that. Are +processes easy to understand and written down so that new contributors can jump +in easily? + +We evaluate on the following: + +- Do you have a community repository or section on your website? +- Is there a document specifically for new contributors/your first contribution? +- Do new users know where to get help? + +#### Project governance documentation + +One of the CNCF’s core project values is open governance. + +We evaluate on the following: + +- Is project governance clearly documented? + +### Recommendations + +> AUTHOR NOTE: Write general recommendations based on the comments from the +> previous section. + +#### Communication methods documented + +#### Beginner friendly issue backlog + +#### New contributor getting started content + +#### Project governance documentation From e7f99fd15432592e74c92456159bac87e3c9bfdb Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Sun, 14 Jun 2026 18:39:35 -0700 Subject: [PATCH 02/49] KubeVirt spell test Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/analysis.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/analyses/2026/kubevirt/analysis.md b/analyses/2026/kubevirt/analysis.md index 866fd878..bfdd8aa0 100644 --- a/analyses/2026/kubevirt/analysis.md +++ b/analyses/2026/kubevirt/analysis.md @@ -22,7 +22,7 @@ efforts. ### Purpose -This document was written to analyze the current state of _PROJECT_ +This document was written to analyze the current state of KubeVirt 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. A third From 74538ad010a0444c9613693850b9d4e38d186791 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Sun, 14 Jun 2026 18:47:06 -0700 Subject: [PATCH 03/49] KubeVirt test w/cspell local changed Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/analysis.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/analyses/2026/kubevirt/analysis.md b/analyses/2026/kubevirt/analysis.md index bfdd8aa0..c78f6e79 100644 --- a/analyses/2026/kubevirt/analysis.md +++ b/analyses/2026/kubevirt/analysis.md @@ -1,7 +1,7 @@ --- title: _PROJECT_Documentation Analysis created: 2026-05-24 -modified: 2026-06-14 +modified: 2026-06-15 author: iRaindrop --- From 84fdb9775324e23d35ba36897f1759e8e90a79f7 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Sun, 14 Jun 2026 18:55:39 -0700 Subject: [PATCH 04/49] removed KubeVirt word Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/analysis.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/analyses/2026/kubevirt/analysis.md b/analyses/2026/kubevirt/analysis.md index c78f6e79..7d272c69 100644 --- a/analyses/2026/kubevirt/analysis.md +++ b/analyses/2026/kubevirt/analysis.md @@ -22,11 +22,11 @@ efforts. ### Purpose -This document was written to analyze the current state of KubeVirt +This document was written to analyze the current state of _PROJECT_ 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. A third -document is an \*\*issues list of issues to be added to the project +document is an **issues** list of issues to be added to the project documentation repository. These issues can be taken up by contributors to improve the documentation. From 78d94241888096028899359c43d24d89fffd8485 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Mon, 15 Jun 2026 09:59:20 -0700 Subject: [PATCH 05/49] added KubeVirt to Cspell Signed-off-by: Bruce Hamilton --- .cspell.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.cspell.yml b/.cspell.yml index bf753dbd..9118c88d 100644 --- a/.cspell.yml +++ b/.cspell.yml @@ -45,3 +45,5 @@ words: - Uchechukwu - webdev - Welsch + - KubeVirt + From bd3907d5aded33ae42f35e2759280488bb30e1c2 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Mon, 15 Jun 2026 10:08:18 -0700 Subject: [PATCH 06/49] Ran prettier on cspell Signed-off-by: Bruce Hamilton --- .cspell.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/.cspell.yml b/.cspell.yml index 9118c88d..6eb6639e 100644 --- a/.cspell.yml +++ b/.cspell.yml @@ -46,4 +46,3 @@ words: - webdev - Welsch - KubeVirt - From e99879da8f3b3c120c1729376c220cbe9a7240ce Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Mon, 15 Jun 2026 10:15:55 -0700 Subject: [PATCH 07/49] KubeVirt spell confrim Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/analysis.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/analyses/2026/kubevirt/analysis.md b/analyses/2026/kubevirt/analysis.md index 7d272c69..20fee2b7 100644 --- a/analyses/2026/kubevirt/analysis.md +++ b/analyses/2026/kubevirt/analysis.md @@ -1,5 +1,5 @@ --- -title: _PROJECT_Documentation Analysis +title: KubeVirtDocumentation Analysis created: 2026-05-24 modified: 2026-06-15 author: iRaindrop @@ -22,7 +22,7 @@ efforts. ### Purpose -This document was written to analyze the current state of _PROJECT_ +This document was written to analyze the current state of KubeVirt's 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. A third From 074bf8501e2985c9f510861c69ef3ed763e92153 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 17 Jun 2026 20:06:05 -0700 Subject: [PATCH 08/49] started comments for the proj documentation Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/analysis.md | 46 ++++++++++++++++++++++++++++-- 1 file changed, 44 insertions(+), 2 deletions(-) diff --git a/analyses/2026/kubevirt/analysis.md b/analyses/2026/kubevirt/analysis.md index 20fee2b7..dbcdaea2 100644 --- a/analyses/2026/kubevirt/analysis.md +++ b/analyses/2026/kubevirt/analysis.md @@ -1,8 +1,8 @@ --- title: KubeVirtDocumentation Analysis created: 2026-05-24 -modified: 2026-06-15 -author: iRaindrop +modified: 2026-06-17 +author: Bruce Hamilton (GitHUb: iraindrop) --- @@ -129,6 +129,48 @@ code. The following sections contain brief assessments of each element of the Project Documentation rubric. +The following observations are my initial observations on the KubeVirt +documentation (https://kubevirt.io/user-guide). + +Docs welcome page: + +- From the home page, selecting **Docs** from the top navigation tabs opens the + **KubeVirt User Guide** page - with the main sections of the documentation as + options on the top navigation tabs. This differs from having the navigation + tabs the choices of all of the web site. This is unusual, but not a negative + experience. +- Selecting the KubeVirt icon on the upper-left should return to home page but + stays on the same page. To return to the home page, you must use the browser. +- On the Welcome page, the bulleted list of selection descriptions needed + consistent editing would read better as a two-column table (table head not + needed). +- The **Try it out** heading should include "QuickStarts" (besides the URL) so + that the reader doesn't wonder if its something different. + +Architecture: + +This page describes essentials and core concepts as expected for an Architecture +page but could be organized better to coordinate with the graphics. The +Application Layout subsection would be better closer to the top. + +The diagram labeled "simplified version" would be better with its own +description. + +The How to and When to use a virtual machine sections would be better placed in +getting started or as administration tasks. + +QuickStarts: + +The Labs, which are used in conjunction with the QuickStarts, are not shown +until select a QuickStart (other than Killercoda). Labs should in the navigation +bar. + +Creating a VM for KubeVirt would be an obvious paramount QuickStart. But there +are currently two topics to do this. The user starts with either start with +"KubeVirt QuickStart with Kind" or "KubeVirt QuickStart with Minikube", followed +by "Use KubeVirt" to create the VM. Perhaps the could be one main topic with +references to Kind and MiniKube. Such thoughts may have been considered before. + #### Information architecture The overall structure (pages/subpages/sections/subsections) of your project From abdbf8dad869db130e834e488861cd0507520782 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 17 Jun 2026 20:19:14 -0700 Subject: [PATCH 09/49] format fixes Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/analysis.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/analyses/2026/kubevirt/analysis.md b/analyses/2026/kubevirt/analysis.md index dbcdaea2..22912103 100644 --- a/analyses/2026/kubevirt/analysis.md +++ b/analyses/2026/kubevirt/analysis.md @@ -2,7 +2,7 @@ title: KubeVirtDocumentation Analysis created: 2026-05-24 modified: 2026-06-17 -author: Bruce Hamilton (GitHUb: iraindrop) +author: Bruce Hamilton --- @@ -162,8 +162,7 @@ getting started or as administration tasks. QuickStarts: The Labs, which are used in conjunction with the QuickStarts, are not shown -until select a QuickStart (other than Killercoda). Labs should in the navigation -bar. +until select a QuickStart. Labs should in the navigation bar. Creating a VM for KubeVirt would be an obvious paramount QuickStart. But there are currently two topics to do this. The user starts with either start with From d8db9064f7118523fbcf6743d4e528f0454cf186 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Fri, 19 Jun 2026 19:56:10 -0700 Subject: [PATCH 10/49] Added contributor and website sections - AI analysis Signed-off-by: Bruce Hamilton --- .cspell.yml | 6 + analyses/2026/kubevirt/analysis.md | 629 +++++++++++++++++++++++++++-- 2 files changed, 596 insertions(+), 39 deletions(-) diff --git a/.cspell.yml b/.cspell.yml index 6eb6639e..f4798273 100644 --- a/.cspell.yml +++ b/.cspell.yml @@ -46,3 +46,9 @@ words: - webdev - Welsch - KubeVirt + - kubevirt + - Quickstart + - Quickstarts + - Killercoda + - Tekton + \ No newline at end of file diff --git a/analyses/2026/kubevirt/analysis.md b/analyses/2026/kubevirt/analysis.md index 22912103..66c3227c 100644 --- a/analyses/2026/kubevirt/analysis.md +++ b/analyses/2026/kubevirt/analysis.md @@ -1,7 +1,7 @@ --- title: KubeVirtDocumentation Analysis created: 2026-05-24 -modified: 2026-06-17 +modified: 2026-06-19 author: Bruce Hamilton --- @@ -32,7 +32,7 @@ improve the documentation. This document: -- Analyzes the current _PROJECT_ technical documentation and website +- Analyzes the current KubeVirt technical documentation and website - Compares existing documentation against the CNCF’s standards - Recommends a program of key improvements with the largest return on investment @@ -40,38 +40,38 @@ This document: The documentation discussed here includes the entire contents of the website, the technical documentation, and documentation for contributors and users on the -_PROJECT_ GitHub repository. +KubeVirt GitHub repository. -The _PROJECT_ website and documentation are written in Markdown and are compiled +The KubeVirt website and documentation are written in Markdown and are compiled using the [Hugo, Docusaurus, Sphinx, other] static site generator with the [Docsy, other] theme and served from [the Netlify platform, other]. The site's -code is stored on the _PROJECT_ GitHub repo. +code is stored on the KubeVirt GitHub repo. #### In scope - + #### Out of scope -- Other _PROJECT_ GitHub repositories besides `user-guide`. +- Other KubeVirt GitHub repositories besides `user-guide`. ### How this document is organized This document is divided into two sections that represent two major areas of concern: -- **Project documentation:** concerns documentation for users of the _PROJECT_ +- **Project documentation:** concerns documentation for users of the KubeVirt software, aimed at people who intend to use the project software. - **Contributor documentation:** concerns documentation for new and existing - contributors to the _PROJECT_ OSS project. + contributors to the KubeVirt OSS project. 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, with a focus on - how it does or does not help _PROJECT_ users achieve their goals. + how it does or does not help KubeVirt users achieve their goals. - **Recommendations**: suggested changes that would improve the effectiveness of the documentation. @@ -112,7 +112,7 @@ to legal requirements such as copyright and licensing issues. ## Project documentation -_PROJECT_ is an **incubating** project of CNCF. This means that the project +KubeVirt is an **incubating** project of CNCF. This means that the project should be developing professional-quality documentation alongside the project code. @@ -130,7 +130,8 @@ The following sections contain brief assessments of each element of the Project Documentation rubric. The following observations are my initial observations on the KubeVirt -documentation (https://kubevirt.io/user-guide). +documentation (https://kubevirt.io/user-guide) by its sections as shown on the +top navigation bar. Docs welcome page: @@ -149,26 +150,36 @@ Docs welcome page: Architecture: -This page describes essentials and core concepts as expected for an Architecture -page but could be organized better to coordinate with the graphics. The -Application Layout subsection would be better closer to the top. +- This page describes essentials and core concepts as expected for an + Architecture page but could be organized better to coordinate with the + graphics. The Application Layout subsection would be better closer to the top. -The diagram labeled "simplified version" would be better with its own -description. +- The diagram labeled "simplified version" would be better with its own + description. -The How to and When to use a virtual machine sections would be better placed in -getting started or as administration tasks. +- The How to and When to use a virtual machine sections would be better placed + in getting started or as administration tasks. QuickStarts: -The Labs, which are used in conjunction with the QuickStarts, are not shown -until select a QuickStart. Labs should in the navigation bar. +- The Labs, which are used in conjunction with the Quickstarts, are not shown + until select a QuickStart. Labs should in the navigation bar. -Creating a VM for KubeVirt would be an obvious paramount QuickStart. But there -are currently two topics to do this. The user starts with either start with -"KubeVirt QuickStart with Kind" or "KubeVirt QuickStart with Minikube", followed -by "Use KubeVirt" to create the VM. Perhaps the could be one main topic with -references to Kind and MiniKube. Such thoughts may have been considered before. +- Creating a VM for KubeVirt would be an obvious paramount QuickStart. But there + are currently two topics to do this. The user starts with either start with + "KubeVirt QuickStart with Kind" or "KubeVirt QuickStart with Minikube", + followed by "Use KubeVirt" to create the VM. Perhaps the could be one main + topic with references to Kind and MiniKube. Such thoughts may have been + considered before. + +Cluster Administration: + +- The top (first) page in the section, Installation, has guidance what would be + helpful in getting started content. +- A majority topics are reference and also how-to's. +- The "Confidential computing" topic might be better titled as "Encrypted + Virtualization". +- The "KubeVirt Tekton" topic might be better titled as "Tekton pipelines." #### Information architecture @@ -256,20 +267,23 @@ We evaluate on the following: ## Contributor documentation -_PROJECT_ is an **incubating** project of CNCF. This means that the project +The analysis in this section was generated by AI, Claude Sonnet 4.6, and +comprises the answers to questions, findings, and rating evaluations. + +KubeVirt is an **incubating** project of CNCF. This means that the project should be developing professional-quality documentation alongside the project code. -| Criterion | [Rating (1-5)] | -| ----------------------------------------- | -------------- | -| Communication methods documented | [rating (1-5)] | -| Beginner friendly issue backlog | [rating (1-5)] | -| “New contributor” getting started content | [rating (1-5)] | -| Project governance documentation | [rating (1-5)] | +| Criterion | Rating (1-5) | +| ----------------------------------------- | ------------ | +| Communication methods documented | 5 | +| Beginner friendly issue backlog | 4 | +| "New contributor" getting started content | 4 | +| Project governance documentation | 5 | ### Comments -The _PROJECT_ documentation provides a well-organized documentation set that can +The KubeVirt documentation provides a well-organized documentation set that can accommodate recommended improvements without a major restructure. The following sections contain brief assessments of each element of the @@ -288,21 +302,78 @@ We evaluate on the following: - Is there a Slack/Discord/Discourse/etc. community and is it prominently linked from your website? + + **Answer:** Partially. Slack is mentioned in the + [Contributing](https://kubevirt.io/user-guide/contributing/) page of the user + guide ("Visit the KubeVirt community page, participate on Slack"), but it is + not prominently linked from the user-guide homepage or navigation. The + `#virtualization` and `#kubevirt-dev` Slack channels are listed in the + [sig-list](https://github.com/kubevirt/community/blob/main/sig-list.md) in the + community repo. The kubevirt.io/community/ page did not render meaningful + content during testing. Slack presence is documented but not prominently + surfaced from the main site. + - Is there a direct link to your GitHub organization/repository? + + **Answer:** Yes. The Contributing page links directly to the + [KubeVirt GitHub organization](https://github.com/kubevirt) and to specific + repos (user-guide, kubevirt.github.io, community, kubevirt/kubevirt). Every + page also has an "Edit this page" link pointing to the GitHub source. + - Are weekly/monthly project meetings documented? Is it clear how someone can join those meetings? + + **Answer:** Yes. The + [sig-list.md](https://github.com/kubevirt/community/blob/main/sig-list.md) in + the community repo documents a weekly community meeting (Wednesdays 15:00 UTC + via Zoom) and multiple SIG meetings (control-plane, compute, storage, + observability, CI, etc.), each with Zoom links. The Contributing page links to + community resources where these are found. The meeting times, cadences, and + Zoom links are clear. + - Are mailing lists documented? + **Answer:** Yes. The + [kubevirt-dev mailing list](https://groups.google.com/forum/#!forum/kubevirt-dev) + is documented in the sig-list and referenced in the GOVERNANCE.md. A private + [cncf-kubevirt-maintainers](mailto:cncf-kubevirt-maintainers@lists.cncf.io) + list is also documented. These are in the community repo, which is linked from + the user-guide Contributing page. + #### Beginner friendly issue backlog We evaluate on the following: - Are docs issues well-triaged? + + **Answer:** Partially. The user-guide repo has very few open issues (only 2 as + of evaluation), with minimal label usage — one is labeled `kind/enhancement` + and one has no labels. Closed issues show some use of lifecycle labels + (`lifecycle/stale`, `lifecycle/rotten`) indicating a staleness bot is in use, + but active triage with descriptive labels appears limited. + - Is there a clearly marked way for new contributors to make code or - documentation contributions (i.e. a “good first issue” label)? + documentation contributions (i.e. a "good first issue" label)? + + **Answer:** Partially. The `good-first-issue` label exists and has been used + (e.g., issue 925 in user-guide, and actively in kubevirt/kubevirt). The + Contributing page explicitly directs new contributors to look for this label. + However, there are currently no open `good-first-issue` issues in the + user-guide repo, making the pathway harder to act on in practice. + - Are issues well-documented (i.e., more than just a title)? + + **Answer:** Mixed. The open issues visible (e.g., "Proposal: Add Simplified + Chinese (zh-CN) Documentation", "Improve the getting started guides of + KubeVirt") appear to have descriptive titles and likely more body content, but + the overall issue count is very small, making it hard to assess a pattern. + - Are issues maintained for staleness? + **Answer:** Yes. Lifecycle labels (`lifecycle/stale`, `lifecycle/rotten`, + `lifecycle/frozen`) are applied to issues over time, indicating an automated + staleness bot (likely prow/tide) is active in the project's repos. + #### New contributor getting started content Open source is complex and projects have many processes to manage that. Are @@ -312,9 +383,31 @@ in easily? We evaluate on the following: - Do you have a community repository or section on your website? + + **Answer:** Yes. There is a dedicated + [kubevirt/community](https://github.com/kubevirt/community) GitHub repository + containing governance docs, SIG charters, membership policy, and the sig-list. + The user-guide Contributing page links to it. The kubevirt.io website also has + a `/community/` page, though it did not render substantive content during + evaluation. + - Is there a document specifically for new contributors/your first contribution? + + **Answer:** Yes. The user-guide has a dedicated + [Contributing](https://kubevirt.io/user-guide/contributing/) page with a "Your + first contribution" section that lists suggested repos, explains the + `good-first-issue` label, links to a + [New Contributor session recording](https://www.youtube.com/playlist?list=PLnLpXX8KHIYw1nDm8BLpg1SyETGcH93yl), + and describes other ways to get started. Prerequisites (Git, GitHub workflow, + labs) are also clearly listed. + - Do new users know where to get help? + **Answer:** Yes. The user-guide homepage has an explicit "Getting help" + section. The Contributing page directs users to the community page, Slack, and + GitHub issues. The community repo README also lists communication channels. + Help pathways are documented across multiple locations. + #### Project governance documentation One of the CNCF’s core project values is open governance. @@ -330,8 +423,466 @@ We evaluate on the following: #### Communication methods documented +KubeVirt documents its communication channels thoroughly in the community repo +and CONTRIBUTING.md, but discoverability from the main website and the +`kubevirt/kubevirt` README could be improved. The `kubevirt.io/community/` page +did not render meaningful content during evaluation, which is a missed +opportunity for new visitors. + +**Recommendations:** + +- Add a visible "Community" section to the `kubevirt/kubevirt` README (or expand + the existing one) that lists Slack channels with direct join links, the + mailing list address, and a link to the weekly meeting schedule — mirroring + the detail already in `kubevirt/community/README.md`. +- Fix or replace the `kubevirt.io/community/` page so it renders usable content: + Slack links, meeting schedule, mailing list, and SIG overview. +- Promote the `#virtualization` and `#kubevirt-dev` Slack channel links more + prominently on the user-guide Contributing page (currently only mentioned in + passing with no direct join URL). + #### Beginner friendly issue backlog -#### New contributor getting started content +The `good-first-issue` label infrastructure exists and is referenced in the +Contributing page, but the user-guide repo has very few open issues overall and +no open `good-first-issue` issues at the time of evaluation. Without an +actionable backlog, new contributors who follow the guidance reach a dead end. + +## Website and infrastructure + +The analysis in this section was generated by AI, Claude Sonnet 4.6, and +comprises the answers to questions, findings, and rating evaluations. + +KubeVirt is an **incubating** project of CNCF. This means that the project +should be [_developing_][criteria] professional-quality documentation alongside +the project code. + +| Criterion | Rating (1-5) | +| ------------------------------------------- | ------------ | +| Single-source for all files | 2 | +| Meets min website req. (for maturity level) | 3 | +| Usability, accessibility, and design | 3 | +| Branding and design | 4 | +| Case studies/social proof | 3 | +| SEO, Analytics, and site-local search | 2 | +| Maintenance planning | 3 | +| A11y plan & implementation | 2 | +| Mobile-first plan & impl. | 3 | +| HTTPS access & HTTP redirect | 5 | +| Google Analytics 4 for production only | 1 | +| Indexing allowed for production server only | 2 | +| Intra-site / local search | 4 | +| Account custodians are documented | 1 | -#### Project governance documentation +### Comments + +The following sections contain brief assessments of each element of the Website +and documentation infrastructure rubric. + +The KubeVirt user guide is a well-structured, professional documentation site +built with MkDocs Material, hosted on GitHub Pages at `kubevirt.io/user-guide/`. +The site is responsive, visually clean, and covers a comprehensive breadth of +topics. The primary infrastructure gaps are the absence of analytics on the +user-guide site, no documented a11y plan, no explicit account custodians, and +the split between two separate repos for the overall kubevirt.io web presence +(the main site uses Jekyll/kubevirt.github.io; docs use MkDocs/user-guide). +These are addressable gaps for an incubating project moving toward graduation. + +#### Single-source requirement + +Source files for _all website pages_ should reside in a single repo. Among other +problems, keeping source files in two places: + +- confuses contributors +- requires you to keep two sources in sync +- increases the likelihood of errors +- makes it more complicated to generate the documentation from source files + +Ideally, all website files should be in the **website repo** itself. +Alternatively, files should be brought into the website repo via [git +submodules][git-submodules]. + +If a project chooses to keep source files in multiple repos, they need a clearly +documented strategy for managing mirrored files and new contributions. + +**Finding:** The user-guide documentation source files all reside in a single +repo ([kubevirt/user-guide](https://github.com/kubevirt/user-guide)) under the +`./docs/` directory — this is good. However, the overall kubevirt.io web +presence is split across two repos with different technology stacks: +[kubevirt/kubevirt.github.io](https://github.com/kubevirt/kubevirt.github.io) +(Jekyll, main website) and kubevirt/user-guide (MkDocs, documentation). The user +guide is deployed as a subdirectory (`/user-guide/`) of the main site. These two +repos require separate contribution workflows, separate tooling, and separate CI +pipelines, which is a coordination overhead and potential source of confusion. +Within the user-guide repo itself, source is properly single-sourced. + +**Rating: 2** — The split between two repos and two static site generators for +the combined web presence needs improvement. + +#### Minimal website requirements + +Listed here are the minimal website requirements for projects based on their +[maturity level][maturity-level], either incubating or graduated. (These are the +only two levels for which a tech docs analysis can be requested.) + + + +| Criterion | Incubating Requirement | Graduated Requirement | +| ----------------------------- | ------------------------------------------------------- | ----------------------------------------- | +| [Website guidelines] | All guidelines satisfied | All guidelines satisfied | +| **Docs analysis** (this) | Requested through CNCF [service desk][cncf-servicedesk] | All follow-up actions addressed | +| **Project doc**: stakeholders | Roles identified and doc needs documented | All stakeholder need identified | +| **Project doc**: hosting | Hosted directly | Hosted directly | +| **Project doc**: user docs | Comprehensive, addressing most stakeholder needs | Fully addresses needs of key stakeholders | + + + +[git-submodules]: https://git-scm.com/book/en/v2/Git-Tools-Submodules +[maturity-level]: + https://github.com/cncf/toc/tree/main/process#ii-stages---definitions--expectations +[cncf-servicedesk]: https://servicedesk.cncf.io + +**Finding:** The user guide is hosted directly on GitHub Pages at +`kubevirt.io/user-guide/` ✅. This docs analysis has been requested ✅. User +docs are comprehensive, covering architecture, installation, cluster +administration, user workloads, compute, networking, storage, debugging, and +release notes — this addresses most stakeholder needs ✅. Stakeholder roles +(cluster admins, users, developers) are implicitly addressed by the site's +navigation structure, though not explicitly documented as personas. CNCF website +guideline compliance has not been fully verified as part of this analysis. + +**Rating: 3** — Meets incubating requirements on hosting, docs breadth, and +having this analysis, with minor gaps in explicit stakeholder documentation. + +#### Usability, accessibility and devices + +Most CNCF websites are accessed from mobile and other non-desktop devices at +least 10-20% of the time. Planning for this early in your website's design will +be much less effort than retrofitting a desktop-first design. + +- Is the website usable from mobile? + + **Answer:** Yes. MkDocs Material renders a responsive layout on mobile with a + hamburger menu, collapsible navigation, and readable typography. + +- Are doc pages readable? + + **Answer:** Yes. Pages use clean typography, good heading hierarchy, and + syntax-highlighted code blocks. + +- Are all / most website features accessible from mobile -- such as the top-nav, + site search and in-page table of contents? + + **Answer:** Yes. The Material theme's mobile rendering includes the search + input, collapsible nav, and in-page TOC, all accessible from mobile. + +- Might a [mobile-first] design make sense for your project? + + **Answer:** Given that KubeVirt targets infrastructure/DevOps engineers who + typically work at desktops, mobile-first is less critical, but the current + responsive design is adequate. + +[mobile-first]: + https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Responsive/Mobile_first + +Plan for suitable [accessibility][] measures for your website. For example: + +- Are color contrasts significant enough for color-impaired readers? + + **Answer:** The teal primary color on a white/dark background generally + provides sufficient contrast, though no formal contrast audit has been + documented. + +- Are most website features usable using a keyboard only? + + **Answer:** MkDocs Material provides standard keyboard navigation support + (tab, enter, arrow keys for search results), though no explicit keyboard-only + audit is documented. + +- Does text-to-speech offer listeners a good experience? + + **Answer:** The Material theme includes ARIA labels for navigation elements + and search, providing a reasonable screen reader experience, though it has not + been explicitly tested. + +It is up to each project to set their own guidelines. No explicit a11y +guidelines or audit are documented for this project. + +[accessibility]: https://developer.mozilla.org/en-US/docs/Web/Accessibility + +**Rating: 3** — The Material theme provides good usability and mobile support by +default; no formal a11y plan or audit is present. + +#### Branding and design + +CNCF seeks to support enterprise-ready open source software. A key aspect of +this is branding and marketing. + +We evaluate on the following: + +- Is there an easily recognizable brand for the project (logo + color scheme) + clearly identifiable? + + **Answer:** Yes. The KubeVirt logo (cube icon) and teal color scheme are + consistently applied across the user guide and main website. + +- Is the brand used across the website consistently? + + **Answer:** Yes. The MkDocs Material theme is configured with the KubeVirt + icon, teal primary/accent colors, and a custom favicon. The branding is + consistent throughout all pages. + +- Is the website's typography clean and well-suited for reading? + + **Answer:** Yes. Material Design's Roboto typeface provides clean, legible + typography with appropriate heading hierarchy and code font differentiation. + +**Rating: 4** — Branding is well-executed and consistent; meets or exceeds +standards for an incubating project. + +#### Case studies/social proof + +One of the best ways to advertise an open source project is to show other +organizations using it. + +We evaluate on the following: + +- Are there case studies available for the project and are they documented on + the website? + + **Answer:** Not in the user guide. The main kubevirt.io site features a logo + wall of 14 end users (ARM, Cloudflare, NVIDIA, Microsoft, Oracle, Red Hat, + CoreWeave, SUSE, etc.) and 17 vendors. However, there are no dedicated + narrative case studies in the user guide. + +- Are there user testimonials available? + + **Answer:** No explicit testimonials are present in the user guide or visibly + on the main site. + +- Is there an active project blog? + + **Answer:** Yes. The kubevirt.io main site has an active blog with recent + posts (KubeVirt v1.8 release announcement in March 2026, security audit + results, technical articles on migration networks, and more). + +- Are there community talks for the project and are they present on the website? + + **Answer:** Not prominently on the user guide. The Contributing page links to + a New Contributor session recording on YouTube, but there is no dedicated + talks/conference section in the user guide. + +- Is there a logo wall of users/participating organizations? + + **Answer:** Yes, on the main kubevirt.io homepage — End Users, Vendors, and + Integrations sections show logos with links. + +**Rating: 3** — Strong adopter presence on the main site; the user guide itself +lacks case studies and talks sections, but this is typical for a doc-focused +sub-site. + +#### SEO, Analytics and site-local search + +SEO helps users find your project and it's documentation, and analytics helps +you monitor site traffic and diagnose issues like page 404s. Intra-site search, +while optional, can offer your readers a site-focused search results. + +We evaluate on the following: + +- Analytics: + - Is analytics enabled for the production server? + + **Answer:** No analytics is configured in the user guide's `mkdocs.yml` or + detected in the live site HTML. The main kubevirt.io site has an Adobe + Analytics comment tag in its HTML, but no analytics code was found in the + user-guide site. + + - Is analytics disabled for all other deploys? + + **Answer:** Not applicable — no analytics is configured at all for the user + guide. + + - If your project used Google Analytics, have you migrated to GA4? + + **Answer:** Google Analytics is not used on the user guide. No GA4 + configuration was found. + + - Can Page-not-found (404) reports easily be generated from you site + analytics? Provide a sample of the site's current top-10 404s. + + **Answer:** No — without analytics configured on the user guide, 404 reports + cannot be generated from it. + +- Is site indexing supported for the production server, while disabled for + website previews and builds for non-default branches? + + **Answer:** A `sitemap.xml` is generated at + `kubevirt.io/user-guide/sitemap.xml` ✅, and the root `robots.txt` contains + only a `Sitemap:` directive with no `Disallow` rules — meaning the production + site is fully indexable. However, there is no evidence that Netlify preview + builds (which are configured via `netlify.toml`) have indexing disabled via + `X-Robots-Tag` headers or a preview-specific `robots.txt`. + +- Is local intra-site search available from the website? + + **Answer:** Yes. The MkDocs `search` plugin is configured in `mkdocs.yml` and + confirmed functional in the live site HTML. Search is available in the header + on all pages. + +- Are the current custodian(s) of the following accounts clearly documented: + analytics, Google Search Console, site-search (such as Google CSE or Algolia) + + **Answer:** No. There is no documentation of account custodians for analytics, + Google Search Console, or site search anywhere in the user-guide repo or + community repo. + +**Rating: 2** — Intra-site search is well-implemented, a sitemap exists, and +HTTPS is enforced. However, the absence of any analytics on the user guide, no +confirmed indexing control for preview builds, and no custodian documentation +are significant gaps. + +#### Maintenance planning + +Website maintenance is an important part of project success, especially when +project maintainers aren’t web developers. + +We evaluate on the following: + +- Is your website tooling well supported by the community (i.e., Hugo with the + Docsy theme) or commonly used by CNCF projects (our recommended tech stack?) + + **Answer:** MkDocs with the Material theme is widely used in the CNCF + ecosystem and is well-supported by the community. It is not the + CNCF-recommended Hugo/Docsy stack, but is a valid and popular alternative. The + `mkdocs-awesome-nav` and `mkdocs-redirects` plugins are also well-maintained. + The main kubevirt.io site uses Jekyll, a different stack, which adds + complexity. + +- Are you actively cultivating website maintainers from within the community? + + **Answer:** The OWNERS and OWNERS_ALIASES files in the user-guide repo define + approvers and reviewers. The Contributing page encourages docs contributions. + No explicit program for cultivating dedicated website maintainers is + described. + +- Are site build times reasonable? + + **Answer:** Yes. MkDocs builds are typically fast (seconds to low minutes for + a site this size). Netlify is configured for preview builds and GitHub Pages + for production. Build configuration is in `netlify.toml`. + +- Do site maintainers have adequate permissions? + + **Answer:** The repo uses Kubernetes-style OWNERS files for managing merge + permissions. GitHub repository access is managed through the kubevirt GitHub + organization. This appears adequate. + +**Rating: 3** — The toolchain is solid and appropriate. The two-repo split +(Jekyll + MkDocs) adds some maintenance overhead but each site is individually +well-maintained. + +#### Other + +- Is your website accessible via HTTPS? + + **Answer:** Yes. The site responds with HTTP/2 200 over HTTPS at + `https://kubevirt.io/user-guide/`. ✅ + +- Does HTTP access, if any, redirect to HTTPS? + + **Answer:** Yes. An HTTP request to `http://kubevirt.io/user-guide/` returns + HTTP 301 redirecting to the HTTPS URL. ✅ + +**Rating: 5** — Full marks; HTTPS is enforced with proper HTTP→HTTPS redirect +via GitHub Pages. + +### Recommendations + +#### Single-source requirement + +Consider consolidating the kubevirt.io web presence into a single repo or +establishing a clearly documented strategy for the two-repo split. One practical +approach would be to serve the user guide from a `docs/` subdirectory of the +main `kubevirt.github.io` repo using a git submodule pointing to the +`user-guide` repo, or to document explicitly that the two repos are +intentionally separate with different purposes. A migration guide for +contributors explaining which repo handles which content would reduce confusion. +Alternatively, migrating the main kubevirt.io site to MkDocs Material (to match +the user guide) would unify tooling and contributor experience. + +#### Minimal website requirements + +Explicitly document the target stakeholder personas (cluster administrators, VM +users, KubeVirt developers) and their documentation needs. This would help the +project track coverage gaps and prioritize new documentation work. Consider also +performing a formal CNCF website guidelines review to identify any outstanding +compliance gaps before graduation. + +#### Usability, accessibility and devices + +Adopt a basic accessibility policy and document it (even a brief statement in +CONTRIBUTING.md is sufficient). Run a [WAVE](https://wave.webaim.org/) or +[axe](https://www.deque.com/axe/) accessibility audit on at least the homepage +and a representative doc page, and address any high-severity findings. Consider +enabling the MkDocs Material +[accessibility plugin](https://squidfunk.github.io/mkdocs-material/plugins/accessibility/) +for automated a11y checks during build. + +#### Branding and design + +No significant action required. Branding is consistent and professional. +Consider adding the CNCF Incubating project badge to the user-guide homepage to +reinforce project maturity signaling. + +#### Case studies/social proof + +Consider adding a "Who uses KubeVirt?" section or page to the user guide that +links to the adopters logos on the main site, notable blog posts from end users, +and any conference talk recordings. This would help new evaluators of the +project quickly understand the production usage breadth without needing to +navigate away from the docs. + +#### SEO, Analytics and site-local search + +This is the highest-priority gap. The following actions are recommended: + +1. **Add analytics to the user guide**: Configure a privacy-respecting analytics + solution (e.g., [Plausible](https://plausible.io/), which is CNCF-friendly + and privacy-focused, or GA4) in `mkdocs.yml` under the `extra.analytics` key. + This enables 404 detection and traffic visibility. +2. **Disable indexing on preview/non-production builds**: Add a + `X-Robots-Tag: noindex` header or include a preview-specific `robots.txt` + disallow in Netlify configuration for branch deploys and PR previews. +3. **Document account custodians**: Create a section in the community repo (or + the user-guide CONTRIBUTING.md) listing the named owners of the analytics + account, Google Search Console, and any other site-related accounts. +4. **Improve robots.txt**: The current root-level `robots.txt` only has a + sitemap reference. Verify that the sitemap URL is correct (note: it has a + double slash `//sitemap.xml` which should be fixed) and consider adding + explicit `Allow` directives for clarity. + +#### Maintenance planning + +Document a succession plan for website maintainers in the community repo — who +approves content changes, who has GitHub Pages deployment access, and how new +maintainers are onboarded. Consider consolidating the user-guide and main site +under a single `sig/documentation` ownership model (the documentation SIG +already exists in sig-list.md but has no chairs or contact listed — this should +be filled in). + +#### Other + +No action required for HTTPS/HTTP redirect — this is handled correctly by GitHub +Pages. + +#### 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 From 4017b98e81a01a34db447bd2d40b4f58675477cc Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Fri, 19 Jun 2026 20:16:44 -0700 Subject: [PATCH 11/49] spell and fixes Signed-off-by: Bruce Hamilton --- .cspell.yml | 1 + analyses/2026/kubevirt/analysis.md | 14 +++++--------- 2 files changed, 6 insertions(+), 9 deletions(-) diff --git a/.cspell.yml b/.cspell.yml index f4798273..71077c08 100644 --- a/.cspell.yml +++ b/.cspell.yml @@ -51,4 +51,5 @@ words: - Quickstarts - Killercoda - Tekton + - cncf \ No newline at end of file diff --git a/analyses/2026/kubevirt/analysis.md b/analyses/2026/kubevirt/analysis.md index 66c3227c..f87aff9e 100644 --- a/analyses/2026/kubevirt/analysis.md +++ b/analyses/2026/kubevirt/analysis.md @@ -396,10 +396,8 @@ We evaluate on the following: **Answer:** Yes. The user-guide has a dedicated [Contributing](https://kubevirt.io/user-guide/contributing/) page with a "Your first contribution" section that lists suggested repos, explains the - `good-first-issue` label, links to a - [New Contributor session recording](https://www.youtube.com/playlist?list=PLnLpXX8KHIYw1nDm8BLpg1SyETGcH93yl), - and describes other ways to get started. Prerequisites (Git, GitHub workflow, - labs) are also clearly listed. + `good-first-issue` label, and describes other ways to get started. + Prerequisites (Git, GitHub workflow, labs) are also clearly listed. - Do new users know where to get help? @@ -454,8 +452,8 @@ The analysis in this section was generated by AI, Claude Sonnet 4.6, and comprises the answers to questions, findings, and rating evaluations. KubeVirt is an **incubating** project of CNCF. This means that the project -should be [_developing_][criteria] professional-quality documentation alongside -the project code. +should be developing professional-quality documentation alongside the project +code. | Criterion | Rating (1-5) | | ------------------------------------------- | ------------ | @@ -824,9 +822,7 @@ Adopt a basic accessibility policy and document it (even a brief statement in CONTRIBUTING.md is sufficient). Run a [WAVE](https://wave.webaim.org/) or [axe](https://www.deque.com/axe/) accessibility audit on at least the homepage and a representative doc page, and address any high-severity findings. Consider -enabling the MkDocs Material -[accessibility plugin](https://squidfunk.github.io/mkdocs-material/plugins/accessibility/) -for automated a11y checks during build. +enabling the MkDocs Material for automated a11y checks during build. #### Branding and design From 74b2c069277a34a658834a983bbab65d3ea37535 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Fri, 19 Jun 2026 20:43:55 -0700 Subject: [PATCH 12/49] ran Prettier on cspell Signed-off-by: Bruce Hamilton --- .cspell.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/.cspell.yml b/.cspell.yml index 71077c08..c2a30527 100644 --- a/.cspell.yml +++ b/.cspell.yml @@ -52,4 +52,3 @@ words: - Killercoda - Tekton - cncf - \ No newline at end of file From d49ddb927f30ab5833a3f8912187a8c11a14a0d1 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Sat, 20 Jun 2026 22:32:05 -0700 Subject: [PATCH 13/49] proj doc comments, added cspell words Signed-off-by: Bruce Hamilton --- .cspell.yml | 2 + analyses/2026/kubevirt/analysis.md | 144 +++++++++++++++++++++++++++-- 2 files changed, 140 insertions(+), 6 deletions(-) diff --git a/.cspell.yml b/.cspell.yml index c2a30527..2432cfbc 100644 --- a/.cspell.yml +++ b/.cspell.yml @@ -52,3 +52,5 @@ words: - Killercoda - Tekton - cncf + - virtctl + - hugepages diff --git a/analyses/2026/kubevirt/analysis.md b/analyses/2026/kubevirt/analysis.md index f87aff9e..3282aec5 100644 --- a/analyses/2026/kubevirt/analysis.md +++ b/analyses/2026/kubevirt/analysis.md @@ -1,7 +1,7 @@ --- title: KubeVirtDocumentation Analysis created: 2026-05-24 -modified: 2026-06-19 +modified: 2026-06-20 author: Bruce Hamilton --- @@ -112,6 +112,8 @@ to legal requirements such as copyright and licensing issues. ## Project documentation +Section analysis by author unless otherwise indicated + KubeVirt is an **incubating** project of CNCF. This means that the project should be developing professional-quality documentation alongside the project code. @@ -133,6 +135,9 @@ The following observations are my initial observations on the KubeVirt documentation (https://kubevirt.io/user-guide) by its sections as shown on the top navigation bar. +This comment section refers to some of the high priority tasks identified by AI, +Claude Sonnet 4.6. For For all tasks and details, see TBD. + Docs welcome page: - From the home page, selecting **Docs** from the top navigation tabs opens the @@ -160,6 +165,12 @@ Architecture: - The How to and When to use a virtual machine sections would be better placed in getting started or as administration tasks. +- Examples of Architecture tasks identified by AI: + - Separate conceptual and procedural content. + - Update deprecated spec.running references. + - Verify and update force-restart grace-period limitation. + - Review and restructure section ordering for new-user flow. + QuickStarts: - The Labs, which are used in conjunction with the Quickstarts, are not shown @@ -172,6 +183,14 @@ QuickStarts: topic with references to Kind and MiniKube. Such thoughts may have been considered before. +- Examples of Quickstart tasks identified by AI: + - Add common prerequisites section. + - Add labs link to top-level navigation. + - Fix accessModes error and add it as an explicit troubleshooting step. + - Add cleanup and reset instructions. + - Update dv_fedora.yml to current CDI API and image reference. + - Investigate and fix SSH connectivity issues. + Cluster Administration: - The top (first) page in the section, Installation, has guidance what would be @@ -181,6 +200,119 @@ Cluster Administration: Virtualization". - The "KubeVirt Tekton" topic might be better titled as "Tekton pipelines." +- Examples of Cluster Administration tasks identified by AI: + - Audit and update OKD Service Catalog APB section. + - Update outdated `--admission-control` flag reference. + - Replace internal dev image references with public images. + - Verify and update API stability status. + - Replace deprecated `--delete-local-data` flag. + - Remove outdated live-migration-not-yet-supported note. + - Add installation instructions for KubeVirt Tekton Tasks. + +User Workloads: + +- The top overview for this section should describe the concept of User + Workloads and how it's pertinent to KubeVirt, such as to use workload + partitioning to accommodate resources spikes. +- The "Lifecycle" topic contains useful How-to guidance on VMs with Kubectl. +- The "Basic Use" topic has useful KubeVirt intro content. +- Helpful `virtctl` summary guidance could be aggregated from `virtctl in the + title.split computing +- The "Templates" and "Virtual Machine Templates" share the same content. + +- Examples of User Workload tasks identified by AI: + - Add VirtualMachine (VM) vs VirtualMachineInstance (VMI) distinction. + - Add macOS and Windows install instructions. + - Fix conflicting kernelArgs documentation. + - Add `virtctl` commands for querying guest info. + - Add the list of available common instance types. + - Add deprecation note pointing to VirtualMachinePool. + - Replace kubevirt/fedora-cloud-container-disk-demo image with public image. + - Update RestartRequired limitation about revert workaround. + +Compute: + +- The topics comprise a variety of tasks that read well and have needs for + mostly tasks such as defining terms and providing examples. Adding subsections + to the left-side navigation bar could be helpful for discovery. + +- Examples of Compute tasks identified by AI: + - Add a KubeVirt-specific hugepages configuration example. + - Create Compute section overview page. + - Add a live-migration cancellation section. + - Reconcile page content with the live migration lab. + - Add introduction distinguishing nodeSelector vs affinity vs toleration. + - Flag alpha label for auto-memory-limits-ratio as potentially unstable. + - Add a summary table of resource allocation rules. + - Add WaitAsReceiver RunStrategy documentation. + +Network: + +- Essentially reference content. Task-based titles could help discovery. + +- Examples of Compute tasks identified by AI: + +- Create Network section overview page. +- Replace unofficial container disk image. +- Add a 'How DNS resolution works for VMs' conceptual intro. +- Update API reference links from 'master' to 'main'. +- Add a network binding comparison table. +- Replace internal dev container image in VMI example. +- Add an egress NetworkPolicy example. +- Add a hot-unplug step-by-step example. + +Storage: + +- Essentially reference content. Task-based titles could help discovery. + +- Examples of Compute tasks identified by AI: + - Create Storage section overview page. + - Replace hardcoded personal path in example command. + - Replace 'master' branch in API reference links with 'main'. + - Replace unofficial kubevirt dev images in examples. + - Remove stale pre-v0.20 registryDisk migration note. + - Replace dev image in disk-sharing example. + - Clarify Migration Controller vs Migration Operator naming. + - Replace dev images in volume migration examples. + +Release notes: + +- A unusual prominent location for release notes, but clearly convenient. + Improvements suggests could be formatting, consistency edits, and perhaps data + aggregation. + +- Examples of Compute tasks identified by AI: + +- Complete the truncated KubeVirtVMGuestMemoryPressure entry. +- Add missing Kubernetes support matrix line to v1.1.0 section. +- Establish and document a release notes template. +- Add release notes maintenance guidance to contributing.md. + +Contributing: + +- Provide an engaging page about ways to contribute. A large part of the content + could be in a more discoverable two-column table of links and descriptions. + +- Examples of Contributing tasks identified by AI: + +- Verify New Contributor session recording playlist link. +- Add PR CI process overview. +- Add local-preview workflow to Contributing page. +- Add link-checking and spell-check steps to Contributing page. + +Virtualization Debugging: + +- Specifies the page is about KubeVirt debugging, so having "Virtualization" in + the title makes it seem like it might be subset of KubeVirt debugging. + +- Overview needs examples of debugging scenarios. + +Examples of Virtualization Debugging tasks identified by AI: + +- Fix 'master' branch in LogVerbosity API reference link. +- Fix stale operations/ path in cross-link to debug page. +- Replace unofficial dev image in logging example VMI. + #### Information architecture The overall structure (pages/subpages/sections/subsections) of your project @@ -243,7 +375,7 @@ We evaluate on the following: Creating inclusive project communities is a key goal for all CNCF projects. -We evaluate on the following: +We evluate on the following: - Are there any customer-facing utilities, endpoints, class names, or feature names that use non-recommended words as documented by the @@ -267,8 +399,8 @@ We evaluate on the following: ## Contributor documentation -The analysis in this section was generated by AI, Claude Sonnet 4.6, and -comprises the answers to questions, findings, and rating evaluations. +Section analysis generated by AI, Claude Sonnet 4.6, and includes the answers to +questions, findings, and rating evaluations. KubeVirt is an **incubating** project of CNCF. This means that the project should be developing professional-quality documentation alongside the project @@ -448,8 +580,8 @@ actionable backlog, new contributors who follow the guidance reach a dead end. ## Website and infrastructure -The analysis in this section was generated by AI, Claude Sonnet 4.6, and -comprises the answers to questions, findings, and rating evaluations. +Section analysis generated by AI, Claude Sonnet 4.6, and includes the answers to +questions, findings, and rating evaluations. KubeVirt is an **incubating** project of CNCF. This means that the project should be developing professional-quality documentation alongside the project From f41d594a0dcdb4b89c5c00c01c7764e4ad0a92a1 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Sat, 20 Jun 2026 22:38:52 -0700 Subject: [PATCH 14/49] spell fix Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/analysis.md | 1 - 1 file changed, 1 deletion(-) diff --git a/analyses/2026/kubevirt/analysis.md b/analyses/2026/kubevirt/analysis.md index 3282aec5..312568e8 100644 --- a/analyses/2026/kubevirt/analysis.md +++ b/analyses/2026/kubevirt/analysis.md @@ -283,7 +283,6 @@ Release notes: - Examples of Compute tasks identified by AI: -- Complete the truncated KubeVirtVMGuestMemoryPressure entry. - Add missing Kubernetes support matrix line to v1.1.0 section. - Establish and document a release notes template. - Add release notes maintenance guidance to contributing.md. From bc13450a8c6890ba4cfbbf8ea5966f542a65e988 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Sat, 20 Jun 2026 22:42:07 -0700 Subject: [PATCH 15/49] spelling fix Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/analysis.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/analyses/2026/kubevirt/analysis.md b/analyses/2026/kubevirt/analysis.md index 312568e8..5f8305ee 100644 --- a/analyses/2026/kubevirt/analysis.md +++ b/analyses/2026/kubevirt/analysis.md @@ -374,7 +374,7 @@ We evaluate on the following: Creating inclusive project communities is a key goal for all CNCF projects. -We evluate on the following: +We evaluate on the following: - Are there any customer-facing utilities, endpoints, class names, or feature names that use non-recommended words as documented by the From e7001f389fd983cc773f60c74d156277ccb185b8 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Sun, 21 Jun 2026 23:59:50 -0700 Subject: [PATCH 16/49] all sections draft complete Signed-off-by: Bruce Hamilton --- .cspell.yml | 21 + analyses/2026/kubevirt/analysis.md | 1010 +++++++++++++++++++++++++--- 2 files changed, 922 insertions(+), 109 deletions(-) diff --git a/.cspell.yml b/.cspell.yml index 2432cfbc..ffac7344 100644 --- a/.cspell.yml +++ b/.cspell.yml @@ -49,8 +49,29 @@ words: - kubevirt - Quickstart - Quickstarts + - quickstart + - quickstarts - Killercoda - Tekton + - tekton - cncf - virtctl - hugepages + - virt + - virsh + - Hotplug + - hotplug + - NUMA + - instancetype + - instancetypes + - virtio + - vsock + - CirrOS + - Cirros + - cirros + - openshift + - ansible + - pasteable + - portgroup + - Multus + - multus diff --git a/analyses/2026/kubevirt/analysis.md b/analyses/2026/kubevirt/analysis.md index 5f8305ee..cf179774 100644 --- a/analyses/2026/kubevirt/analysis.md +++ b/analyses/2026/kubevirt/analysis.md @@ -1,7 +1,7 @@ --- title: KubeVirtDocumentation Analysis created: 2026-05-24 -modified: 2026-06-20 +modified: 2026-06-21 author: Bruce Hamilton --- @@ -118,25 +118,55 @@ KubeVirt is an **incubating** project of CNCF. This means that the project should be developing professional-quality documentation alongside the project code. -| Criterion | [Rating (1-5)] | -| -------------------------- | -------------- | -| Information architecture | [rating (1-5)] | -| New user content | [rating (1-5)] | -| Content maintainability | [rating (1-5)] | -| Content creation processes | [rating (1-5)] | -| Inclusive language | [rating (1-5)] | +| Criterion | Rating (1-5) | +| ---------------------------------------- | ------------ | +| Information architecture | 4 | +| New user content | 3 | +| Content maintainability & site mechanics | 2 | +| Content creation processes | 3 | +| Inclusive language | 3 | ### Comments -The following sections contain brief assessments of each element of the Project +The following sections contain assessments of each element of the Project Documentation rubric. -The following observations are my initial observations on the KubeVirt -documentation (https://kubevirt.io/user-guide) by its sections as shown on the -top navigation bar. +This section includes AI observations generated from Claude Sonnet 4.6 and are +indicated as AI. -This comment section refers to some of the high priority tasks identified by AI, -Claude Sonnet 4.6. For For all tasks and details, see TBD. +#### Overall comments + +Author comments: + +The KubeVirt has a well-thought out structure that can accommodate improvements +without having to restructure sections on a wide basis. + +The Welcome page has long lines in bullets could be better formatted for +readability and scanning. See the rest of overall comments by the Author in the +next section, "Comments of KubeVirt documentation sections." + +AI comments: + +The KubeVirt user guide is a comprehensive, well-organized documentation site +covering architecture, installation, cluster administration, user workloads, +compute, networking, storage, debugging, and release notes — 94 Markdown pages +in total, served via MkDocs Material at `kubevirt.io/user-guide/`. + +The breadth of topics is good for an incubating project. Key gaps include the +lack of versioned documentation, no localization framework, no self-contained +getting started path, and an externally-hosted API reference that is only +loosely integrated with the user guide. + +(end AI comments) + +#### Comments of KubeVirt documentation sections + +The following observations are author observations on the KubeVirt documentation +(https://kubevirt.io/user-guide) by its sections as shown on the top navigation +bar. + +AI comments for these sections are tasks defined in the KubeVirt-Analysis.csv +file, described later in Recommendations. Docs welcome page: @@ -165,12 +195,6 @@ Architecture: - The How to and When to use a virtual machine sections would be better placed in getting started or as administration tasks. -- Examples of Architecture tasks identified by AI: - - Separate conceptual and procedural content. - - Update deprecated spec.running references. - - Verify and update force-restart grace-period limitation. - - Review and restructure section ordering for new-user flow. - QuickStarts: - The Labs, which are used in conjunction with the Quickstarts, are not shown @@ -183,14 +207,6 @@ QuickStarts: topic with references to Kind and MiniKube. Such thoughts may have been considered before. -- Examples of Quickstart tasks identified by AI: - - Add common prerequisites section. - - Add labs link to top-level navigation. - - Fix accessModes error and add it as an explicit troubleshooting step. - - Add cleanup and reset instructions. - - Update dv_fedora.yml to current CDI API and image reference. - - Investigate and fix SSH connectivity issues. - Cluster Administration: - The top (first) page in the section, Installation, has guidance what would be @@ -200,15 +216,6 @@ Cluster Administration: Virtualization". - The "KubeVirt Tekton" topic might be better titled as "Tekton pipelines." -- Examples of Cluster Administration tasks identified by AI: - - Audit and update OKD Service Catalog APB section. - - Update outdated `--admission-control` flag reference. - - Replace internal dev image references with public images. - - Verify and update API stability status. - - Replace deprecated `--delete-local-data` flag. - - Remove outdated live-migration-not-yet-supported note. - - Add installation instructions for KubeVirt Tekton Tasks. - User Workloads: - The top overview for this section should describe the concept of User @@ -220,85 +227,27 @@ User Workloads: title.split computing - The "Templates" and "Virtual Machine Templates" share the same content. -- Examples of User Workload tasks identified by AI: - - Add VirtualMachine (VM) vs VirtualMachineInstance (VMI) distinction. - - Add macOS and Windows install instructions. - - Fix conflicting kernelArgs documentation. - - Add `virtctl` commands for querying guest info. - - Add the list of available common instance types. - - Add deprecation note pointing to VirtualMachinePool. - - Replace kubevirt/fedora-cloud-container-disk-demo image with public image. - - Update RestartRequired limitation about revert workaround. - Compute: - The topics comprise a variety of tasks that read well and have needs for mostly tasks such as defining terms and providing examples. Adding subsections to the left-side navigation bar could be helpful for discovery. -- Examples of Compute tasks identified by AI: - - Add a KubeVirt-specific hugepages configuration example. - - Create Compute section overview page. - - Add a live-migration cancellation section. - - Reconcile page content with the live migration lab. - - Add introduction distinguishing nodeSelector vs affinity vs toleration. - - Flag alpha label for auto-memory-limits-ratio as potentially unstable. - - Add a summary table of resource allocation rules. - - Add WaitAsReceiver RunStrategy documentation. - -Network: - -- Essentially reference content. Task-based titles could help discovery. - -- Examples of Compute tasks identified by AI: - -- Create Network section overview page. -- Replace unofficial container disk image. -- Add a 'How DNS resolution works for VMs' conceptual intro. -- Update API reference links from 'master' to 'main'. -- Add a network binding comparison table. -- Replace internal dev container image in VMI example. -- Add an egress NetworkPolicy example. -- Add a hot-unplug step-by-step example. - -Storage: +Network and Storage: - Essentially reference content. Task-based titles could help discovery. -- Examples of Compute tasks identified by AI: - - Create Storage section overview page. - - Replace hardcoded personal path in example command. - - Replace 'master' branch in API reference links with 'main'. - - Replace unofficial kubevirt dev images in examples. - - Remove stale pre-v0.20 registryDisk migration note. - - Replace dev image in disk-sharing example. - - Clarify Migration Controller vs Migration Operator naming. - - Replace dev images in volume migration examples. - Release notes: - A unusual prominent location for release notes, but clearly convenient. Improvements suggests could be formatting, consistency edits, and perhaps data aggregation. -- Examples of Compute tasks identified by AI: - -- Add missing Kubernetes support matrix line to v1.1.0 section. -- Establish and document a release notes template. -- Add release notes maintenance guidance to contributing.md. - Contributing: - Provide an engaging page about ways to contribute. A large part of the content could be in a more discoverable two-column table of links and descriptions. -- Examples of Contributing tasks identified by AI: - -- Verify New Contributor session recording playlist link. -- Add PR CI process overview. -- Add local-preview workflow to Contributing page. -- Add link-checking and spell-check steps to Contributing page. - Virtualization Debugging: - Specifies the page is about KubeVirt debugging, so having "Virtualization" in @@ -306,45 +255,171 @@ Virtualization Debugging: - Overview needs examples of debugging scenarios. -Examples of Virtualization Debugging tasks identified by AI: - -- Fix 'master' branch in LogVerbosity API reference link. -- Fix stale operations/ path in cross-link to debug page. -- Replace unofficial dev image in logging example VMI. - #### Information architecture The overall structure (pages/subpages/sections/subsections) of your project documentation. We evaluate on the following: -- Is there high level conceptual/“About” content? Is the documentation feature +The answers and rating paragraphs in this section were generated by AI: + +- Is there high level conceptual/"About" content? Is the documentation feature complete? (i.e., each product feature is documented) + + **Answer:** Yes. The `architecture.md` page provides a conceptual overview of + KubeVirt's service-oriented architecture, its relationship to Kubernetes, and + the roles of CRDs, controllers, and daemons. Each of the main sections + (Cluster Administration, User Workloads, Compute, Network, Storage) begins + with conceptual framing before presenting tasks. Feature coverage is broad: + live migration, CPU/memory hotplug, hugepages, NUMA, host devices, storage + import/export/snapshot/clone, network binding plugins, and ARM64 support are + all documented. The site is substantially feature-complete for core + functionality. + - Are there step-by-step instructions (tasks, tutorials) documented for features? + + **Answer:** Yes, with caveats. Most pages combine conceptual explanation with + YAML manifests and `kubectl`/`virtctl` command sequences. However, the + presentation style varies: some pages (e.g., `installation.md`, + `live_migration.md`, `snapshot_restore_api.md`) follow a clear task structure, + while others (e.g., `virtual_hardware.md`, `interfaces_and_networks.md`) read + more like reference material with embedded examples. There are no structured + tutorial walkthroughs within the user guide itself — tutorials are delegated + to external Killercoda labs and kubevirt.io/labs links. + - Are there any key features which are documented but missing task documentation? -- Is the “happy path”/most common use case documented? Does task and tutorial + + **Answer:** Yes, a few gaps exist. The `network_binding_plugins.md` page + describes the plugin architecture conceptually but does not include a complete + worked example of implementing and deploying a custom binding plugin. The + `hook-sidecar.md` page similarly describes the mechanism without a clear + end-to-end task. The `instancetypes.md` and related `creating_it_pref.md` + pages describe the instancetype model but don't walk through a complete "VM + from scratch using instancetype and preference" scenario as a single tutorial. + +- Is the "happy path"/most common use case documented? Does task and tutorial content demonstrate atomicity and isolation of concerns? (Are tasks clearly named according to user goals?) + + **Answer:** Partially. The happy path — deploying KubeVirt on a cluster and + running a first VM — is not fully self-contained within the user guide. + `installation.md` covers deployment, and `basic_use.md` covers starting and + stopping VMs, but the connection between them is implicit; there is no + explicit "From zero to your first running VM" sequence that chains these steps + together. Task pages are generally well-named according to user goals (e.g., + "Accessing Virtual Machines", "Hotplug Volumes", "Live Migration"), and most + demonstrate reasonable isolation of concerns. However, the + `disks_and_volumes.md` page covers a very large surface area in a single + document and could benefit from being split. + - If the documentation does not suffice, is there a clear escalation path for users needing more help? (FAQ, Troubleshooting) + + **Answer:** Partially. The homepage has a "Getting help" section linking to + the bug tracker, mailing list, and Slack. There is a dedicated "Virtualization + Debugging" section (`debug_virt_stack/`) with six pages covering log + verbosity, virsh commands, privileged node debugging, QEMU strace, and GDB. + However, there is no FAQ page, and no general troubleshooting page targeting + common user-facing errors (e.g., VM stuck in Pending, network connectivity + failures, image import failures). The debugging section is + advanced/developer-oriented rather than user-oriented. + - If the product exposes an API, is there a complete reference? + + **Answer:** Yes, but it is hosted externally. The KubeVirt API reference is + available at `http://kubevirt.io/api-reference/` and is linked from the user + guide homepage and individual pages. The reference is auto-generated and + covers all CRD types (VirtualMachine, VirtualMachineInstance, + VirtualMachineInstanceMigration, etc.). However, the API reference is not + integrated into the user guide site itself, links to it use `http://` rather + than `https://`, and many in-guide deep links reference the `master` branch + path (`/api-reference/master/definitions.html`) rather than a stable versioned + path, which may become stale. + - Is content up to date and accurate? + **Answer:** Largely yes. Release notes are current through v1.8.0 (March 2026) + and many pages reference recent feature gate additions. However, several API + reference deep-links use `master`-branch paths that may not reflect the latest + stable release. A few older sections may not reflect current defaults (e.g., + AppArmor workarounds described in `installation.md` note a tracking issue as + "future" work, which may have already been resolved upstream). + +**Rating: 3** — Broad and largely accurate coverage with good conceptual +framing; held back by the lack of a self-contained "happy path" sequence, the +external (and HTTP-linked) API reference, no FAQ/user-facing troubleshooting, +and some reference-only pages that could benefit from task-structured rewrites. + #### New user content New users are the most avid users of documentation, and need content specifically for them. We evaluate on the following: -- Is “getting started” clearly labeled? (“Getting started”, “Installation”, - “First steps”, etc.) +The answers and rating paragraphs in this section were generated by AI: + +- Is "getting started" clearly labeled? ("Getting started", "Installation", + "First steps", etc.) + + **Answer:** Partially. The top-level navigation includes a "Quickstarts" entry + and a "Cluster Administration" section whose first page is "Installation." + However, the Quickstarts page (`quickstarts.md`) is essentially a curated list + of external links (Killercoda, minikube, kind, cloud providers) and contains + no embedded steps on that page. There is no section explicitly labeled + "Getting Started" that guides a user from zero through a first successful VM. + - Is installation documented step-by-step? + + **Answer:** Yes. `cluster_admin/installation.md` provides clear prerequisites, + container runtime support notes, AppArmor considerations, and installation + steps using `kubectl apply` with the KubeVirt operator manifest. Requirements + (Kubernetes version, `--allow-privileged`, `kubectl`) are enumerated at the + top. The steps are sequential. + - If needed, are multiple OSes documented? + + **Answer:** Partially. The documentation assumes Linux as the host OS + (consistent with Kubernetes deployment targets). ARM64 cluster support is + covered in a dedicated subsection of Cluster Administration (four pages: + device status, feature gate status, operations, and VMs on ARM64). There is no + documentation for Windows hosts, which is appropriate since KubeVirt does not + support Windows as a host OS. Windows _guest_ operating system support is + documented (`user_workloads/windows_virtio_drivers.md`, `legacy_windows.md`). + - Do users know where to go after reading the getting started guide? -- Is your new user content clearly signposted on your site’s homepage or at the + + **Answer:** Partially. The external quickstart guides (e.g., + kubevirt.io/quickstart_minikube/) link back to the user guide for further + learning. The user guide homepage lists all sections with one-line + descriptions, making it clear what the next steps could be. However, the + Quickstarts page itself has no "next steps" or recommended reading path — it + ends with the four links and no guidance on which sections of the user guide + to read next. + +- Is your new user content clearly signposted on your site's homepage or at the top of your information architecture? + + **Answer:** Yes. The homepage lists all guide sections with brief + descriptions, "Try it out" links to Killercoda and quickstart labs, KubeVirt + Labs links, a "Getting help" section, and a "Developer" section. The + "Quickstarts" item appears in the top navigation bar as the third item after + "Welcome" and "Architecture." New users can orient themselves quickly from the + homepage. + - Is there sample code or other example content that can easily be copy-pasted? + **Answer:** Yes. The user guide is rich in YAML manifests and + `kubectl`/`virtctl` command examples throughout. Most feature pages provide at + least one complete YAML snippet showing the relevant spec fields in context. + Code blocks are syntax-highlighted via with anchor line numbers, and MkDocs + Material provides a one-click copy button on code blocks. The examples are + generally realistic and independently runnable. + +**Rating: 3** — Installation is well-documented and examples can be pasted; +signposting on the homepage is adequate. Key weaknesses are the Quickstarts page +delegating entirely to external content without a self-contained path, and the +lack of a "What to read next" guide for new users. + #### Content maintainability & site mechanics As a project scales, concerns like localized (translated) content and versioning @@ -352,11 +427,44 @@ become large maintenance burdens, particularly if you don’t plan for them. We evaluate on the following: +The answers and rating paragraphs in this section were generated by AI: + - Is your documentation searchable? + + **Answer:** Yes. The MkDocs `search` plugin is configured in `mkdocs.yml` with + a custom separator to improve tokenization, and site-local search is + functional and present in the header on all pages. See also the website + analysis document's assessment of intra-site search (rated 4/5). + - Are you planning for localization/internationalization with regards to site directory structure? Is a localization framework present? + + **Answer:** No. The documentation is English-only with no localization + framework in place. The directory structure does not include language-code + subdirectories (e.g., `docs/zh-CN/`), and `mkdocs.yml` has no `i18n` or + `locale` configuration. There is one open issue in the user-guide repo + proposing Simplified Chinese (zh-CN) documentation, but no implementation has + begun. MkDocs Material's `i18n` plugin (which would enable language-based + directory structure) is not currently enabled. + - Do you have a clearly documented method for versioning your content? + **Answer:** No. The user guide serves a single version of documentation from + the `main` branch with no versioning mechanism. There are no versioned doc + sets (e.g., separate /v1.7/, /v1.8/ branches or MkDocs `mike` plugin + configuration). Release notes (`release_notes.md`) are maintained in a single + file covering all releases, but this is distinct from versioned documentation. + Many in-page API reference links hardcode `/api-reference/master/` as the + path, meaning users reading docs for an older release see links to current-tip + API behavior. This is a meaningful gap as KubeVirt has a defined support + matrix (latest three Kubernetes releases) and users running older versions may + have different feature availability. + +**Rating: 2** — Search is well-implemented, but the absence of both a +localization framework and a doc versioning strategy represent significant gaps +for a project with multiple active release lines and a growing international +community. + #### Content creation processes Documentation is only as useful as it is accurate and well-maintained, and @@ -364,38 +472,722 @@ requires the same kind of review and approval processes as code. We evaluate on the following: +The answers and rating paragraphs in this section were generated by AI: + - Is there a clearly documented (ongoing) contribution process for documentation? + + **Answer:** Yes. The `contributing.md` page (linked from the main navigation) + clearly describes prerequisites (Git workflow, GitHub familiarity), repository + entry points for docs contributions (user-guide, kubevirt.github.io, community + repos), how to find `good-first-issue` labeled issues, and alternative + contribution paths (PR reviews, issue filing, New Contributor session + recording). The CONTRIBUTING.md in the repo root provides the Makefile-based + local preview workflow (`make build_img`, `make run`, `make check_links`, + `make check_spelling`). + - Does your code release process account for documentation creation & updates? + + **Answer:** Partially. The release notes page is kept current (v1.8.0 as of + March 2026 is present). However, there is no documented policy or checklist + that explicitly requires documentation updates as part of the code release + process. There is no "docs freeze" process, no release-gating on docs + completeness, and no explicit owner for ensuring new features released in each + KubeVirt version are documented in the user guide before or alongside the code + release. + - Who reviews and approves documentation pull requests? + + **Answer:** Clearly documented. The `OWNERS` file defines approvers and + reviewers via `OWNERS_ALIASES`. The `OWNERS` file also specifies that paths + under `docs/` are labeled `kind/documentation` and paths under `site/` are + labeled `kind/website` automatically. The project uses Prow/Tide for automated + label management and lifecycle enforcement. + - Does the website have a clear owner/maintainer? + **Answer:** Partially. The `OWNERS_ALIASES` file identifies the team of + approvers and reviewers. However, there is no single named documentation lead + or website owner. The `sig-list.md` in the community repo lists a + "sig/documentation" SIG but it currently has no chairs or contact persons + listed, meaning the governance structure for documentation exists on paper but + is not actively staffed. + +**Rating: 3** — Contribution workflow and reviewer/approver ownership are well +documented. The main gaps are the absence of a documented release-gating process +for docs and the un-staffed documentation SIG. + #### Inclusive language Creating inclusive project communities is a key goal for all CNCF projects. We evaluate on the following: +The answers and rating paragraphs in this section were generated by AI: + - Are there any customer-facing utilities, endpoints, class names, or feature names that use non-recommended words as documented by the [Inclusive Naming Initiative](https://inclusivenaming.org) website? + + **Answer:** Minor issues present. The word "master" appears in multiple + in-page API reference deep-links (e.g., + `http://kubevirt.io/api-reference/master/definitions.html`), which reflects + the upstream API reference site's URL structure rather than a KubeVirt-owned + naming choice. Within the user guide prose, one code example in + `live_migration.md` shows `"master": "eth1"` as a network interface + configuration key — this is a third-party (libvirt/Linux bridge) configuration + value outside KubeVirt's direct control. No KubeVirt-specific CRD field names, + feature gate names, CLI subcommands, or endpoint names using non-recommended + terms (master/slave, whitelist/blacklist, sanity) were found. + - Does the project use language like "simple", "easy", etc.? + **Answer:** Yes, occasionally. A scan of the docs found approximately 45 + occurrences of "simple" or "easy" across 42 files. Many of these are benign — + resource names in YAML examples (`simple-vm`, `simple-dv`), architecture asset + filenames (`architecture-simple.png`), and technical terms ("Simple frame + buffer device"). However, some are in prose: "a simple example" (multiple + pages in `storage/`), "easy ways to fix them" + (`containerized_data_importer.md`), "simplest" as a descriptor for a + workaround option (`installation.md`), and "easy guest-host communication" + (`vsock.md`). While these are not egregious uses, they reflect an opportunity + to adopt more neutral, descriptive language consistent with CNCF inclusive + language guidance. + +**Rating: 3** — No KubeVirt-owned CRD names, feature names, or user-visible +identifiers use non-recommended terminology. The "master" references are +inherited from external URL structures. Occasional use of "simple"/"easy" in +prose is present but not pervasive and is addressable through normal doc +editing. + ### Recommendations -> AUTHOR NOTE: Write general recommendations based on the comments from the -> previous section. +##### Author overall recommendations: + +The AI results capture my recommendations except for the following pressing +needs I see as a novice user: + +- Guidance and frank advice about using a virtual machine to on a Windows or + MacOS to then use a virtual machine in KubeVirt. This VM within a VM is nested + virtualization and is a key concept for getting to understand KubeVirt. Users + who have a Linux machine don't need to worry about nested virtualization. In + addition, VMs on Windows and MacOS are usually transitory, requiring the + reinstall of clusters, tools, and KubeVirt. This guidance should be in the top + overview or getting started section. + +- The AI results include having a common prerequisites topic, but at a higher + level a Roadmap topic or subsection of Getting Started should provide guidance + for different user scenarios to decide whether to use a VM in Windows or + invest in a Linux computer. While this isn't pertinent to develops, it will + save a lot of time for other users to get on the right path as soon as + possible. + +##### AI overall recommendations: + +The KubeVirt user guide is a substantive, professionally maintained +documentation site with 94 Markdown pages covering architecture, installation, +cluster administration, user workloads, compute, networking, storage, and +debugging. The breadth of topic coverage is strong for a CNCF incubating +project. Core strengths include copyable YAML examples throughout, a clean +MkDocs Material presentation, good branding consistency, and active release +notes. + +**The primary friction surface is onboarding.** New users — whether +Kubernetes-native engineers evaluating KubeVirt as an extension or traditional +VM operators migrating from VMware or OpenStack — have no clear, self-contained +path from zero to a running VM entirely within the user guide. The Quickstarts +page delegates immediately to external Killercoda labs with no embedded steps +and no "what to read next" guidance. + +**A secondary friction surface is content fragmentation.** The API reference is +externally hosted and loosely integrated; the main kubevirt.io site uses Jekyll +while the user guide uses MkDocs; governance documentation lives in a separate +repo with no cross-links; and the documentation SIG is on paper but un-staffed. +These gaps compound each other and make the documentation harder to maintain and +harder for new contributors to navigate. + +The underlying technology is sound, the community momentum is real, and the +VMware migration window (Broadcom pricing/licensing upheaval, 2024–2026) creates +a direct adoption opportunity. Closing these documentation gaps is the +highest-leverage action the project can take to convert evaluators into +production users. + +**A third, concrete finding comes from the page-level task analysis** +(kubevirt-analysis.csv): 266 discrete tasks were identified across 94 pages. Of +these, 66 are high-priority, 86 medium, and 114 low. The high-priority tasks +fall into five clusters — each representing a category of technical debt that +erodes reader trust independently of any structural improvement: + +| Cluster | High-pri task count | Examples | +| ------------------------------------------ | ------------------- | -------------------------------------------------------------------------- | +| Unofficial/internal dev images in examples | 17 | `kubevirt/fedora-cloud-container-disk-demo`, internal registry refs | +| Broken or stale links | 15 | Broken bridge link in live_migration.md, stale OKD 3.9 link | +| Outdated or removed content | 11 | `--delete-local-data` flag, `--admission-control`, pre-v0.34 taint notes | +| Deprecated API references | 6 | `spec.running`, `rbac.authorization.k8s.io/v1beta1`, OKD openshift-ansible | +| User-visible typos in code | 6 | (see csv file) | + +These are independent of audience targeting or architecture improvements — they +are factual errors and broken examples that any reader can encounter today. They +should be addressed before or alongside any larger structural work. + +**Summary scores across all rubric areas:** + +| Area | Rating (1–5) | Primary Gap | +| ---------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------ | +| Information architecture | 3 | No self-contained happy path; missing user-facing troubleshooting; no section overview pages | +| New user content | 3 | Quickstarts delegates entirely to external content; Basic Use page too thin | +| Content maintainability & site mechanics | 2 | No versioning, no localization framework | +| Content creation processes | 3 | No release-gating on docs; documentation SIG un-staffed; no release notes template | +| Inclusive language | 3 | Occasional "simple"/"easy" in prose; "master" in API links | +| Website & infrastructure | 2–4 (varies) | No analytics, no preview-build noindex, no account custodians | +| Contributor experience | 3 | Onboarding info spread across four repos; no active good-first-issues | +| **Technical debt (accuracy)** | **2** | **17 unofficial images, 15 broken links, 11 outdated sections, 6 deprecated APIs, 6 code typos** | + +#### Technical Debt & Content Accuracy + +This Technical Debt & Content Accuracy section is a proposed template change and +was generated by AI. + +> These tasks described for Technical Debt & Content Accuracy are sourced +> directly from kubevirt-analysis.csv. The 266 tasks in that file are intended +> for SME triage and GitHub issue creation. The recommendations below describe +> the patterns and priorities at a level useful for project planning; individual +> task details (node IDs, file paths, specific fixes) are in the CSV. + +This is the most immediately actionable area. No structural change is required — +each item is a concrete, bounded fix in a known file. Taken together, they +represent a systematic erosion of reader trust: a reader who hits a broken link, +an image that won't pull, or a typo in a field name they're about to paste into +production has reason to distrust the entire page. + +##### 1. Replace unofficial and internal dev images in examples + +**Priority: High — 17 occurrences across 11+ files** + +Multiple pages embed container image references from internal development +registries or personal/unofficial namespaces that readers cannot pull: + +- `kubevirt/fedora-cloud-container-disk-demo` (user_workloads, network, storage + pages). +- Internal registry paths (confidential_computing.md, host-devices.md, debug + strace pages). +- Unofficial CirrOS images (run_strategies.md, dns.md, service_objects.md). +- Dev sidecar/shim images (launch-qemu-strace.md). + +**Recommendation:** Establish a canonical set of public, stable container images +for documentation examples (e.g., `quay.io/kubevirt/cirros-container-disk-demo`, +official Fedora Cloud images). Run a single sweep replacing all unofficial +references in one PR, then add a CI linting rule (e.g., a grep check on +`registry.k8s.io` or known internal registry host names in Markdown code blocks) +to prevent regressions. + +##### 2. Fix broken and stale links + +**Priority: High — 15 occurrences across 10+ files** + +Broken links identified include: + +- Bridge interface link in `compute/live_migration.md` (A05-B06-T01) +- Cross-link to live migration prerequisites from + `cluster_admin/tekton_tasks.md` (A03-B14-T01) +- Stale OKD 3.9 documentation link in `compute/hugepages.md` (A05-B05-T02) +- Feature-gate links using absolute paths in `network/hotplug/interfaces.md` + (A06-B07-T01) and `network/hotplug/nad_reference.md` (A06-B08-T02) +- Stale golang tour URL in `contributing.md` (A09-B01-T01) +- `master`-branch API reference links in `network/interfaces_and_networks.md`, + `storage/disks_and_volumes.md`, and `debug_virt_stack/debug.md` +- Stale cross-link using old `operations/` path in `debug_virt_stack/logging.md` + (A10-B02-T01) +- DNS resolver spec link in `network/dns.md` (A06-B01-T01) + +**Recommendation:** Run `make check_links` on a CI schedule (not just on PR) and +treat link failures as blocking. For the `master`-branch API reference links, +this is the same fix as the broader API link scheme recommendation (see +Information Architecture §2) — a single pass replaces all of them. + +##### 3. Remove or update deprecated API references + +**Priority: High — 6 occurrences across 5 files** + +- `spec.running` field references throughout `architecture.md` (A01-T02) — + deprecated in favor of `spec.runStrategy` +- `rbac.authorization.k8s.io/v1beta1` API version in + `user_workloads/accessing_virtual_machines.md` (A04-B06-T01) — removed in + Kubernetes 1.25 +- `--admission-control` flag (replaced by `--enable-admission-plugins`) in + `cluster_admin/api_validation.md` (A03-B05-T01) +- OKD `openshift-ansible` references in `cluster_admin/api_validation.md` + (A03-B05-T02) +- `instancetype.kubevirt.io` API stability status note in + `user_workloads/instancetypes.md` (A04-B15-T01) — may have been promoted to + stable +- Missing deprecation notice on `user_workloads/presets.md` (A04-B18-T01) — + Presets are deprecated in favor of Instancetypes + +**Recommendation:** Each of these is a high-confidence fix that does not require +SME judgment — they are factually wrong or out of date. Batch into a single +"deprecated API cleanup" PR. Add the Presets deprecation admonition immediately +as it actively misleads users into using a feature that is being removed. + +##### 4. Fix user-visible typos in code and API field names + +**Priority: High — 6 occurrences, some in copy-pasteable code** + +(see CSV file) + +**Recommendation:** Fix all in a single PR — these are unambiguous one-line +changes. The field name typos are especially damaging because users copy them +verbatim and then debug why their manifest doesn't work. + +##### 5. Remove or archive outdated historical content + +**Priority: High/Medium — 11 occurrences** + +Sections describing behavior specific to unsupported releases confuse readers on +current versions and signal that the docs are not maintained: + +- Pre-v0.20.0 and pre-v0.34.2 version-specific notes in + `cluster_admin/installation.md` (A03-B01-T02) +- Pre-v0.34 taint note in `cluster_admin/node_maintenance.md` (A03-B12-T03) +- Pre-v0.56 feature gate enablement note in `compute/live_migration.md` + (A05-B06-T03) +- "Future release" language in `cluster_admin/installation.md` AppArmor section + (A03-B01-T01) — the referenced issue may already be resolved +- "Future release" language in `compute/persistent_tpm_and_uefi_state.md` + (A05-B14-T01) +- `--delete-local-data` flag (deprecated in kubectl 1.20, removed in 1.27) in + `cluster_admin/node_maintenance.md` (A03-B12-T01) +- OKD Service Catalog APB section in `cluster_admin/installation.md` + (A03-B01-T03) — the Service Catalog was removed from OKD years ago +- Outdated OKD `openshift-ansible` section in `cluster_admin/api_validation.md` + (A03-B05-T02) + +**Recommendation:** SME review required for some (e.g., whether the AppArmor +issue is resolved). Others (pre-v0.20 notes, `--delete-local-data`, OKD APB) can +be deleted without verification — they describe behavior removed in Kubernetes +or OKD versions that are no longer in the support matrix. + +##### 6. Fix the JSON syntax error in the passt registration example + +**Priority: High — 1 occurrence** + +(A06-B04-T01) See sheet for a JSON syntax error in the passt plugin registration +example. A reader following this example will get an error with no indication +the source is the doc. Fix immediately. + +##### 7. Complete truncated and placeholder release notes entries + +**Priority: High/Medium — 2 occurrences** + +- The `KubeVirtVMGuestMemoryPressure` entry in `release_notes.md` is truncated + mid-sentence (A08-B01-T05) +- A placeholder appears in place of a real release note (A08-B01-T06) + +**Recommendation:** These are the most visible credibility issues in the release +notes. Retrieve the complete text from the corresponding GitHub PR or release +tag and complete both entries. #### Information architecture +The recommendations in this section were generated by AI. + +##### 1. Add section overview pages for every major section + +**Priority: Medium — 6 new pages identified in kubevirt-anlaysis.csv** + +Every major section of the user guide (Cluster Administration, User Workloads, +Compute, Network, Storage, Debug) is missing an `overview.md` landing page. +Readers who navigate into a section from the top-level nav land directly on the +first content page with no orientation. The task analysis identified this gap +consistently (A03-T01, A04-T01, A05-T01, A06-T01, A07-T01, A10-T01): + +- `cluster_admin/overview.md` +- `user_workloads/overview.md` +- `compute/overview.md` +- `network/overview.md` +- `storage/overview.md` +- `debug_virt_stack/overview.md` + +Each overview page should: describe what the section covers, identify the target +reader (cluster admin vs. VM user), and link to the two or three most important +pages within the section. These are low-word-count pages with high impact on +navigability. + +##### 2. Add a user-facing troubleshooting page + +(virsh, QEMU strace, GDB). There is no troubleshooting page for common end-user +failures. Create `user_workloads/troubleshooting.md` covering: + +- VM stuck in Pending or CrashLoopBackOff +- Network connectivity failures from inside a VM +- CDI image import errors +- Live migration failures +- virtctl connection issues + +This is the most common support escalation path and currently has no +documentation home. + +##### 3. Fix API reference links — scheme and versioning + +**Priority: High** + +All in-guide links to the API reference use `http://` and hardcode the +`/api-reference/master/` path. Both are problems: + +- `http://` should be `https://` (security, mixed-content warnings) +- `/master/` links point to the development branch, not the version a user is + running; on older releases these links may describe non-existent fields + +Replace with `https://kubevirt.io/api-reference/` (latest stable) or, better, +introduce a versioned link macro tied to the MkDocs release variable. Surface +the API reference link in the site navigation (currently only on the Welcome +page), not just inline in prose. + +##### 4. Refactor large reference pages into focused task pages + +**Priority: Medium** + +`disks_and_volumes.md` is the largest single page in the guide and attempts to +cover conceptual explanation, reference tables, and task instructions in one +document. Split it into: + +- `disks_and_volumes/concepts.md` — what volumes and disks are, how they relate + to PVCs +- `disks_and_volumes/reference.md` — field catalog and type descriptions +- `disks_and_volumes/tasks/` — individual how-tos (attach a DataVolume, hotplug + a disk, etc.) + +Similarly, `network_binding_plugins.md` and `hook-sidecar.md` describe +architecture well but provide no end-to-end worked examples. Add at minimum one +complete task per page that a reader can follow from start to finish. + +##### 5. Add a "Coming from VMware" onboarding path + +**Priority: Medium** (High if targeting the 2024–2026 VMware migration window) + +Organizations migrating from VMware bring traditional virtualization +expectations and limited Kubernetes fluency. There is no documentation bridge. +Create a short guide that maps: + +| VMware concept | KubeVirt equivalent | Notes/gaps | +| ----------------- | --------------------------------------- | ---------- | +| vCenter / vSphere | Kubernetes API server + KubeVirt | | +| VM template | VirtualMachineInstancetype + Preference | | +| vMotion | Live migration | | +| Datastore | PVC / DataVolume (CDI) | | +| vDS / portgroup | Multus / secondary networks | | +| Snapshots | VM snapshot API | | + +Be honest about gaps (DRS-style scheduling, mature backup tooling, deep Windows +integration) — building trust with evaluators is more valuable than obscuring +shortcomings they will discover in production. + +##### 6. Create an end-to-end instancetype/preference tutorial + +**Priority: Medium** + +`instancetypes.md` and `creating_it_pref.md` describe the instancetype model but +do not walk through a complete "VM from scratch using instancetype and +preference" scenario. Add a single tutorial page that goes from defining an +instancetype and preference through creating a VM and verifying resource +allocation. This scenario represents the KubeVirt-recommended path for VM +resource management and deserves a dedicated page. + #### New user content +The recommendations in this section were generated by AI. + +##### 1. Create a self-contained "Getting Started" page + +**Priority: High** + +The current `quickstarts.md` is a curated list of four external links. It +contains no embedded steps and provides no guidance for a user without access to +Killercoda or a cloud provider. Add a page — either replacing or supplementing +the current Quickstarts — that walks through: + +1. Prerequisites check (Kubernetes cluster, kubectl, virtctl) +2. Install the KubeVirt operator (`kubectl apply`) +3. Wait for operator readiness (with expected output) +4. Create a minimal VM (copy-paste manifest provided) +5. Start the VM and connect via `virtctl console` +6. Stop and delete the VM +7. "What to read next" with three recommended follow-on pages + +This page should be completable without leaving the user guide site. + +##### 2. Expand the Basic Use page into a meaningful getting-started flow + +**Priority: Medium** (A04-B02-T01 in kubevirt-anlaysis.csv) + +`user_workloads/basic_use.md` is currently a thin page that covers VM start/stop +commands but does not walk through a meaningful first-use scenario. It is the +logical destination after Installation but does not build on it. Expand to +include: + +- The VM/VMI distinction (A04-B01-T01 — many readers do not understand that a + `VirtualMachine` manages lifecycle while a `VirtualMachineInstance` is the + running unit) +- Start, stop, restart, and migrate commands in a single reference table + (A04-B01-T03) +- How to verify the VM is running (status fields, events) +- A "What to read next" pointer to Networking and Storage pages + +This is distinct from the "Getting Started" self-contained quickstart (§1 above) +— the Basic Use page is the permanent reference for the most common operations, +while the quickstart is the narrative onboarding experience. + +##### 3. Add a common prerequisites section to Quickstarts + +**Priority: Medium** (A02-T04 in kubevirt-analysis.csv) + +The Quickstarts page links to four separate external environments but does not +list shared prerequisites. A reader needs kubectl, virtctl, and cluster access +for all of them. Add a brief prerequisites block at the top of `quickstarts.md`: + +- `kubectl` configured against a cluster +- `virtctl` plugin installed (link to virtctl_client_tool.md) +- Minimum cluster resources (RAM, CPUs) +- KubeVirt operator installed (link to installation.md) + +Also ensure the `virtctl_client_tool.md` page covers macOS and Windows install +instructions (A04-B05-T01, currently high-priority missing content) so the +prerequisites link is useful for all readers. + +##### 4. Add "What to read next" sections + +**Priority: Medium** + +The Quickstarts page and the Installation page both end without directing users +to their next logical step. Add a brief "Next steps" section to each: + +- After Quickstarts: point to User Workloads → Basic Use, and Storage → CDI +- After Installation: point to Quickstarts, then Feature Gates and Authorization + +##### 5. Add an audience orientation statement to the homepage + +**Priority: Medium** + +From the high-level review (kubevirt-reviews.md): the guide currently tries to +serve Kubernetes-native engineers and traditional VM operators simultaneously +without acknowledging either. Add a brief orientation paragraph near the top of +`index.md` that identifies who the guide is for and what prerequisite knowledge +is assumed (Kubernetes familiarity, cluster access). This sets expectations +correctly and reduces early drop-off from users who feel lost. + #### Content maintainability & site mechanics +The recommendations in this section were generated by AI. + +##### 1. Adopt doc versioning via the `mike` plugin + +**Priority: High** + +KubeVirt maintains a support matrix (latest three Kubernetes releases). Users on +older KubeVirt versions currently see docs and API reference links that reflect +the development branch, not their installed version. The MkDocs `mike` plugin +(designed for MkDocs Material + GitHub Pages) enables versioned doc sets with a +version dropdown in the header. Recommended approach: + +- Maintain the latest two KubeVirt major versions +- Mark older versions with a clear deprecation notice +- Replace hardcoded `/master/` API reference links with a version variable + +##### 2. Prepare the directory structure for localization + +**Priority: Medium** + +There is an open issue proposing Simplified Chinese (zh-CN) documentation. +Currently the directory structure does not support language subdirectories, +meaning accepting that contribution would require a structural refactor. Enable +the MkDocs Material `i18n` plugin and add a documented convention for how +language variants are organized (`docs/zh-CN/`, etc.), even if only English is +populated initially. Cost is low now; cost grows with every page added. + +##### 3. Enable analytics on the user guide + +**Priority: High** (from website analysis) + +The user guide has no analytics configured. Without analytics: + +- 404 errors cannot be detected or triaged +- High-traffic pages cannot be prioritized for quality improvement +- New user drop-off points cannot be identified + +Add a privacy-respecting analytics solution (Plausible is CNCF-friendly and +requires no cookie consent banner) via the `extra.analytics` key in +`mkdocs.yml`. Ensure preview/branch builds have indexing disabled +(`X-Robots-Tag: noindex` via Netlify headers) to avoid polluting production +analytics and search indexes. + +##### 4. Document account custodians + +**Priority: Medium** (from website analysis) + +There is no documentation of who owns the analytics account, Google Search +Console, or site-search configuration for the user guide. Add a named section to +CONTRIBUTING.md or the community repo listing the current custodians. This is a +low-effort change that prevents account access loss during maintainer +transitions. + +##### 5. Fix the sitemap URL double-slash + +**Priority: Low** + +The root `robots.txt` references the sitemap with a double slash +(`//sitemap.xml`). Correct to `https://kubevirt.io/user-guide/sitemap.xml`. + #### Content creation processes +The recommendations in this section were generated by AI. + +##### 1. Document a release-docs checklist + +**Priority: High** + +There is no documented policy requiring documentation updates as part of the +code release process. Features are regularly released without corresponding user +guide updates, and there is no doc-freeze process or release sign-off gate. Add +to `CONTRIBUTING.md` (or a new `docs/release-process.md`): + +- Which types of code changes require a user guide PR before merge +- Who is responsible for user guide completeness per release (SIG/documentation + or the feature author) +- How the sig/documentation SIG is involved in release sign-off +- What the escalation path is for undocumented features discovered post-release + +##### 2. Staff the documentation SIG + +**Priority: High** + +The `sig-list.md` in the community repo lists `sig/documentation` with no +chairs, no contact persons, and no meeting schedule. This means documentation +has no governance home, no release accountability, and no single point of +contact for the CNCF documentation review process. Nominate at least one SIG +chair and add them to the sig-list entry. Even a part-time commitment from an +existing committer is significantly better than the current vacuum. + +##### 3. Curate an active good-first-issue backlog + +**Priority: Medium** (from contributor docs review) + +The `good-first-issue` label infrastructure exists but the user-guide repo has +no open good-first issues at the time of review. New contributors who follow the +contributing guide reach a dead end. Maintain a rolling set of 3–5 small, +well-scoped documentation tasks: + +- Missing feature documentation stubs +- Broken or stale links +- Pages needing a "What to read next" section +- Prose uses of "simple"/"easy" that can be replaced + +Activate the `help-wanted` label and use it consistently as a triage step for +incoming issues. + +##### 4. Consolidate new contributor onboarding + +**Priority: Medium** (from contributor docs review) + +New contributor guidance is spread across at least four locations: +`kubevirt/kubevirt` CONTRIBUTING.md, `docs/getting-started.md`, the user-guide +Contributing page, and the community repo. Create a single "New Contributor +Guide" landing page that aggregates the full end-to-end path, and add a "Quick +Start (docs only)" path at the top for contributors who only want to fix +documentation — the current guide leads immediately into +Bazel/Docker/nested-virtualization setup that is unnecessary for documentation +contributions. + +##### 5. Establish a release notes template + +**Priority: Medium** (A08-T01 in kubevirt-anlaysis.csv) + +The `release_notes.md` file has inconsistent formatting across releases, two +incomplete entries (a truncated note, a `NONR` placeholder — see Technical Debt +§7), and no documented template for contributors. Create a release notes +template (either a comment block at the top of `release_notes.md` or a separate +`docs/release-notes-template.md`) that specifies: + +- Required sections per release (breaking changes, new features, deprecations, + bug fixes, known issues) +- How to link to the corresponding GitHub milestone +- The Kubernetes support matrix line format (several releases are missing this) +- Who is responsible for completing the notes before release tag + +This pairs with the release-docs checklist recommendation (§1 above). + #### Inclusive language +The recommendations in this section were generated by AI. + +##### 1. Replace prose uses of "simple" and "easy" + +**Priority: Low** + +Approximately 45 occurrences of "simple" or "easy" exist across 42 files. Most +are in code example resource names (acceptable) but some are in prose that can +be improved: + +| Current | Suggested replacement | +| ------------------------------------- | --------------------------------------------- | +| "a simple example" | "the following example" / "a minimal example" | +| "easy ways to fix them" | "common ways to resolve them" | +| "simplest" as a workaround descriptor | "the most direct" / "the least-invasive" | + +This is a low-effort improvement that aligns with CNCF inclusive language +guidance from the [Inclusive Naming Initiative](https://inclusivenaming.org). + +##### 2. Track the "master" API reference URL path + +**Priority: Low** + +All deep-links to the API reference use +`/api-reference/master/definitions.html`. This is the upstream API reference +site's URL structure, not a KubeVirt-owned naming choice — but it does embed a +non-recommended term in user-visible URLs. Open an issue (or add a link-checker +CI note) to flag when the upstream adopts a non-master stable URL, at which +point all deep-links can be updated in a single pass. + +#### Additional Recommendations + +The recommendations in this section were generated by AI. + +##### API developer experience + +The API developer experience deserves dedicated investment. The current user +guide is written primarily for operators ("how do I configure live migration?"), +not for developers ("what fields govern a migration policy and what are their +invariants?"). Specific actions: + +- Add the `kubevirt-api-developer-guide.md` content (or equivalent) as a formal + section of the user guide, covering the Kubernetes → KubeVirt concept mapping + table, `kubectl explain` patterns, client library usage, and + controller/operator development guidance. +- Treat the API reference as a product: ensure every CRD field has a prose + description in the OpenAPI spec (auto-populated from Go source comments), + versioned per release, linked bidirectionally from the user guide. +- Add a tracked issue for populating missing field descriptions in + `staging/src/kubevirt.io/api/core/v1/types.go` — developers currently read Go + source code to understand field intent. + +##### Website consolidation + +From the website analysis: the kubevirt.io web presence is split between +`kubevirt/kubevirt.github.io` (Jekyll, main site) and `kubevirt/user-guide` +(MkDocs, docs). These require separate contribution workflows and tooling. While +full consolidation may be a large undertaking, a near-term improvement would be +to document the two-repo split explicitly for contributors (which repo handles +which content and why), and to ensure the main site's "Documentation" navigation +link always points to the current stable user guide. + +##### Governance link visibility + +From the contributor docs review: `GOVERNANCE.md` exists in `kubevirt/community` +but is not linked from the `kubevirt/kubevirt` README or the user-guide +Contributing page. Add a direct link to governance documentation from both entry +points. Also note the maintainer concentration (majority from a single employer) +and document the project's approach to broadening representation — this is a +common CNCF due-diligence concern for graduation review. + ## Contributor documentation Section analysis generated by AI, Claude Sonnet 4.6, and includes the answers to From d7371ca8f6f953e6d8ced2fc577e95d7bcf19518 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Mon, 22 Jun 2026 01:05:40 -0700 Subject: [PATCH 17/49] fixes Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/analysis.md | 109 +++++++++++++---------------- 1 file changed, 48 insertions(+), 61 deletions(-) diff --git a/analyses/2026/kubevirt/analysis.md b/analyses/2026/kubevirt/analysis.md index cf179774..2e09c8de 100644 --- a/analyses/2026/kubevirt/analysis.md +++ b/analyses/2026/kubevirt/analysis.md @@ -562,7 +562,7 @@ editing. ### Recommendations -##### Author overall recommendations: +#### Author overall recommendations The AI results capture my recommendations except for the following pressing needs I see as a novice user: @@ -582,7 +582,7 @@ needs I see as a novice user: save a lot of time for other users to get on the right path as soon as possible. -##### AI overall recommendations: +#### AI overall recommendations The KubeVirt user guide is a substantive, professionally maintained documentation site with 94 Markdown pages covering architecture, installation, @@ -612,37 +612,22 @@ a direct adoption opportunity. Closing these documentation gaps is the highest-leverage action the project can take to convert evaluators into production users. -**A third, concrete finding comes from the page-level task analysis** -(kubevirt-analysis.csv): 266 discrete tasks were identified across 94 pages. Of -these, 66 are high-priority, 86 medium, and 114 low. The high-priority tasks +**A third, concrete finding comes from the page-level task analysis**. (kubevirt-analysis.csv): 266 discrete tasks were identified across 94 pages. Of these, 66 are high-priority, 86 medium, and 114 low. The high-priority tasks fall into five clusters — each representing a category of technical debt that erodes reader trust independently of any structural improvement: -| Cluster | High-pri task count | Examples | -| ------------------------------------------ | ------------------- | -------------------------------------------------------------------------- | -| Unofficial/internal dev images in examples | 17 | `kubevirt/fedora-cloud-container-disk-demo`, internal registry refs | -| Broken or stale links | 15 | Broken bridge link in live_migration.md, stale OKD 3.9 link | -| Outdated or removed content | 11 | `--delete-local-data` flag, `--admission-control`, pre-v0.34 taint notes | -| Deprecated API references | 6 | `spec.running`, `rbac.authorization.k8s.io/v1beta1`, OKD openshift-ansible | -| User-visible typos in code | 6 | (see csv file) | +| Cluster | High-pri task count | Examples | +| ------------------------------------------ | ---| -----------------------| +| Unofficial/internal dev images in examples | 17 | internal registry refs | +| Broken or stale links | 15 | Broken bridge link | +| Outdated or removed content | 11 | `--delete-local-data` flag | +| Deprecated API references | 6 | `spec.running` | +| User-visible typos in code | 6 | (see csv file) | These are independent of audience targeting or architecture improvements — they are factual errors and broken examples that any reader can encounter today. They should be addressed before or alongside any larger structural work. -**Summary scores across all rubric areas:** - -| Area | Rating (1–5) | Primary Gap | -| ---------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------ | -| Information architecture | 3 | No self-contained happy path; missing user-facing troubleshooting; no section overview pages | -| New user content | 3 | Quickstarts delegates entirely to external content; Basic Use page too thin | -| Content maintainability & site mechanics | 2 | No versioning, no localization framework | -| Content creation processes | 3 | No release-gating on docs; documentation SIG un-staffed; no release notes template | -| Inclusive language | 3 | Occasional "simple"/"easy" in prose; "master" in API links | -| Website & infrastructure | 2–4 (varies) | No analytics, no preview-build noindex, no account custodians | -| Contributor experience | 3 | Onboarding info spread across four repos; no active good-first-issues | -| **Technical debt (accuracy)** | **2** | **17 unofficial images, 15 broken links, 11 outdated sections, 6 deprecated APIs, 6 code typos** | - #### Technical Debt & Content Accuracy This Technical Debt & Content Accuracy section is a proposed template change and @@ -683,7 +668,7 @@ to prevent regressions. ##### 2. Fix broken and stale links -**Priority: High — 15 occurrences across 10+ files** +> Priority: High — 15 occurrences across 10+ files Broken links identified include: @@ -707,7 +692,7 @@ Information Architecture §2) — a single pass replaces all of them. ##### 3. Remove or update deprecated API references -**Priority: High — 6 occurrences across 5 files** +> Priority: High — 6 occurrences across 5 files - `spec.running` field references throughout `architecture.md` (A01-T02) — deprecated in favor of `spec.runStrategy` @@ -731,7 +716,7 @@ as it actively misleads users into using a feature that is being removed. ##### 4. Fix user-visible typos in code and API field names -**Priority: High — 6 occurrences, some in copy-pasteable code** +> Priority: High — 6 occurrences, some in copy-pasteable code (see CSV file) @@ -741,7 +726,7 @@ verbatim and then debug why their manifest doesn't work. ##### 5. Remove or archive outdated historical content -**Priority: High/Medium — 11 occurrences** +> Priority: High/Medium — 11 occurrences Sections describing behavior specific to unsupported releases confuse readers on current versions and signal that the docs are not maintained: @@ -753,8 +738,7 @@ current versions and signal that the docs are not maintained: (A05-B06-T03) - "Future release" language in `cluster_admin/installation.md` AppArmor section (A03-B01-T01) — the referenced issue may already be resolved -- "Future release" language in `compute/persistent_tpm_and_uefi_state.md` - (A05-B14-T01) +- "Future release" language in (A05-B14-T01) - `--delete-local-data` flag (deprecated in kubectl 1.20, removed in 1.27) in `cluster_admin/node_maintenance.md` (A03-B12-T01) - OKD Service Catalog APB section in `cluster_admin/installation.md` @@ -769,15 +753,15 @@ or OKD versions that are no longer in the support matrix. ##### 6. Fix the JSON syntax error in the passt registration example -**Priority: High — 1 occurrence** +> Priority: High — 1 occurrence -(A06-B04-T01) See sheet for a JSON syntax error in the passt plugin registration +(A06-B04-T01) See sheet for a JSON syntax error in the plugin registration example. A reader following this example will get an error with no indication the source is the doc. Fix immediately. ##### 7. Complete truncated and placeholder release notes entries -**Priority: High/Medium — 2 occurrences** +> Priority: High/Medium — 2 occurrences - The `KubeVirtVMGuestMemoryPressure` entry in `release_notes.md` is truncated mid-sentence (A08-B01-T05) @@ -793,7 +777,7 @@ The recommendations in this section were generated by AI. ##### 1. Add section overview pages for every major section -**Priority: Medium — 6 new pages identified in kubevirt-anlaysis.csv** +> Priority: Medium — 6 new pages identified in kubevirt-analysis.csv Every major section of the user guide (Cluster Administration, User Workloads, Compute, Network, Storage, Debug) is missing an `overview.md` landing page. @@ -829,7 +813,7 @@ documentation home. ##### 3. Fix API reference links — scheme and versioning -**Priority: High** +> Priority: High All in-guide links to the API reference use `http://` and hardcode the `/api-reference/master/` path. Both are problems: @@ -845,7 +829,7 @@ page), not just inline in prose. ##### 4. Refactor large reference pages into focused task pages -**Priority: Medium** +> Priority: Medium `disks_and_volumes.md` is the largest single page in the guide and attempts to cover conceptual explanation, reference tables, and task instructions in one @@ -863,7 +847,7 @@ complete task per page that a reader can follow from start to finish. ##### 5. Add a "Coming from VMware" onboarding path -**Priority: Medium** (High if targeting the 2024–2026 VMware migration window) +> Priority: Medium (High if targeting the 2024–2026 VMware migration window) Organizations migrating from VMware bring traditional virtualization expectations and limited Kubernetes fluency. There is no documentation bridge. @@ -884,7 +868,7 @@ shortcomings they will discover in production. ##### 6. Create an end-to-end instancetype/preference tutorial -**Priority: Medium** +> Priority: Medium `instancetypes.md` and `creating_it_pref.md` describe the instancetype model but do not walk through a complete "VM from scratch using instancetype and @@ -899,7 +883,7 @@ The recommendations in this section were generated by AI. ##### 1. Create a self-contained "Getting Started" page -**Priority: High** +> Priority: High The current `quickstarts.md` is a curated list of four external links. It contains no embedded steps and provides no guidance for a user without access to @@ -918,7 +902,7 @@ This page should be completable without leaving the user guide site. ##### 2. Expand the Basic Use page into a meaningful getting-started flow -**Priority: Medium** (A04-B02-T01 in kubevirt-anlaysis.csv) +> Priority: Medium (A04-B02-T01 in kubevirt-analysis.csv) `user_workloads/basic_use.md` is currently a thin page that covers VM start/stop commands but does not walk through a meaningful first-use scenario. It is the @@ -939,7 +923,7 @@ while the quickstart is the narrative onboarding experience. ##### 3. Add a common prerequisites section to Quickstarts -**Priority: Medium** (A02-T04 in kubevirt-analysis.csv) +> Priority: Medium (A02-T04 in kubevirt-analysis.csv) The Quickstarts page links to four separate external environments but does not list shared prerequisites. A reader needs kubectl, virtctl, and cluster access @@ -956,7 +940,7 @@ prerequisites link is useful for all readers. ##### 4. Add "What to read next" sections -**Priority: Medium** +> Priority: Medium The Quickstarts page and the Installation page both end without directing users to their next logical step. Add a brief "Next steps" section to each: @@ -966,7 +950,7 @@ to their next logical step. Add a brief "Next steps" section to each: ##### 5. Add an audience orientation statement to the homepage -**Priority: Medium** +> Priority: Medium From the high-level review (kubevirt-reviews.md): the guide currently tries to serve Kubernetes-native engineers and traditional VM operators simultaneously @@ -981,7 +965,7 @@ The recommendations in this section were generated by AI. ##### 1. Adopt doc versioning via the `mike` plugin -**Priority: High** +> Priority: High KubeVirt maintains a support matrix (latest three Kubernetes releases). Users on older KubeVirt versions currently see docs and API reference links that reflect @@ -995,7 +979,7 @@ version dropdown in the header. Recommended approach: ##### 2. Prepare the directory structure for localization -**Priority: Medium** +> Priority: Medium There is an open issue proposing Simplified Chinese (zh-CN) documentation. Currently the directory structure does not support language subdirectories, @@ -1006,7 +990,7 @@ populated initially. Cost is low now; cost grows with every page added. ##### 3. Enable analytics on the user guide -**Priority: High** (from website analysis) +> Priority: High (from website analysis) The user guide has no analytics configured. Without analytics: @@ -1022,7 +1006,7 @@ analytics and search indexes. ##### 4. Document account custodians -**Priority: Medium** (from website analysis) +> Priority: Medium (from website analysis) There is no documentation of who owns the analytics account, Google Search Console, or site-search configuration for the user guide. Add a named section to @@ -1032,7 +1016,7 @@ transitions. ##### 5. Fix the sitemap URL double-slash -**Priority: Low** +> Priority: Low The root `robots.txt` references the sitemap with a double slash (`//sitemap.xml`). Correct to `https://kubevirt.io/user-guide/sitemap.xml`. @@ -1043,7 +1027,7 @@ The recommendations in this section were generated by AI. ##### 1. Document a release-docs checklist -**Priority: High** +> Priority: High There is no documented policy requiring documentation updates as part of the code release process. Features are regularly released without corresponding user @@ -1058,7 +1042,7 @@ to `CONTRIBUTING.md` (or a new `docs/release-process.md`): ##### 2. Staff the documentation SIG -**Priority: High** +> Priority: High The `sig-list.md` in the community repo lists `sig/documentation` with no chairs, no contact persons, and no meeting schedule. This means documentation @@ -1069,7 +1053,7 @@ existing committer is significantly better than the current vacuum. ##### 3. Curate an active good-first-issue backlog -**Priority: Medium** (from contributor docs review) +> Priority: Medium (from contributor docs review) The `good-first-issue` label infrastructure exists but the user-guide repo has no open good-first issues at the time of review. New contributors who follow the @@ -1086,7 +1070,7 @@ incoming issues. ##### 4. Consolidate new contributor onboarding -**Priority: Medium** (from contributor docs review) +> Priority: Medium (from contributor docs review) New contributor guidance is spread across at least four locations: `kubevirt/kubevirt` CONTRIBUTING.md, `docs/getting-started.md`, the user-guide @@ -1099,10 +1083,10 @@ contributions. ##### 5. Establish a release notes template -**Priority: Medium** (A08-T01 in kubevirt-anlaysis.csv) +> Priority: Medium (A08-T01 in kubevirt-analysis.csv) The `release_notes.md` file has inconsistent formatting across releases, two -incomplete entries (a truncated note, a `NONR` placeholder — see Technical Debt +incomplete entries (a truncated note, a placeholder — see Technical Debt §7), and no documented template for contributors. Create a release notes template (either a comment block at the top of `release_notes.md` or a separate `docs/release-notes-template.md`) that specifies: @@ -1121,7 +1105,7 @@ The recommendations in this section were generated by AI. ##### 1. Replace prose uses of "simple" and "easy" -**Priority: Low** +> Priority: Low Approximately 45 occurrences of "simple" or "easy" exist across 42 files. Most are in code example resource names (acceptable) but some are in prose that can @@ -1138,7 +1122,7 @@ guidance from the [Inclusive Naming Initiative](https://inclusivenaming.org). ##### 2. Track the "master" API reference URL path -**Priority: Low** +> Priority: Low All deep-links to the API reference use `/api-reference/master/definitions.html`. This is the upstream API reference @@ -1216,6 +1200,8 @@ Contributor Documentation rubric. > these criteria. Keep in mind that much of the contributor documentation might > be contained in the documentation repository. +The answers and rating paragraphs in this section were generated by AI: + #### Communication methods documented One of the easiest ways to attract new contributors is making sure they know how @@ -1337,10 +1323,11 @@ We evaluate on the following: - Is project governance clearly documented? -### Recommendations +**Answer:** Yes. KubeVirt's governance documentation is comprehensive and well-structured in the `kubevirt/community` repository — covering maintainer roles, SIG/WG charters, a contributor ladder, voting rules, and active maintainer/emeritus lists. The primary gap is discoverability: the main `kubevirt/kubevirt` repository does not link to `GOVERNANCE.md` directly. + +##### Recommendations -> AUTHOR NOTE: Write general recommendations based on the comments from the -> previous section. +KubeVirt's governance documentation is comprehensive and well-structured in the `kubevirt/community` repository — covering maintainer roles, SIG/WG charters, a contributor ladder, voting rules, and active maintainer/emeritus lists. The primary gap is discoverability: the main `kubevirt/kubevirt` repository does not link to `GOVERNANCE.md` directly. #### Communication methods documented @@ -1350,7 +1337,7 @@ and CONTRIBUTING.md, but discoverability from the main website and the did not render meaningful content during evaluation, which is a missed opportunity for new visitors. -**Recommendations:** +##### Recommendations - Add a visible "Community" section to the `kubevirt/kubevirt` README (or expand the existing one) that lists Slack channels with direct join links, the From 78883607bd377efaa8524dba11c97f3ad5fbf2a8 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Mon, 22 Jun 2026 01:31:33 -0700 Subject: [PATCH 18/49] spelling and formatting Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/analysis.md | 50 ++++++++++++++++++------------ 1 file changed, 30 insertions(+), 20 deletions(-) diff --git a/analyses/2026/kubevirt/analysis.md b/analyses/2026/kubevirt/analysis.md index 2e09c8de..ae34b524 100644 --- a/analyses/2026/kubevirt/analysis.md +++ b/analyses/2026/kubevirt/analysis.md @@ -612,17 +612,19 @@ a direct adoption opportunity. Closing these documentation gaps is the highest-leverage action the project can take to convert evaluators into production users. -**A third, concrete finding comes from the page-level task analysis**. (kubevirt-analysis.csv): 266 discrete tasks were identified across 94 pages. Of these, 66 are high-priority, 86 medium, and 114 low. The high-priority tasks +**A third, concrete finding comes from the page-level task analysis**. +(kubevirt-analysis.csv): 266 discrete tasks were identified across 94 pages. Of +these, 66 are high-priority, 86 medium, and 114 low. The high-priority tasks fall into five clusters — each representing a category of technical debt that erodes reader trust independently of any structural improvement: -| Cluster | High-pri task count | Examples | -| ------------------------------------------ | ---| -----------------------| -| Unofficial/internal dev images in examples | 17 | internal registry refs | -| Broken or stale links | 15 | Broken bridge link | -| Outdated or removed content | 11 | `--delete-local-data` flag | -| Deprecated API references | 6 | `spec.running` | -| User-visible typos in code | 6 | (see csv file) | +| Cluster | High-pri tasks | +| ------------------------------------------ | -------------- | +| Unofficial/internal dev images in examples | 17 | +| Broken or stale links | 15 | +| Outdated or removed content | 11 | +| Deprecated API references | 6 | +| User-visible typos in code | 6 | These are independent of audience targeting or architecture improvements — they are factual errors and broken examples that any reader can encounter today. They @@ -647,7 +649,7 @@ production has reason to distrust the entire page. ##### 1. Replace unofficial and internal dev images in examples -**Priority: High — 17 occurrences across 11+ files** +> Priority: High — 17 occurrences across 11+ files Multiple pages embed container image references from internal development registries or personal/unofficial namespaces that readers cannot pull: @@ -751,7 +753,7 @@ issue is resolved). Others (pre-v0.20 notes, `--delete-local-data`, OKD APB) can be deleted without verification — they describe behavior removed in Kubernetes or OKD versions that are no longer in the support matrix. -##### 6. Fix the JSON syntax error in the passt registration example +##### 6. Fix the JSON syntax error in the registration example > Priority: High — 1 occurrence @@ -1086,9 +1088,9 @@ contributions. > Priority: Medium (A08-T01 in kubevirt-analysis.csv) The `release_notes.md` file has inconsistent formatting across releases, two -incomplete entries (a truncated note, a placeholder — see Technical Debt -§7), and no documented template for contributors. Create a release notes -template (either a comment block at the top of `release_notes.md` or a separate +incomplete entries (a truncated note, a placeholder — see Technical Debt §7), +and no documented template for contributors. Create a release notes template +(either a comment block at the top of `release_notes.md` or a separate `docs/release-notes-template.md`) that specifies: - Required sections per release (breaking changes, new features, deprecations, @@ -1111,11 +1113,11 @@ Approximately 45 occurrences of "simple" or "easy" exist across 42 files. Most are in code example resource names (acceptable) but some are in prose that can be improved: -| Current | Suggested replacement | -| ------------------------------------- | --------------------------------------------- | -| "a simple example" | "the following example" / "a minimal example" | -| "easy ways to fix them" | "common ways to resolve them" | -| "simplest" as a workaround descriptor | "the most direct" / "the least-invasive" | +| Current | Suggested replacement | +| ----------------------- | -------------------------------------------- | +| "a simple example" | "the following example", "a minimal example" | +| "easy ways to fix them" | "common ways to resolve them" | +| "simplest" | "the most direct" / "the least-invasive" | This is a low-effort improvement that aligns with CNCF inclusive language guidance from the [Inclusive Naming Initiative](https://inclusivenaming.org). @@ -1323,11 +1325,19 @@ We evaluate on the following: - Is project governance clearly documented? -**Answer:** Yes. KubeVirt's governance documentation is comprehensive and well-structured in the `kubevirt/community` repository — covering maintainer roles, SIG/WG charters, a contributor ladder, voting rules, and active maintainer/emeritus lists. The primary gap is discoverability: the main `kubevirt/kubevirt` repository does not link to `GOVERNANCE.md` directly. +**Answer:** Yes. KubeVirt's governance documentation is comprehensive and +well-structured in the `kubevirt/community` repository — covering maintainer +roles, SIG/WG charters, a contributor ladder, voting rules, and active +maintainer/emeritus lists. The primary gap is discoverability: the main +`kubevirt/kubevirt` repository does not link to `GOVERNANCE.md` directly. ##### Recommendations -KubeVirt's governance documentation is comprehensive and well-structured in the `kubevirt/community` repository — covering maintainer roles, SIG/WG charters, a contributor ladder, voting rules, and active maintainer/emeritus lists. The primary gap is discoverability: the main `kubevirt/kubevirt` repository does not link to `GOVERNANCE.md` directly. +KubeVirt's governance documentation is comprehensive and well-structured in the +`kubevirt/community` repository — covering maintainer roles, SIG/WG charters, a +contributor ladder, voting rules, and active maintainer/emeritus lists. The +primary gap is discoverability: the main `kubevirt/kubevirt` repository does not +link to `GOVERNANCE.md` directly. #### Communication methods documented From c3f2782b52be60432c2659734bd421aef013b3aa Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Mon, 22 Jun 2026 22:14:51 -0700 Subject: [PATCH 19/49] format fixes Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/analysis.md | 32 +++++++++++------------------- 1 file changed, 12 insertions(+), 20 deletions(-) diff --git a/analyses/2026/kubevirt/analysis.md b/analyses/2026/kubevirt/analysis.md index ae34b524..7dd3da56 100644 --- a/analyses/2026/kubevirt/analysis.md +++ b/analyses/2026/kubevirt/analysis.md @@ -1,7 +1,7 @@ --- -title: KubeVirtDocumentation Analysis +title: KubeVirt Documentation Analysis created: 2026-05-24 -modified: 2026-06-21 +modified: 2026-06-22 author: Bruce Hamilton --- @@ -1099,7 +1099,7 @@ and no documented template for contributors. Create a release notes template - The Kubernetes support matrix line format (several releases are missing this) - Who is responsible for completing the notes before release tag -This pairs with the release-docs checklist recommendation (§1 above). +This pairs with the release-docs checklist recommendation (#1 above). #### Inclusive language @@ -1331,23 +1331,7 @@ roles, SIG/WG charters, a contributor ladder, voting rules, and active maintainer/emeritus lists. The primary gap is discoverability: the main `kubevirt/kubevirt` repository does not link to `GOVERNANCE.md` directly. -##### Recommendations - -KubeVirt's governance documentation is comprehensive and well-structured in the -`kubevirt/community` repository — covering maintainer roles, SIG/WG charters, a -contributor ladder, voting rules, and active maintainer/emeritus lists. The -primary gap is discoverability: the main `kubevirt/kubevirt` repository does not -link to `GOVERNANCE.md` directly. - -#### Communication methods documented - -KubeVirt documents its communication channels thoroughly in the community repo -and CONTRIBUTING.md, but discoverability from the main website and the -`kubevirt/kubevirt` README could be improved. The `kubevirt.io/community/` page -did not render meaningful content during evaluation, which is a missed -opportunity for new visitors. - -##### Recommendations +### Recommendations - Add a visible "Community" section to the `kubevirt/kubevirt` README (or expand the existing one) that lists Slack channels with direct join links, the @@ -1359,6 +1343,14 @@ opportunity for new visitors. prominently on the user-guide Contributing page (currently only mentioned in passing with no direct join URL). +#### Communication methods documented + +KubeVirt documents its communication channels thoroughly in the community repo +and CONTRIBUTING.md, but discoverability from the main website and the +`kubevirt/kubevirt` README could be improved. The `kubevirt.io/community/` page +did not render meaningful content during evaluation, which is a missed +opportunity for new visitors. + #### Beginner friendly issue backlog The `good-first-issue` label infrastructure exists and is referenced in the From 1c2c36dec2be73b7df98db65419213b5f61fa623 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 24 Jun 2026 18:44:45 -0700 Subject: [PATCH 20/49] moved content to appendix, structure fixes Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/analysis.md | 400 +++++++++++++++-------------- 1 file changed, 205 insertions(+), 195 deletions(-) diff --git a/analyses/2026/kubevirt/analysis.md b/analyses/2026/kubevirt/analysis.md index 7dd3da56..f9f2c54a 100644 --- a/analyses/2026/kubevirt/analysis.md +++ b/analyses/2026/kubevirt/analysis.md @@ -134,9 +134,7 @@ Documentation rubric. This section includes AI observations generated from Claude Sonnet 4.6 and are indicated as AI. -#### Overall comments - -Author comments: +#### Overall comments - Author The KubeVirt has a well-thought out structure that can accommodate improvements without having to restructure sections on a wide basis. @@ -145,22 +143,6 @@ The Welcome page has long lines in bullets could be better formatted for readability and scanning. See the rest of overall comments by the Author in the next section, "Comments of KubeVirt documentation sections." -AI comments: - -The KubeVirt user guide is a comprehensive, well-organized documentation site -covering architecture, installation, cluster administration, user workloads, -compute, networking, storage, debugging, and release notes — 94 Markdown pages -in total, served via MkDocs Material at `kubevirt.io/user-guide/`. - -The breadth of topics is good for an incubating project. Key gaps include the -lack of versioned documentation, no localization framework, no self-contained -getting started path, and an externally-hosted API reference that is only -loosely integrated with the user guide. - -(end AI comments) - -#### Comments of KubeVirt documentation sections - The following observations are author observations on the KubeVirt documentation (https://kubevirt.io/user-guide) by its sections as shown on the top navigation bar. @@ -255,6 +237,20 @@ Virtualization Debugging: - Overview needs examples of debugging scenarios. +#### Overall comments - AI + +The KubeVirt user guide is a comprehensive, well-organized documentation site +covering architecture, installation, cluster administration, user workloads, +compute, networking, storage, debugging, and release notes — 94 Markdown pages +in total, served via MkDocs Material at `kubevirt.io/user-guide/`. + +The breadth of topics is good for an incubating project. Key gaps include the +lack of versioned documentation, no localization framework, no self-contained +getting started path, and an externally-hosted API reference that is only +loosely integrated with the user guide. + +(end AI comments) + #### Information architecture The overall structure (pages/subpages/sections/subsections) of your project @@ -562,27 +558,37 @@ editing. ### Recommendations -#### Author overall recommendations +#### Overall recommendations - Author The AI results capture my recommendations except for the following pressing needs I see as a novice user: -- Guidance and frank advice about using a virtual machine to on a Windows or - MacOS to then use a virtual machine in KubeVirt. This VM within a VM is nested +- Risks of embedded virtualization + + Guidance and frank advice about using a virtual machine on a Windows or MacOS + to then use a virtual machine in KubeVirt. This VM within a VM is nested virtualization and is a key concept for getting to understand KubeVirt. Users who have a Linux machine don't need to worry about nested virtualization. In addition, VMs on Windows and MacOS are usually transitory, requiring the reinstall of clusters, tools, and KubeVirt. This guidance should be in the top overview or getting started section. -- The AI results include having a common prerequisites topic, but at a higher +- Add a Roadmap topic + + The AI results include having a common prerequisites topic, but at a higher level a Roadmap topic or subsection of Getting Started should provide guidance for different user scenarios to decide whether to use a VM in Windows or invest in a Linux computer. While this isn't pertinent to develops, it will save a lot of time for other users to get on the right path as soon as possible. -#### AI overall recommendations +- Add architectural diagrams + + Diagrams should be updated in the Architecture topic and added to Quickstarts + and Getting Started content and ideally for each major section. Mermaid code + is recommended and be created initially by AI. + +#### Overall recommendations - AI The KubeVirt user guide is a substantive, professionally maintained documentation site with 94 Markdown pages covering architecture, installation, @@ -630,154 +636,13 @@ These are independent of audience targeting or architecture improvements — the are factual errors and broken examples that any reader can encounter today. They should be addressed before or alongside any larger structural work. -#### Technical Debt & Content Accuracy - -This Technical Debt & Content Accuracy section is a proposed template change and -was generated by AI. - -> These tasks described for Technical Debt & Content Accuracy are sourced -> directly from kubevirt-analysis.csv. The 266 tasks in that file are intended -> for SME triage and GitHub issue creation. The recommendations below describe -> the patterns and priorities at a level useful for project planning; individual -> task details (node IDs, file paths, specific fixes) are in the CSV. - -This is the most immediately actionable area. No structural change is required — -each item is a concrete, bounded fix in a known file. Taken together, they -represent a systematic erosion of reader trust: a reader who hits a broken link, -an image that won't pull, or a typo in a field name they're about to paste into -production has reason to distrust the entire page. - -##### 1. Replace unofficial and internal dev images in examples - -> Priority: High — 17 occurrences across 11+ files - -Multiple pages embed container image references from internal development -registries or personal/unofficial namespaces that readers cannot pull: - -- `kubevirt/fedora-cloud-container-disk-demo` (user_workloads, network, storage - pages). -- Internal registry paths (confidential_computing.md, host-devices.md, debug - strace pages). -- Unofficial CirrOS images (run_strategies.md, dns.md, service_objects.md). -- Dev sidecar/shim images (launch-qemu-strace.md). - -**Recommendation:** Establish a canonical set of public, stable container images -for documentation examples (e.g., `quay.io/kubevirt/cirros-container-disk-demo`, -official Fedora Cloud images). Run a single sweep replacing all unofficial -references in one PR, then add a CI linting rule (e.g., a grep check on -`registry.k8s.io` or known internal registry host names in Markdown code blocks) -to prevent regressions. - -##### 2. Fix broken and stale links - -> Priority: High — 15 occurrences across 10+ files - -Broken links identified include: - -- Bridge interface link in `compute/live_migration.md` (A05-B06-T01) -- Cross-link to live migration prerequisites from - `cluster_admin/tekton_tasks.md` (A03-B14-T01) -- Stale OKD 3.9 documentation link in `compute/hugepages.md` (A05-B05-T02) -- Feature-gate links using absolute paths in `network/hotplug/interfaces.md` - (A06-B07-T01) and `network/hotplug/nad_reference.md` (A06-B08-T02) -- Stale golang tour URL in `contributing.md` (A09-B01-T01) -- `master`-branch API reference links in `network/interfaces_and_networks.md`, - `storage/disks_and_volumes.md`, and `debug_virt_stack/debug.md` -- Stale cross-link using old `operations/` path in `debug_virt_stack/logging.md` - (A10-B02-T01) -- DNS resolver spec link in `network/dns.md` (A06-B01-T01) - -**Recommendation:** Run `make check_links` on a CI schedule (not just on PR) and -treat link failures as blocking. For the `master`-branch API reference links, -this is the same fix as the broader API link scheme recommendation (see -Information Architecture §2) — a single pass replaces all of them. - -##### 3. Remove or update deprecated API references - -> Priority: High — 6 occurrences across 5 files - -- `spec.running` field references throughout `architecture.md` (A01-T02) — - deprecated in favor of `spec.runStrategy` -- `rbac.authorization.k8s.io/v1beta1` API version in - `user_workloads/accessing_virtual_machines.md` (A04-B06-T01) — removed in - Kubernetes 1.25 -- `--admission-control` flag (replaced by `--enable-admission-plugins`) in - `cluster_admin/api_validation.md` (A03-B05-T01) -- OKD `openshift-ansible` references in `cluster_admin/api_validation.md` - (A03-B05-T02) -- `instancetype.kubevirt.io` API stability status note in - `user_workloads/instancetypes.md` (A04-B15-T01) — may have been promoted to - stable -- Missing deprecation notice on `user_workloads/presets.md` (A04-B18-T01) — - Presets are deprecated in favor of Instancetypes - -**Recommendation:** Each of these is a high-confidence fix that does not require -SME judgment — they are factually wrong or out of date. Batch into a single -"deprecated API cleanup" PR. Add the Presets deprecation admonition immediately -as it actively misleads users into using a feature that is being removed. - -##### 4. Fix user-visible typos in code and API field names - -> Priority: High — 6 occurrences, some in copy-pasteable code - -(see CSV file) - -**Recommendation:** Fix all in a single PR — these are unambiguous one-line -changes. The field name typos are especially damaging because users copy them -verbatim and then debug why their manifest doesn't work. - -##### 5. Remove or archive outdated historical content - -> Priority: High/Medium — 11 occurrences - -Sections describing behavior specific to unsupported releases confuse readers on -current versions and signal that the docs are not maintained: - -- Pre-v0.20.0 and pre-v0.34.2 version-specific notes in - `cluster_admin/installation.md` (A03-B01-T02) -- Pre-v0.34 taint note in `cluster_admin/node_maintenance.md` (A03-B12-T03) -- Pre-v0.56 feature gate enablement note in `compute/live_migration.md` - (A05-B06-T03) -- "Future release" language in `cluster_admin/installation.md` AppArmor section - (A03-B01-T01) — the referenced issue may already be resolved -- "Future release" language in (A05-B14-T01) -- `--delete-local-data` flag (deprecated in kubectl 1.20, removed in 1.27) in - `cluster_admin/node_maintenance.md` (A03-B12-T01) -- OKD Service Catalog APB section in `cluster_admin/installation.md` - (A03-B01-T03) — the Service Catalog was removed from OKD years ago -- Outdated OKD `openshift-ansible` section in `cluster_admin/api_validation.md` - (A03-B05-T02) - -**Recommendation:** SME review required for some (e.g., whether the AppArmor -issue is resolved). Others (pre-v0.20 notes, `--delete-local-data`, OKD APB) can -be deleted without verification — they describe behavior removed in Kubernetes -or OKD versions that are no longer in the support matrix. - -##### 6. Fix the JSON syntax error in the registration example - -> Priority: High — 1 occurrence - -(A06-B04-T01) See sheet for a JSON syntax error in the plugin registration -example. A reader following this example will get an error with no indication -the source is the doc. Fix immediately. - -##### 7. Complete truncated and placeholder release notes entries - -> Priority: High/Medium — 2 occurrences - -- The `KubeVirtVMGuestMemoryPressure` entry in `release_notes.md` is truncated - mid-sentence (A08-B01-T05) -- A placeholder appears in place of a real release note (A08-B01-T06) - -**Recommendation:** These are the most visible credibility issues in the release -notes. Retrieve the complete text from the corresponding GitHub PR or release -tag and complete both entries. - #### Information architecture -The recommendations in this section were generated by AI. +##### Information Architecture Recommendations - Author -##### 1. Add section overview pages for every major section +##### Information Architecture Recommendations - AI + +1. Add section overview pages for every major section > Priority: Medium — 6 new pages identified in kubevirt-analysis.csv @@ -799,7 +664,7 @@ reader (cluster admin vs. VM user), and link to the two or three most important pages within the section. These are low-word-count pages with high impact on navigability. -##### 2. Add a user-facing troubleshooting page +2. Add a user-facing troubleshooting page (virsh, QEMU strace, GDB). There is no troubleshooting page for common end-user failures. Create `user_workloads/troubleshooting.md` covering: @@ -813,7 +678,7 @@ failures. Create `user_workloads/troubleshooting.md` covering: This is the most common support escalation path and currently has no documentation home. -##### 3. Fix API reference links — scheme and versioning +3. Fix API reference links — scheme and versioning > Priority: High @@ -829,7 +694,7 @@ introduce a versioned link macro tied to the MkDocs release variable. Surface the API reference link in the site navigation (currently only on the Welcome page), not just inline in prose. -##### 4. Refactor large reference pages into focused task pages +4. Refactor large reference pages into focused task pages > Priority: Medium @@ -847,7 +712,7 @@ Similarly, `network_binding_plugins.md` and `hook-sidecar.md` describe architecture well but provide no end-to-end worked examples. Add at minimum one complete task per page that a reader can follow from start to finish. -##### 5. Add a "Coming from VMware" onboarding path +5. Add a "Coming from VMware" onboarding path > Priority: Medium (High if targeting the 2024–2026 VMware migration window) @@ -868,7 +733,7 @@ Be honest about gaps (DRS-style scheduling, mature backup tooling, deep Windows integration) — building trust with evaluators is more valuable than obscuring shortcomings they will discover in production. -##### 6. Create an end-to-end instancetype/preference tutorial +6. Create an end-to-end instancetype/preference tutorial > Priority: Medium @@ -881,9 +746,13 @@ resource management and deserves a dedicated page. #### New user content +##### New user content Recommendations - Author + +##### New user Recommendations - AI + The recommendations in this section were generated by AI. -##### 1. Create a self-contained "Getting Started" page +1. Create a self-contained "Getting Started" page > Priority: High @@ -902,7 +771,7 @@ the current Quickstarts — that walks through: This page should be completable without leaving the user guide site. -##### 2. Expand the Basic Use page into a meaningful getting-started flow +2. Expand the Basic Use page into a meaningful getting-started flow > Priority: Medium (A04-B02-T01 in kubevirt-analysis.csv) @@ -923,7 +792,7 @@ This is distinct from the "Getting Started" self-contained quickstart (§1 above — the Basic Use page is the permanent reference for the most common operations, while the quickstart is the narrative onboarding experience. -##### 3. Add a common prerequisites section to Quickstarts +3. Add a common prerequisites section to Quickstarts > Priority: Medium (A02-T04 in kubevirt-analysis.csv) @@ -940,7 +809,7 @@ Also ensure the `virtctl_client_tool.md` page covers macOS and Windows install instructions (A04-B05-T01, currently high-priority missing content) so the prerequisites link is useful for all readers. -##### 4. Add "What to read next" sections +4. Add "What to read next" sections > Priority: Medium @@ -950,7 +819,7 @@ to their next logical step. Add a brief "Next steps" section to each: - After Quickstarts: point to User Workloads → Basic Use, and Storage → CDI - After Installation: point to Quickstarts, then Feature Gates and Authorization -##### 5. Add an audience orientation statement to the homepage +5. Add an audience orientation statement to the homepage > Priority: Medium @@ -965,7 +834,7 @@ correctly and reduces early drop-off from users who feel lost. The recommendations in this section were generated by AI. -##### 1. Adopt doc versioning via the `mike` plugin +1. Adopt doc versioning via the `mike` plugin > Priority: High @@ -979,7 +848,7 @@ version dropdown in the header. Recommended approach: - Mark older versions with a clear deprecation notice - Replace hardcoded `/master/` API reference links with a version variable -##### 2. Prepare the directory structure for localization +2. Prepare the directory structure for localization > Priority: Medium @@ -990,7 +859,7 @@ the MkDocs Material `i18n` plugin and add a documented convention for how language variants are organized (`docs/zh-CN/`, etc.), even if only English is populated initially. Cost is low now; cost grows with every page added. -##### 3. Enable analytics on the user guide +3. Enable analytics on the user guide > Priority: High (from website analysis) @@ -1006,7 +875,7 @@ requires no cookie consent banner) via the `extra.analytics` key in (`X-Robots-Tag: noindex` via Netlify headers) to avoid polluting production analytics and search indexes. -##### 4. Document account custodians +4. Document account custodians > Priority: Medium (from website analysis) @@ -1016,7 +885,7 @@ CONTRIBUTING.md or the community repo listing the current custodians. This is a low-effort change that prevents account access loss during maintainer transitions. -##### 5. Fix the sitemap URL double-slash +5. Fix the sitemap URL double-slash > Priority: Low @@ -1027,7 +896,7 @@ The root `robots.txt` references the sitemap with a double slash The recommendations in this section were generated by AI. -##### 1. Document a release-docs checklist +1. Document a release-docs checklist > Priority: High @@ -1042,7 +911,7 @@ to `CONTRIBUTING.md` (or a new `docs/release-process.md`): - How the sig/documentation SIG is involved in release sign-off - What the escalation path is for undocumented features discovered post-release -##### 2. Staff the documentation SIG +2. Staff the documentation SIG > Priority: High @@ -1053,7 +922,7 @@ contact for the CNCF documentation review process. Nominate at least one SIG chair and add them to the sig-list entry. Even a part-time commitment from an existing committer is significantly better than the current vacuum. -##### 3. Curate an active good-first-issue backlog +3. Curate an active good-first-issue backlog > Priority: Medium (from contributor docs review) @@ -1070,7 +939,7 @@ well-scoped documentation tasks: Activate the `help-wanted` label and use it consistently as a triage step for incoming issues. -##### 4. Consolidate new contributor onboarding +4. Consolidate new contributor onboarding > Priority: Medium (from contributor docs review) @@ -1083,7 +952,7 @@ documentation — the current guide leads immediately into Bazel/Docker/nested-virtualization setup that is unnecessary for documentation contributions. -##### 5. Establish a release notes template +5. Establish a release notes template > Priority: Medium (A08-T01 in kubevirt-analysis.csv) @@ -1105,7 +974,7 @@ This pairs with the release-docs checklist recommendation (#1 above). The recommendations in this section were generated by AI. -##### 1. Replace prose uses of "simple" and "easy" +1. Replace prose uses of "simple" and "easy" > Priority: Low @@ -1122,7 +991,7 @@ be improved: This is a low-effort improvement that aligns with CNCF inclusive language guidance from the [Inclusive Naming Initiative](https://inclusivenaming.org). -##### 2. Track the "master" API reference URL path +2. Track the "master" API reference URL path > Priority: Low @@ -1198,10 +1067,6 @@ accommodate recommended improvements without a major restructure. The following sections contain brief assessments of each element of the Contributor Documentation rubric. -> AUTHOR NOTE: For each heading below, discuss how well the in-scope items meet -> these criteria. Keep in mind that much of the contributor documentation might -> be contained in the documentation repository. - The answers and rating paragraphs in this section were generated by AI: #### Communication methods documented @@ -1794,3 +1659,148 @@ The numeric rating values used in this document are as follows 3. Meets standards 4. Meets or exceeds standards 5. Exemplary + +## Appendices + +### Appendix A - Technical Debt & Content Accuracy - AI + +This Technical Debt & Content Accuracy section is a proposed template change and +was generated by AI. + +> These tasks described for Technical Debt & Content Accuracy are sourced +> directly from kubevirt-analysis.csv. The 266 tasks in that file are intended +> for SME triage and GitHub issue creation. The recommendations below describe +> the patterns and priorities at a level useful for project planning; individual +> task details (node IDs, file paths, specific fixes) are in the CSV. + +This is the most immediately actionable area. No structural change is required — +each item is a concrete, bounded fix in a known file. Taken together, they +represent a systematic erosion of reader trust: a reader who hits a broken link, +an image that won't pull, or a typo in a field name they're about to paste into +production has reason to distrust the entire page. + +##### 1. Replace unofficial and internal dev images in examples + +> Priority: High — 17 occurrences across 11+ files + +Multiple pages embed container image references from internal development +registries or personal/unofficial namespaces that readers cannot pull: + +- `kubevirt/fedora-cloud-container-disk-demo` (user_workloads, network, storage + pages). +- Internal registry paths (confidential_computing.md, host-devices.md, debug + strace pages). +- Unofficial CirrOS images (run_strategies.md, dns.md, service_objects.md). +- Dev sidecar/shim images (launch-qemu-strace.md). + +**Recommendation:** Establish a canonical set of public, stable container images +for documentation examples (e.g., `quay.io/kubevirt/cirros-container-disk-demo`, +official Fedora Cloud images). Run a single sweep replacing all unofficial +references in one PR, then add a CI linting rule (e.g., a grep check on +`registry.k8s.io` or known internal registry host names in Markdown code blocks) +to prevent regressions. + +##### 2. Fix broken and stale links + +> Priority: High — 15 occurrences across 10+ files + +Broken links identified include: + +- Bridge interface link in `compute/live_migration.md` (A05-B06-T01) +- Cross-link to live migration prerequisites from + `cluster_admin/tekton_tasks.md` (A03-B14-T01) +- Stale OKD 3.9 documentation link in `compute/hugepages.md` (A05-B05-T02) +- Feature-gate links using absolute paths in `network/hotplug/interfaces.md` + (A06-B07-T01) and `network/hotplug/nad_reference.md` (A06-B08-T02) +- Stale golang tour URL in `contributing.md` (A09-B01-T01) +- `master`-branch API reference links in `network/interfaces_and_networks.md`, + `storage/disks_and_volumes.md`, and `debug_virt_stack/debug.md` +- Stale cross-link using old `operations/` path in `debug_virt_stack/logging.md` + (A10-B02-T01) +- DNS resolver spec link in `network/dns.md` (A06-B01-T01) + +**Recommendation:** Run `make check_links` on a CI schedule (not just on PR) and +treat link failures as blocking. For the `master`-branch API reference links, +this is the same fix as the broader API link scheme recommendation (see +Information Architecture §2) — a single pass replaces all of them. + +##### 3. Remove or update deprecated API references + +> Priority: High — 6 occurrences across 5 files + +- `spec.running` field references throughout `architecture.md` (A01-T02) — + deprecated in favor of `spec.runStrategy` +- `rbac.authorization.k8s.io/v1beta1` API version in + `user_workloads/accessing_virtual_machines.md` (A04-B06-T01) — removed in + Kubernetes 1.25 +- `--admission-control` flag (replaced by `--enable-admission-plugins`) in + `cluster_admin/api_validation.md` (A03-B05-T01) +- OKD `openshift-ansible` references in `cluster_admin/api_validation.md` + (A03-B05-T02) +- `instancetype.kubevirt.io` API stability status note in + `user_workloads/instancetypes.md` (A04-B15-T01) — may have been promoted to + stable +- Missing deprecation notice on `user_workloads/presets.md` (A04-B18-T01) — + Presets are deprecated in favor of Instancetypes + +**Recommendation:** Each of these is a high-confidence fix that does not require +SME judgment — they are factually wrong or out of date. Batch into a single +"deprecated API cleanup" PR. Add the Presets deprecation admonition immediately +as it actively misleads users into using a feature that is being removed. + +##### 4. Fix user-visible typos in code and API field names + +> Priority: High — 6 occurrences, some in copy-pasteable code + +(see CSV file) + +**Recommendation:** Fix all in a single PR — these are unambiguous one-line +changes. The field name typos are especially damaging because users copy them +verbatim and then debug why their manifest doesn't work. + +##### 5. Remove or archive outdated historical content + +> Priority: High/Medium — 11 occurrences + +Sections describing behavior specific to unsupported releases confuse readers on +current versions and signal that the docs are not maintained: + +- Pre-v0.20.0 and pre-v0.34.2 version-specific notes in + `cluster_admin/installation.md` (A03-B01-T02) +- Pre-v0.34 taint note in `cluster_admin/node_maintenance.md` (A03-B12-T03) +- Pre-v0.56 feature gate enablement note in `compute/live_migration.md` + (A05-B06-T03) +- "Future release" language in `cluster_admin/installation.md` AppArmor section + (A03-B01-T01) — the referenced issue may already be resolved +- "Future release" language in (A05-B14-T01) +- `--delete-local-data` flag (deprecated in kubectl 1.20, removed in 1.27) in + `cluster_admin/node_maintenance.md` (A03-B12-T01) +- OKD Service Catalog APB section in `cluster_admin/installation.md` + (A03-B01-T03) — the Service Catalog was removed from OKD years ago +- Outdated OKD `openshift-ansible` section in `cluster_admin/api_validation.md` + (A03-B05-T02) + +**Recommendation:** SME review required for some (e.g., whether the AppArmor +issue is resolved). Others (pre-v0.20 notes, `--delete-local-data`, OKD APB) can +be deleted without verification — they describe behavior removed in Kubernetes +or OKD versions that are no longer in the support matrix. + +##### 6. Fix the JSON syntax error in the registration example + +> Priority: High — 1 occurrence + +(A06-B04-T01) See sheet for a JSON syntax error in the plugin registration +example. A reader following this example will get an error with no indication +the source is the doc. Fix immediately. + +##### 7. Complete truncated and placeholder release notes entries + +> Priority: High/Medium — 2 occurrences + +- The `KubeVirtVMGuestMemoryPressure` entry in `release_notes.md` is truncated + mid-sentence (A08-B01-T05) +- A placeholder appears in place of a real release note (A08-B01-T06) + +**Recommendation:** These are the most visible credibility issues in the release +notes. Retrieve the complete text from the corresponding GitHub PR or release +tag and complete both entries. From 2495371b59786773562382c9e2905c881a59a9eb Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 24 Jun 2026 20:43:01 -0700 Subject: [PATCH 21/49] format fixes Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/analysis.md | 410 +++++++++++++++-------------- 1 file changed, 210 insertions(+), 200 deletions(-) diff --git a/analyses/2026/kubevirt/analysis.md b/analyses/2026/kubevirt/analysis.md index f9f2c54a..108f19b3 100644 --- a/analyses/2026/kubevirt/analysis.md +++ b/analyses/2026/kubevirt/analysis.md @@ -134,7 +134,7 @@ Documentation rubric. This section includes AI observations generated from Claude Sonnet 4.6 and are indicated as AI. -#### Overall comments - Author +#### Overall- Author The KubeVirt has a well-thought out structure that can accommodate improvements without having to restructure sections on a wide basis. @@ -237,7 +237,7 @@ Virtualization Debugging: - Overview needs examples of debugging scenarios. -#### Overall comments - AI +#### Overall- AI The KubeVirt user guide is a comprehensive, well-organized documentation site covering architecture, installation, cluster administration, user workloads, @@ -558,7 +558,7 @@ editing. ### Recommendations -#### Overall recommendations - Author +#### Overall - Author The AI results capture my recommendations except for the following pressing needs I see as a novice user: @@ -588,7 +588,7 @@ needs I see as a novice user: and Getting Started content and ideally for each major section. Mermaid code is recommended and be created initially by AI. -#### Overall recommendations - AI +#### Overall - AI The KubeVirt user guide is a substantive, professionally maintained documentation site with 94 Markdown pages covering architecture, installation, @@ -642,9 +642,9 @@ should be addressed before or alongside any larger structural work. ##### Information Architecture Recommendations - AI -1. Add section overview pages for every major section +###### Add section overview pages for every major section -> Priority: Medium — 6 new pages identified in kubevirt-analysis.csv +> Priority: High — 6 new pages identified in kubevirt-analysis.csv Every major section of the user guide (Cluster Administration, User Workloads, Compute, Network, Storage, Debug) is missing an `overview.md` landing page. @@ -664,7 +664,7 @@ reader (cluster admin vs. VM user), and link to the two or three most important pages within the section. These are low-word-count pages with high impact on navigability. -2. Add a user-facing troubleshooting page +###### Add a user-facing troubleshooting page (virsh, QEMU strace, GDB). There is no troubleshooting page for common end-user failures. Create `user_workloads/troubleshooting.md` covering: @@ -678,7 +678,7 @@ failures. Create `user_workloads/troubleshooting.md` covering: This is the most common support escalation path and currently has no documentation home. -3. Fix API reference links — scheme and versioning +###### Fix API reference links — scheme and versioning > Priority: High @@ -694,56 +694,6 @@ introduce a versioned link macro tied to the MkDocs release variable. Surface the API reference link in the site navigation (currently only on the Welcome page), not just inline in prose. -4. Refactor large reference pages into focused task pages - -> Priority: Medium - -`disks_and_volumes.md` is the largest single page in the guide and attempts to -cover conceptual explanation, reference tables, and task instructions in one -document. Split it into: - -- `disks_and_volumes/concepts.md` — what volumes and disks are, how they relate - to PVCs -- `disks_and_volumes/reference.md` — field catalog and type descriptions -- `disks_and_volumes/tasks/` — individual how-tos (attach a DataVolume, hotplug - a disk, etc.) - -Similarly, `network_binding_plugins.md` and `hook-sidecar.md` describe -architecture well but provide no end-to-end worked examples. Add at minimum one -complete task per page that a reader can follow from start to finish. - -5. Add a "Coming from VMware" onboarding path - -> Priority: Medium (High if targeting the 2024–2026 VMware migration window) - -Organizations migrating from VMware bring traditional virtualization -expectations and limited Kubernetes fluency. There is no documentation bridge. -Create a short guide that maps: - -| VMware concept | KubeVirt equivalent | Notes/gaps | -| ----------------- | --------------------------------------- | ---------- | -| vCenter / vSphere | Kubernetes API server + KubeVirt | | -| VM template | VirtualMachineInstancetype + Preference | | -| vMotion | Live migration | | -| Datastore | PVC / DataVolume (CDI) | | -| vDS / portgroup | Multus / secondary networks | | -| Snapshots | VM snapshot API | | - -Be honest about gaps (DRS-style scheduling, mature backup tooling, deep Windows -integration) — building trust with evaluators is more valuable than obscuring -shortcomings they will discover in production. - -6. Create an end-to-end instancetype/preference tutorial - -> Priority: Medium - -`instancetypes.md` and `creating_it_pref.md` describe the instancetype model but -do not walk through a complete "VM from scratch using instancetype and -preference" scenario. Add a single tutorial page that goes from defining an -instancetype and preference through creating a VM and verifying resource -allocation. This scenario represents the KubeVirt-recommended path for VM -resource management and deserves a dedicated page. - #### New user content ##### New user content Recommendations - Author @@ -752,7 +702,7 @@ resource management and deserves a dedicated page. The recommendations in this section were generated by AI. -1. Create a self-contained "Getting Started" page +###### Create a self-contained "Getting Started" page > Priority: High @@ -771,70 +721,11 @@ the current Quickstarts — that walks through: This page should be completable without leaving the user guide site. -2. Expand the Basic Use page into a meaningful getting-started flow - -> Priority: Medium (A04-B02-T01 in kubevirt-analysis.csv) - -`user_workloads/basic_use.md` is currently a thin page that covers VM start/stop -commands but does not walk through a meaningful first-use scenario. It is the -logical destination after Installation but does not build on it. Expand to -include: - -- The VM/VMI distinction (A04-B01-T01 — many readers do not understand that a - `VirtualMachine` manages lifecycle while a `VirtualMachineInstance` is the - running unit) -- Start, stop, restart, and migrate commands in a single reference table - (A04-B01-T03) -- How to verify the VM is running (status fields, events) -- A "What to read next" pointer to Networking and Storage pages - -This is distinct from the "Getting Started" self-contained quickstart (§1 above) -— the Basic Use page is the permanent reference for the most common operations, -while the quickstart is the narrative onboarding experience. - -3. Add a common prerequisites section to Quickstarts - -> Priority: Medium (A02-T04 in kubevirt-analysis.csv) - -The Quickstarts page links to four separate external environments but does not -list shared prerequisites. A reader needs kubectl, virtctl, and cluster access -for all of them. Add a brief prerequisites block at the top of `quickstarts.md`: - -- `kubectl` configured against a cluster -- `virtctl` plugin installed (link to virtctl_client_tool.md) -- Minimum cluster resources (RAM, CPUs) -- KubeVirt operator installed (link to installation.md) - -Also ensure the `virtctl_client_tool.md` page covers macOS and Windows install -instructions (A04-B05-T01, currently high-priority missing content) so the -prerequisites link is useful for all readers. - -4. Add "What to read next" sections - -> Priority: Medium - -The Quickstarts page and the Installation page both end without directing users -to their next logical step. Add a brief "Next steps" section to each: - -- After Quickstarts: point to User Workloads → Basic Use, and Storage → CDI -- After Installation: point to Quickstarts, then Feature Gates and Authorization - -5. Add an audience orientation statement to the homepage - -> Priority: Medium - -From the high-level review (kubevirt-reviews.md): the guide currently tries to -serve Kubernetes-native engineers and traditional VM operators simultaneously -without acknowledging either. Add a brief orientation paragraph near the top of -`index.md` that identifies who the guide is for and what prerequisite knowledge -is assumed (Kubernetes familiarity, cluster access). This sets expectations -correctly and reduces early drop-off from users who feel lost. - #### Content maintainability & site mechanics The recommendations in this section were generated by AI. -1. Adopt doc versioning via the `mike` plugin +##### Adopt doc versioning via the mike plugin > Priority: High @@ -848,7 +739,7 @@ version dropdown in the header. Recommended approach: - Mark older versions with a clear deprecation notice - Replace hardcoded `/master/` API reference links with a version variable -2. Prepare the directory structure for localization +##### Prepare the directory structure for localization > Priority: Medium @@ -859,7 +750,7 @@ the MkDocs Material `i18n` plugin and add a documented convention for how language variants are organized (`docs/zh-CN/`, etc.), even if only English is populated initially. Cost is low now; cost grows with every page added. -3. Enable analytics on the user guide +##### Enable analytics on the user guide > Priority: High (from website analysis) @@ -875,7 +766,7 @@ requires no cookie consent banner) via the `extra.analytics` key in (`X-Robots-Tag: noindex` via Netlify headers) to avoid polluting production analytics and search indexes. -4. Document account custodians +##### Document account custodians > Priority: Medium (from website analysis) @@ -885,7 +776,7 @@ CONTRIBUTING.md or the community repo listing the current custodians. This is a low-effort change that prevents account access loss during maintainer transitions. -5. Fix the sitemap URL double-slash +##### Fix the sitemap URL double-slash > Priority: Low @@ -911,7 +802,7 @@ to `CONTRIBUTING.md` (or a new `docs/release-process.md`): - How the sig/documentation SIG is involved in release sign-off - What the escalation path is for undocumented features discovered post-release -2. Staff the documentation SIG +##### Staff the documentation SIG > Priority: High @@ -922,86 +813,10 @@ contact for the CNCF documentation review process. Nominate at least one SIG chair and add them to the sig-list entry. Even a part-time commitment from an existing committer is significantly better than the current vacuum. -3. Curate an active good-first-issue backlog - -> Priority: Medium (from contributor docs review) - -The `good-first-issue` label infrastructure exists but the user-guide repo has -no open good-first issues at the time of review. New contributors who follow the -contributing guide reach a dead end. Maintain a rolling set of 3–5 small, -well-scoped documentation tasks: - -- Missing feature documentation stubs -- Broken or stale links -- Pages needing a "What to read next" section -- Prose uses of "simple"/"easy" that can be replaced - -Activate the `help-wanted` label and use it consistently as a triage step for -incoming issues. - -4. Consolidate new contributor onboarding - -> Priority: Medium (from contributor docs review) - -New contributor guidance is spread across at least four locations: -`kubevirt/kubevirt` CONTRIBUTING.md, `docs/getting-started.md`, the user-guide -Contributing page, and the community repo. Create a single "New Contributor -Guide" landing page that aggregates the full end-to-end path, and add a "Quick -Start (docs only)" path at the top for contributors who only want to fix -documentation — the current guide leads immediately into -Bazel/Docker/nested-virtualization setup that is unnecessary for documentation -contributions. - -5. Establish a release notes template - -> Priority: Medium (A08-T01 in kubevirt-analysis.csv) - -The `release_notes.md` file has inconsistent formatting across releases, two -incomplete entries (a truncated note, a placeholder — see Technical Debt §7), -and no documented template for contributors. Create a release notes template -(either a comment block at the top of `release_notes.md` or a separate -`docs/release-notes-template.md`) that specifies: - -- Required sections per release (breaking changes, new features, deprecations, - bug fixes, known issues) -- How to link to the corresponding GitHub milestone -- The Kubernetes support matrix line format (several releases are missing this) -- Who is responsible for completing the notes before release tag - -This pairs with the release-docs checklist recommendation (#1 above). - #### Inclusive language The recommendations in this section were generated by AI. -1. Replace prose uses of "simple" and "easy" - -> Priority: Low - -Approximately 45 occurrences of "simple" or "easy" exist across 42 files. Most -are in code example resource names (acceptable) but some are in prose that can -be improved: - -| Current | Suggested replacement | -| ----------------------- | -------------------------------------------- | -| "a simple example" | "the following example", "a minimal example" | -| "easy ways to fix them" | "common ways to resolve them" | -| "simplest" | "the most direct" / "the least-invasive" | - -This is a low-effort improvement that aligns with CNCF inclusive language -guidance from the [Inclusive Naming Initiative](https://inclusivenaming.org). - -2. Track the "master" API reference URL path - -> Priority: Low - -All deep-links to the API reference use -`/api-reference/master/definitions.html`. This is the upstream API reference -site's URL structure, not a KubeVirt-owned naming choice — but it does embed a -non-recommended term in user-visible URLs. Open an issue (or add a link-checker -CI note) to flag when the upstream adopts a non-master stable URL, at which -point all deep-links can be updated in a single pass. - #### Additional Recommendations The recommendations in this section were generated by AI. @@ -1804,3 +1619,198 @@ the source is the doc. Fix immediately. **Recommendation:** These are the most visible credibility issues in the release notes. Retrieve the complete text from the corresponding GitHub PR or release tag and complete both entries. + +### Appendix B - Medium and low recommendations - AI + +#### Information Architecture + +##### Refactor large reference pages into focused task pages + +> Priority: Medium + +`disks_and_volumes.md` is the largest single page in the guide and attempts to +cover conceptual explanation, reference tables, and task instructions in one +document. Split it into: + +- `disks_and_volumes/concepts.md` — what volumes and disks are, how they relate + to PVCs +- `disks_and_volumes/reference.md` — field catalog and type descriptions +- `disks_and_volumes/tasks/` — individual how-tos (attach a DataVolume, hotplug + a disk, etc.) + +Similarly, `network_binding_plugins.md` and `hook-sidecar.md` describe +architecture well but provide no end-to-end worked examples. Add at minimum one +complete task per page that a reader can follow from start to finish. + +##### Add a "Coming from VMware" onboarding path + +> Priority: Medium (High if targeting the 2024–2026 VMware migration window) + +Organizations migrating from VMware bring traditional virtualization +expectations and limited Kubernetes fluency. There is no documentation bridge. +Create a short guide that maps: + +| VMware concept | KubeVirt equivalent | Notes/gaps | +| ----------------- | --------------------------------------- | ---------- | +| vCenter / vSphere | Kubernetes API server + KubeVirt | | +| VM template | VirtualMachineInstancetype + Preference | | +| vMotion | Live migration | | +| Datastore | PVC / DataVolume (CDI) | | +| vDS / portgroup | Multus / secondary networks | | +| Snapshots | VM snapshot API | | + +Be honest about gaps (DRS-style scheduling, mature backup tooling, deep Windows +integration) — building trust with evaluators is more valuable than obscuring +shortcomings they will discover in production. + +##### Create an end-to-end instancetype/preference tutorial + +> Priority: Medium + +`instancetypes.md` and `creating_it_pref.md` describe the instancetype model but +do not walk through a complete "VM from scratch using instancetype and +preference" scenario. Add a single tutorial page that goes from defining an +instancetype and preference through creating a VM and verifying resource +allocation. This scenario represents the KubeVirt-recommended path for VM +resource management and deserves a dedicated page. + +#### New User Content + +##### Expand the Basic Use page into a meaningful getting-started flow + +> Priority: Medium (A04-B02-T01 in kubevirt-analysis.csv) + +`user_workloads/basic_use.md` is currently a thin page that covers VM start/stop +commands but does not walk through a meaningful first-use scenario. It is the +logical destination after Installation but does not build on it. Expand to +include: + +- The VM/VMI distinction (A04-B01-T01 — many readers do not understand that a + `VirtualMachine` manages lifecycle while a `VirtualMachineInstance` is the + running unit) +- Start, stop, restart, and migrate commands in a single reference table + (A04-B01-T03) +- How to verify the VM is running (status fields, events) +- A "What to read next" pointer to Networking and Storage pages + +This is distinct from the "Getting Started" self-contained quickstart (§1 above) +— the Basic Use page is the permanent reference for the most common operations, +while the quickstart is the narrative onboarding experience. + +##### Add a common prerequisites section to Quickstarts + +> Priority: Medium (A02-T04 in kubevirt-analysis.csv) + +The Quickstarts page links to four separate external environments but does not +list shared prerequisites. A reader needs kubectl, virtctl, and cluster access +for all of them. Add a brief prerequisites block at the top of `quickstarts.md`: + +- `kubectl` configured against a cluster +- `virtctl` plugin installed (link to virtctl_client_tool.md) +- Minimum cluster resources (RAM, CPUs) +- KubeVirt operator installed (link to installation.md) + +Also ensure the `virtctl_client_tool.md` page covers macOS and Windows install +instructions (A04-B05-T01, currently high-priority missing content) so the +prerequisites link is useful for all readers. + +##### Add "What to read next" sections + +> Priority: Medium + +The Quickstarts page and the Installation page both end without directing users +to their next logical step. Add a brief "Next steps" section to each: + +- After Quickstarts: point to User Workloads → Basic Use, and Storage → CDI +- After Installation: point to Quickstarts, then Feature Gates and Authorization + +##### Add an audience orientation statement to the homepage + +> Priority: Medium + +From the high-level review (kubevirt-reviews.md): the guide currently tries to +serve Kubernetes-native engineers and traditional VM operators simultaneously +without acknowledging either. Add a brief orientation paragraph near the top of +`index.md` that identifies who the guide is for and what prerequisite knowledge +is assumed (Kubernetes familiarity, cluster access). This sets expectations +correctly and reduces early drop-off from users who feel lost. + +#### Content creation process + +##### Curate an active good-first-issue backlog + +> Priority: Medium (from contributor docs review) + +The `good-first-issue` label infrastructure exists but the user-guide repo has +no open good-first issues at the time of review. New contributors who follow the +contributing guide reach a dead end. Maintain a rolling set of 3–5 small, +well-scoped documentation tasks: + +- Missing feature documentation stubs +- Broken or stale links +- Pages needing a "What to read next" section +- Prose uses of "simple"/"easy" that can be replaced + +Activate the `help-wanted` label and use it consistently as a triage step for +incoming issues. + +##### Consolidate new contributor onboarding + +> Priority: Medium (from contributor docs review) + +New contributor guidance is spread across at least four locations: +`kubevirt/kubevirt` CONTRIBUTING.md, `docs/getting-started.md`, the user-guide +Contributing page, and the community repo. Create a single "New Contributor +Guide" landing page that aggregates the full end-to-end path, and add a "Quick +Start (docs only)" path at the top for contributors who only want to fix +documentation — the current guide leads immediately into +Bazel/Docker/nested-virtualization setup that is unnecessary for documentation +contributions. + +##### Establish a release notes template + +> Priority: Medium (A08-T01 in kubevirt-analysis.csv) + +The `release_notes.md` file has inconsistent formatting across releases, two +incomplete entries (a truncated note, a placeholder — see Technical Debt §7), +and no documented template for contributors. Create a release notes template +(either a comment block at the top of `release_notes.md` or a separate +`docs/release-notes-template.md`) that specifies: + +- Required sections per release (breaking changes, new features, deprecations, + bug fixes, known issues) +- How to link to the corresponding GitHub milestone +- The Kubernetes support matrix line format (several releases are missing this) +- Who is responsible for completing the notes before release tag + +This pairs with the release-docs checklist recommendation (#1 above). + +#### Inclusive Language + +##### Replace prose uses of "simple" and "easy" + +> Priority: Low + +Approximately 45 occurrences of "simple" or "easy" exist across 42 files. Most +are in code example resource names (acceptable) but some are in prose that can +be improved: + +| Current | Suggested replacement | +| ----------------------- | -------------------------------------------- | +| "a simple example" | "the following example", "a minimal example" | +| "easy ways to fix them" | "common ways to resolve them" | +| "simplest" | "the most direct" / "the least-invasive" | + +This is a low-effort improvement that aligns with CNCF inclusive language +guidance from the [Inclusive Naming Initiative](https://inclusivenaming.org). + +##### Track the "master" API reference URL path + +> Priority: Low + +All deep-links to the API reference use +`/api-reference/master/definitions.html`. This is the upstream API reference +site's URL structure, not a KubeVirt-owned naming choice — but it does embed a +non-recommended term in user-visible URLs. Open an issue (or add a link-checker +CI note) to flag when the upstream adopts a non-master stable URL, at which +point all deep-links can be updated in a single pass. From fa8152c63267aada73062d7f635f70e4a83723c9 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 24 Jun 2026 20:53:56 -0700 Subject: [PATCH 22/49] heading fixes Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/analysis.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/analyses/2026/kubevirt/analysis.md b/analyses/2026/kubevirt/analysis.md index 108f19b3..d2764d52 100644 --- a/analyses/2026/kubevirt/analysis.md +++ b/analyses/2026/kubevirt/analysis.md @@ -1494,7 +1494,7 @@ represent a systematic erosion of reader trust: a reader who hits a broken link, an image that won't pull, or a typo in a field name they're about to paste into production has reason to distrust the entire page. -##### 1. Replace unofficial and internal dev images in examples +#### 1. Replace unofficial and internal dev images in examples > Priority: High — 17 occurrences across 11+ files @@ -1515,7 +1515,7 @@ references in one PR, then add a CI linting rule (e.g., a grep check on `registry.k8s.io` or known internal registry host names in Markdown code blocks) to prevent regressions. -##### 2. Fix broken and stale links +#### 2. Fix broken and stale links > Priority: High — 15 occurrences across 10+ files @@ -1539,7 +1539,7 @@ treat link failures as blocking. For the `master`-branch API reference links, this is the same fix as the broader API link scheme recommendation (see Information Architecture §2) — a single pass replaces all of them. -##### 3. Remove or update deprecated API references +#### 3. Remove or update deprecated API references > Priority: High — 6 occurrences across 5 files @@ -1563,7 +1563,7 @@ SME judgment — they are factually wrong or out of date. Batch into a single "deprecated API cleanup" PR. Add the Presets deprecation admonition immediately as it actively misleads users into using a feature that is being removed. -##### 4. Fix user-visible typos in code and API field names +#### 4. Fix user-visible typos in code and API field names > Priority: High — 6 occurrences, some in copy-pasteable code @@ -1573,7 +1573,7 @@ as it actively misleads users into using a feature that is being removed. changes. The field name typos are especially damaging because users copy them verbatim and then debug why their manifest doesn't work. -##### 5. Remove or archive outdated historical content +#### 5. Remove or archive outdated historical content > Priority: High/Medium — 11 occurrences @@ -1600,7 +1600,7 @@ issue is resolved). Others (pre-v0.20 notes, `--delete-local-data`, OKD APB) can be deleted without verification — they describe behavior removed in Kubernetes or OKD versions that are no longer in the support matrix. -##### 6. Fix the JSON syntax error in the registration example +#### 6. Fix the JSON syntax error in the registration example > Priority: High — 1 occurrence @@ -1608,7 +1608,7 @@ or OKD versions that are no longer in the support matrix. example. A reader following this example will get an error with no indication the source is the doc. Fix immediately. -##### 7. Complete truncated and placeholder release notes entries +#### 7. Complete truncated and placeholder release notes entries > Priority: High/Medium — 2 occurrences From b9a5a14954d22eb3ace6e8c8216a972bfe6afd18 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 22 Jul 2026 00:32:02 -0700 Subject: [PATCH 23/49] Updates per new AI workflow Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/analysis.md | 1541 +++++++++------------------- 1 file changed, 484 insertions(+), 1057 deletions(-) diff --git a/analyses/2026/kubevirt/analysis.md b/analyses/2026/kubevirt/analysis.md index d2764d52..f483ff09 100644 --- a/analyses/2026/kubevirt/analysis.md +++ b/analyses/2026/kubevirt/analysis.md @@ -1,7 +1,7 @@ --- title: KubeVirt Documentation Analysis created: 2026-05-24 -modified: 2026-06-22 +modified: 2026-07-19 author: Bruce Hamilton --- @@ -131,10 +131,7 @@ code. The following sections contain assessments of each element of the Project Documentation rubric. -This section includes AI observations generated from Claude Sonnet 4.6 and are -indicated as AI. - -#### Overall- Author +#### Overall (Author) The KubeVirt has a well-thought out structure that can accommodate improvements without having to restructure sections on a wide basis. @@ -237,184 +234,221 @@ Virtualization Debugging: - Overview needs examples of debugging scenarios. -#### Overall- AI - -The KubeVirt user guide is a comprehensive, well-organized documentation site -covering architecture, installation, cluster administration, user workloads, -compute, networking, storage, debugging, and release notes — 94 Markdown pages -in total, served via MkDocs Material at `kubevirt.io/user-guide/`. - -The breadth of topics is good for an incubating project. Key gaps include the -lack of versioned documentation, no localization framework, no self-contained -getting started path, and an externally-hosted API reference that is only -loosely integrated with the user guide. - -(end AI comments) - -#### Information architecture +#### Information architecture (AI) The overall structure (pages/subpages/sections/subsections) of your project documentation. We evaluate on the following: -The answers and rating paragraphs in this section were generated by AI: - - Is there high level conceptual/"About" content? Is the documentation feature complete? (i.e., each product feature is documented) - **Answer:** Yes. The `architecture.md` page provides a conceptual overview of - KubeVirt's service-oriented architecture, its relationship to Kubernetes, and - the roles of CRDs, controllers, and daemons. Each of the main sections - (Cluster Administration, User Workloads, Compute, Network, Storage) begins - with conceptual framing before presenting tasks. Feature coverage is broad: - live migration, CPU/memory hotplug, hugepages, NUMA, host devices, storage - import/export/snapshot/clone, network binding plugins, and ARM64 support are - all documented. The site is substantially feature-complete for core - functionality. + Yes to conceptual content. The top-level `architecture.md` explains the + service-oriented architecture and component stack, and the Welcome page + (`index.md`) together with most section indexes provide "About"-style framing. + Feature coverage is largely complete: the 94-page guide documents live + migration, CPU and memory hotplug, hugepages, NUMA, host devices, storage + import/export/snapshot/clone, network binding plugins, and ARM64. A few + features are described only as mechanisms rather than with full task coverage. - Are there step-by-step instructions (tasks, tutorials) documented for features? - **Answer:** Yes, with caveats. Most pages combine conceptual explanation with - YAML manifests and `kubectl`/`virtctl` command sequences. However, the - presentation style varies: some pages (e.g., `installation.md`, - `live_migration.md`, `snapshot_restore_api.md`) follow a clear task structure, - while others (e.g., `virtual_hardware.md`, `interfaces_and_networks.md`) read - more like reference material with embedded examples. There are no structured - tutorial walkthroughs within the user guide itself — tutorials are delegated - to external Killercoda labs and kubevirt.io/labs links. + Mostly yes. Most feature pages include procedures with copy-pasteable + `kubectl` and `virtctl` examples, and the Welcome page links to external + hands-on labs. Presentation is inconsistent, however: only about 20 of 94 + pages use explicit numbered steps, and many procedures are presented as prose + interspersed with command blocks (for example, `user_workloads/basic_use.md`). + Converting multi-step procedures to numbered steps would make tasks easier to + follow. - Are there any key features which are documented but missing task documentation? - **Answer:** Yes, a few gaps exist. The `network_binding_plugins.md` page - describes the plugin architecture conceptually but does not include a complete - worked example of implementing and deploying a custom binding plugin. The - `hook-sidecar.md` page similarly describes the mechanism without a clear - end-to-end task. The `instancetypes.md` and related `creating_it_pref.md` - pages describe the instancetype model but don't walk through a complete "VM - from scratch using instancetype and preference" scenario as a single tutorial. + Yes, a few. `network/network_binding_plugins.md` and + `user_workloads/hook-sidecar.md` describe mechanisms without end-to-end worked + examples, and `user_workloads/virtctl_client_tool.md` covers only downloading + and installing `virtctl` rather than providing a consolidated command + reference. Adding a complete task walkthrough for each would close these gaps. - Is the "happy path"/most common use case documented? Does task and tutorial content demonstrate atomicity and isolation of concerns? (Are tasks clearly named according to user goals?) - **Answer:** Partially. The happy path — deploying KubeVirt on a cluster and - running a first VM — is not fully self-contained within the user guide. - `installation.md` covers deployment, and `basic_use.md` covers starting and - stopping VMs, but the connection between them is implicit; there is no - explicit "From zero to your first running VM" sequence that chains these steps - together. Task pages are generally well-named according to user goals (e.g., - "Accessing Virtual Machines", "Hotplug Volumes", "Live Migration"), and most - demonstrate reasonable isolation of concerns. However, the - `disks_and_volumes.md` page covers a very large surface area in a single - document and could benefit from being split. + The happy path is not documented as a single flow: + `cluster_admin/installation.md` and `user_workloads/basic_use.md` are never + chained into an "install to first running VM" tutorial, and `quickstarts.md` + is only a short list of external links. Atomicity is partial. Most task pages + are goal-named, but oversized pages such as `storage/disks_and_volumes.md` + (roughly 2,160 lines) combine many loosely related tasks and concepts. Task + naming is inconsistent: `compute/live_migration.md` mixes verb-phrase headings + ("Enabling the live-migration support", "Canceling a live migration") with + noun-phrase headings ("Limitations", "Migration Status Reporting"). - If the documentation does not suffice, is there a clear escalation path for users needing more help? (FAQ, Troubleshooting) - **Answer:** Partially. The homepage has a "Getting help" section linking to - the bug tracker, mailing list, and Slack. There is a dedicated "Virtualization - Debugging" section (`debug_virt_stack/`) with six pages covering log - verbosity, virsh commands, privileged node debugging, QEMU strace, and GDB. - However, there is no FAQ page, and no general troubleshooting page targeting - common user-facing errors (e.g., VM stuck in Pending, network connectivity - failures, image import failures). The debugging section is - advanced/developer-oriented rather than user-oriented. + Partially. The Welcome page includes a "Getting help" section linking to file + a bug, the mailing list, and Slack, which is a good external escalation path. + However, there is no in-documentation FAQ or user-facing troubleshooting page; + `debug_virt_stack/` is developer-oriented. A user troubleshooting page would + provide first-line help before external channels. - If the product exposes an API, is there a complete reference? - **Answer:** Yes, but it is hosted externally. The KubeVirt API reference is - available at `http://kubevirt.io/api-reference/` and is linked from the user - guide homepage and individual pages. The reference is auto-generated and - covers all CRD types (VirtualMachine, VirtualMachineInstance, - VirtualMachineInstanceMigration, etc.). However, the API reference is not - integrated into the user guide site itself, links to it use `http://` rather - than `https://`, and many in-guide deep links reference the `master` branch - path (`/api-reference/master/definitions.html`) rather than a stable versioned - path, which may become stale. + Partially. A complete API reference exists but is hosted externally and linked + from `index.md`. The links use `http://` and deep-link to `master`-pinned + paths, so they are neither secure nor version-stable. Co-hosting or linking a + versioned `https://` reference would make it durable and release-accurate. - Is content up to date and accurate? - **Answer:** Largely yes. Release notes are current through v1.8.0 (March 2026) - and many pages reference recent feature gate additions. However, several API - reference deep-links use `master`-branch paths that may not reflect the latest - stable release. A few older sections may not reflect current defaults (e.g., - AppArmor workarounds described in `installation.md` note a tracking issue as - "future" work, which may have already been resolved upstream). - -**Rating: 3** — Broad and largely accurate coverage with good conceptual -framing; held back by the lack of a self-contained "happy path" sequence, the -external (and HTTP-linked) API reference, no FAQ/user-facing troubleshooting, -and some reference-only pages that could benefit from task-structured rewrites. + Yes. `release_notes.md` is current (v1.8.0) and feature coverage reflects + recent capabilities. Content is generally accurate; the main freshness risk is + the externally hosted, `master`-pinned API reference, which can drift from + released versions. + +##### Comment + +The KubeVirt User Guide is organized into clear, domain-oriented top-level +sections (Architecture, Quickstarts, Cluster Administration, User Workloads, +Compute, Network, Storage, Release Notes, Contributing, and Virtualization +Debugging), and navigation order is explicitly controlled through `.nav.yml` +files rather than left to alphabetization. This gives the guide a predictable +structure that maps reasonably well to the two implied personas—cluster +administrators and workload owners—and the presence of dedicated conceptual +content in `architecture.md` and an entry point in `quickstarts.md` is a solid +foundation. The overall shape of the site is sound and does not require a +ground-up rebuild. + +The most significant architectural weakness is that conceptual, task, and +reference information are interleaved within sections rather than separated by +information type. The Storage section, for example, places API reference pages +(`clone_api.md`, `export_api.md`, `snapshot_restore_api.md`) alongside +task-oriented pages (`hotplug_volumes.md`, `disks_and_volumes.md`) in a single +flat list, and Compute and Cluster Administration present roughly twenty pages +each in long, largely undifferentiated lists. Readers cannot easily tell whether +a given page teaches a concept, walks through a task, or documents an API +surface. Introducing consistent sub-groupings—as User Workloads already does +with its "Monitoring" and "Workloads" clusters—would make each section easier to +scan and would bring the guide closer to the clear concept/task/reference +separation modeled by the Prometheus documentation. + +Two secondary issues also affect wayfinding. First, most pages are named as +nouns or feature names ("hugepages", "live_migration", "host-devices") rather +than as goal-oriented verb phrases, which makes it harder for users to locate +content by the task they are trying to accomplish. Second, the new-user path is +thin: the Quickstarts page mainly links out to external Killercoda and +kubevirt.io resources, and installation is nested inside Cluster Administration +rather than surfaced as a clearly labeled "Getting Started" or "Installation" +entry near the top of the information architecture. The escalation path (bug +tracker, mailing list, and Slack) is present on the landing page, but there is +no consolidated FAQ or troubleshooting hub beyond the debugging section, which +sits at the very bottom of the navigation after Contributing. + +To improve the architecture, group each section's pages by information type and +use case, rename task pages to lead with a verb that names the user goal, +promote installation and first-run content into a clearly labeled +getting-started entry high in the navigation, and consider relocating +Virtualization Debugging nearer the task content it supports. These are +targeted, incremental changes rather than a wholesale reorganization. + +Is a restructure of the content needed? False. The top-level information +architecture is fundamentally sound; the guide needs targeted section-level +reorganization, clearer separation of information types, and improved page +naming rather than a full restructure. #### New user content New users are the most avid users of documentation, and need content specifically for them. We evaluate on the following: -The answers and rating paragraphs in this section were generated by AI: - - Is "getting started" clearly labeled? ("Getting started", "Installation", "First steps", etc.) - **Answer:** Partially. The top-level navigation includes a "Quickstarts" entry - and a "Cluster Administration" section whose first page is "Installation." - However, the Quickstarts page (`quickstarts.md`) is essentially a curated list - of external links (Killercoda, minikube, kind, cloud providers) and contains - no embedded steps on that page. There is no section explicitly labeled - "Getting Started" that guides a user from zero through a first successful VM. + Partially. There is no page or navigation entry titled "Getting Started" or + "First steps." New-user entry points are instead spread across a top-level + "Quickstarts" item, an "Installation" page (the first page under Cluster + Administration), and a "Try it out" section on the homepage. "Installation" is + clearly labeled, but the absence of a single, consistently named + getting-started landing page makes the on-ramp harder to find than a + conventional "Getting Started" label would. - Is installation documented step-by-step? - **Answer:** Yes. `cluster_admin/installation.md` provides clear prerequisites, - container runtime support notes, AppArmor considerations, and installation - steps using `kubectl apply` with the KubeVirt operator manifest. Requirements - (Kubernetes version, `--allow-privileged`, `kubectl`) are enumerated at the - top. The steps are sequential. + Yes. `cluster_admin/installation.md` lists prerequisites and then provides + copy-pasteable, ordered commands to deploy the KubeVirt operator, create the + KubeVirt CR, wait for the components to become available, and verify the + running pods. It also covers optional steps such as software emulation + fallback and node-placement restrictions. - If needed, are multiple OSes documented? - **Answer:** Partially. The documentation assumes Linux as the host OS - (consistent with Kubernetes deployment targets). ARM64 cluster support is - covered in a dedicated subsection of Cluster Administration (four pages: - device status, feature gate status, operations, and VMs on ARM64). There is no - documentation for Windows hosts, which is appropriate since KubeVirt does not - support Windows as a host OS. Windows _guest_ operating system support is - documented (`user_workloads/windows_virtio_drivers.md`, `legacy_windows.md`). + Partially. Because KubeVirt is a Kubernetes add-on, the installation guide + documents multiple Kubernetes platforms (Kubernetes, OKD, k3OS) and both the + x86_64 and Arm64 architectures, rather than host operating systems. + Host-OS-specific concerns are limited to AppArmor and SELinux notes. + Separately, guest operating systems (for example Windows and Linux) are + documented under User Workloads. There is no per-Linux-distribution + installation walkthrough, which is reasonable for a cluster add-on but worth + noting. - Do users know where to go after reading the getting started guide? - **Answer:** Partially. The external quickstart guides (e.g., - kubevirt.io/quickstart_minikube/) link back to the user guide for further - learning. The user guide homepage lists all sections with one-line - descriptions, making it clear what the next steps could be. However, the - Quickstarts page itself has no "next steps" or recommended reading path — it - ends with the four links and no guidance on which sections of the user guide - to read next. + Partially. The installation page ends with optional topics (network plugins, + node placement) rather than an explicit "Next steps" pointer to creating a + first virtual machine. Users must navigate on their own to "User Workloads" + (for example `basic_use.md` or `creating_vms.md`). Adding a clear "Next steps" + link from installation to the first-VM tasks would close this gap. - Is your new user content clearly signposted on your site's homepage or at the top of your information architecture? - **Answer:** Yes. The homepage lists all guide sections with brief - descriptions, "Try it out" links to Killercoda and quickstart labs, KubeVirt - Labs links, a "Getting help" section, and a "Developer" section. The - "Quickstarts" item appears in the top navigation bar as the third item after - "Welcome" and "Architecture." New users can orient themselves quickly from the - homepage. + Yes. The homepage lists all major sections and includes prominent "Try it + out," "KubeVirt Labs," and "Getting help" sections, and "Quickstarts" appears + near the top of the navigation. However, much of this new-user content relies + on external links (Killercoda, minikube/kind/cloud quickstarts, and the + kubevirt.io labs) rather than in-guide getting-started material, so the + signposting leads users off-site fairly quickly. - Is there sample code or other example content that can easily be copy-pasted? - **Answer:** Yes. The user guide is rich in YAML manifests and - `kubectl`/`virtctl` command examples throughout. Most feature pages provide at - least one complete YAML snippet showing the relevant spec fields in context. - Code blocks are syntax-highlighted via with anchor line numbers, and MkDocs - Material provides a one-click copy button on code blocks. The examples are - generally realistic and independently runnable. - -**Rating: 3** — Installation is well-documented and examples can be pasted; -signposting on the homepage is adequate. Key weaknesses are the Quickstarts page -delegating entirely to external content without a self-contained path, and the -lack of a "What to read next" guide for new users. + Yes. The documentation makes extensive use of fenced and indented code blocks + with ready-to-run examples, including installation shell commands, + `virtctl create vm` invocations, `kubectl` lifecycle commands, and YAML + manifests. These are formatted for direct copy-paste. + +##### Comment + +The KubeVirt User Guide gives new users a solid technical starting point, but +its on-ramp is fragmented across several differently named locations. New-user +material is split between a top-level "Quickstarts" entry, an "Installation" +page buried as the first item under "Cluster Administration," and "Try it out" +and "KubeVirt Labs" sections on the homepage. Because none of these is labeled +"Getting Started" or "First Steps," newcomers must piece the path together +themselves. Consolidating these entry points under a single, clearly named +"Getting Started" section—ideally as its own top-level navigation item—would +match the convention new users expect and provide one obvious front door. The +Falco getting-started guide (https://falco.org/docs/getting-started/) is a good +model for this unified structure. + +The installation documentation itself is strong: it lists prerequisites, +provides ordered and copy-pasteable operator and CR commands, shows how to +verify a healthy deployment, and covers multiple platforms (Kubernetes, OKD, +k3OS) and architectures (x86_64 and Arm64). The main weakness is that the guide +leans heavily on external links—Killercoda, the minikube/kind/cloud quickstarts, +and the kubevirt.io labs—rather than an in-guide walkthrough that carries a +reader from a fresh cluster to a running virtual machine. Bringing at least one +complete, end-to-end "deploy KubeVirt and launch your first VM" tutorial into +the guide would reduce reliance on off-site content and give users a +self-contained first success. + +The most actionable single improvement is to close the gap between installation +and first use. The installation page currently ends with optional topics +(network plugins, node placement) and offers no explicit "Next steps" pointer +toward the first-VM tasks in "User Workloads" (such as `basic_use.md` and +`creating_vms.md`). Adding a clear "Next steps" call-to-action at the end of +installation, linking directly to creating and accessing a first virtual +machine, would give new users an unbroken path from setup to a working workload. #### Content maintainability & site mechanics @@ -423,43 +457,67 @@ become large maintenance burdens, particularly if you don’t plan for them. We evaluate on the following: -The answers and rating paragraphs in this section were generated by AI: - -- Is your documentation searchable? +- Is the documentation searchable? - **Answer:** Yes. The MkDocs `search` plugin is configured in `mkdocs.yml` with - a custom separator to improve tokenization, and site-local search is - functional and present in the header on all pages. See also the website - analysis document's assessment of intra-site search (rated 4/5). + Yes. The `search` plugin is enabled in `mkdocs.yml` (with a custom tokenizer + separator), and the `mkdocs-material` theme provides a built-in client-side + search box across the site. Users can search all pages from the header search + field. -- Are you planning for localization/internationalization with regards to site +- Are there plans for localization/internationalization with regards to site directory structure? Is a localization framework present? - **Answer:** No. The documentation is English-only with no localization - framework in place. The directory structure does not include language-code - subdirectories (e.g., `docs/zh-CN/`), and `mkdocs.yml` has no `i18n` or - `locale` configuration. There is one open issue in the user-guide repo - proposing Simplified Chinese (zh-CN) documentation, but no implementation has - begun. MkDocs Material's `i18n` plugin (which would enable language-based - directory structure) is not currently enabled. - -- Do you have a clearly documented method for versioning your content? - - **Answer:** No. The user guide serves a single version of documentation from - the `main` branch with no versioning mechanism. There are no versioned doc - sets (e.g., separate /v1.7/, /v1.8/ branches or MkDocs `mike` plugin - configuration). Release notes (`release_notes.md`) are maintained in a single - file covering all releases, but this is distinct from versioned documentation. - Many in-page API reference links hardcode `/api-reference/master/` as the - path, meaning users reading docs for an older release see links to current-tip - API behavior. This is a meaningful gap as KubeVirt has a defined support - matrix (latest three Kubernetes releases) and users running older versions may - have different feature availability. - -**Rating: 2** — Search is well-implemented, but the absence of both a -localization framework and a doc versioning strategy represent significant gaps -for a project with multiple active release lines and a growing international -community. + No. There is no localization framework configured. The `docs/` tree is + organized by topic (for example `cluster_admin`, `compute`, `network`, + `storage`) with no per-language subdirectories such as `en/` or `zh/`, and no + i18n plugin (for example `mkdocs-static-i18n`) is present in `mkdocs.yml` or + installed by the Netlify build. The theme does not set a language/locale + switcher, and no localization plans are documented in the README or + CONTRIBUTING files. + +- Is there a clearly documented method for versioning of content? + + No. The documentation site publishes a single "latest" version built from the + `main` branch to kubevirt.io/user-guide, and there is no content-versioning + tooling configured. The standard MkDocs Material versioning tool (`mike`) is + not enabled, the theme defines no version provider or version selector, and + neither the README nor CONTRIBUTING describes a method for versioning + documentation. The `release_notes.md` page tracks the KubeVirt product's + release notes rather than versioned snapshots of the docs. + +##### Comment + +The KubeVirt User Guide is built on a maintainable foundation. It uses MkDocs +with the `mkdocs-material` theme, keeps all content as Markdown under `docs/`, +and enforces ordering explicitly through per-directory `.nav.yml` files rather +than relying on alphabetical sorting. Search is enabled out of the box via the +`search` plugin, and the contribution workflow is well documented: the README +describes forking, signing commits, and local validation through `make` targets +that check spelling (yaspeller) and links (HTMLProofer). Page moves are handled +gracefully through an extensive `redirects` map in `mkdocs.yml`, which preserves +old URLs and reduces link rot. These are strong maintainability practices. + +The most significant gap is content versioning. The site publishes a single +"latest" build from the `main` branch, with no versioning tooling such as `mike` +and no version selector in the theme. Because KubeVirt's API and features evolve +across releases, readers on an older KubeVirt version have no way to view +documentation matching their deployment, and maintainers cannot preserve +historical snapshots. Adopting `mike` (the standard versioning tool for MkDocs +Material) and surfacing a version dropdown would let the project align +documentation with product releases and is the highest-impact maintainability +improvement to pursue. Kubernetes (https://kubernetes.io/docs/) is a good model +of versioned CNCF documentation. + +Localization is a secondary consideration. There is currently no +internationalization framework, no per-language directory structure (for example +`en/` or `zh/`), and no documented plans for translation. While localization may +not be an immediate priority, the current flat, topic-based layout would require +restructuring to support it later. If translation is a future goal, the project +should decide early on a directory convention and evaluate an i18n plugin (such +as `mkdocs-static-i18n`) so the structure can accommodate multiple languages +without a disruptive reorganization. In the near term, documenting the intended +approach—even if implementation is deferred—would help contributors plan content +accordingly. #### Content creation processes @@ -468,50 +526,79 @@ requires the same kind of review and approval processes as code. We evaluate on the following: -The answers and rating paragraphs in this section were generated by AI: - - Is there a clearly documented (ongoing) contribution process for documentation? - **Answer:** Yes. The `contributing.md` page (linked from the main navigation) - clearly describes prerequisites (Git workflow, GitHub familiarity), repository - entry points for docs contributions (user-guide, kubevirt.github.io, community - repos), how to find `good-first-issue` labeled issues, and alternative - contribution paths (PR reviews, issue filing, New Contributor session - recording). The CONTRIBUTING.md in the repo root provides the Makefile-based - local preview workflow (`make build_img`, `make run`, `make check_links`, - `make check_spelling`). - -- Does your code release process account for documentation creation & updates? - - **Answer:** Partially. The release notes page is kept current (v1.8.0 as of - March 2026 is present). However, there is no documented policy or checklist - that explicitly requires documentation updates as part of the code release - process. There is no "docs freeze" process, no release-gating on docs - completeness, and no explicit owner for ensuring new features released in each - KubeVirt version are documented in the user guide before or alongside the code - release. + Yes. `docs/contributing.md` explains the ongoing GitHub workflow (fork, + branch, commit, open pull request, review, merge), explicitly lists the + user-guide repository as a low-barrier target for first contributions, and + links to community resources such as the Code of Conduct, membership policy, + and governance. The repository README complements this with the local + authoring workflow: where content lives (`./docs`), how to sign commits, and + how to validate changes with `make` targets for spelling (yaspeller) and link + checking (HTMLProofer) before opening a PR. + +- Does the code release process account for documentation creation & updates? + + Not explicitly. The user guide lives in a separate repository + (`kubevirt/user-guide`) and is published continuously from the `main` branch + to kubevirt.io/user-guide rather than being cut alongside KubeVirt code + releases. While a `release_notes.md` page tracks product releases, there is no + documented mechanism in this repository that requires documentation to be + created or updated as part of the core code release process, so docs updates + are decoupled from the release cadence. - Who reviews and approves documentation pull requests? - **Answer:** Clearly documented. The `OWNERS` file defines approvers and - reviewers via `OWNERS_ALIASES`. The `OWNERS` file also specifies that paths - under `docs/` are labeled `kind/documentation` and paths under `site/` are - labeled `kind/website` automatically. The project uses Prow/Tide for automated - label management and lifecycle enforcement. + Reviews and approvals are governed by Kubernetes-style OWNERS files enforced + through Prow. The root `OWNERS` delegates to `reviewers` and `approvers` + aliases defined in `OWNERS_ALIASES`. Subdirectories under `docs/` delegate to + the relevant SIG teams—for example `docs/storage/OWNERS` routes to sig-storage + reviewers and approvers. Documentation PRs are automatically labeled + `kind/documentation`, and merges require an approver's `/approve` plus + reviewer `/lgtm`. - Does the website have a clear owner/maintainer? - **Answer:** Partially. The `OWNERS_ALIASES` file identifies the team of - approvers and reviewers. However, there is no single named documentation lead - or website owner. The `sig-list.md` in the community repo lists a - "sig/documentation" SIG but it currently has no chairs or contact persons - listed, meaning the governance structure for documentation exists on paper but - is not actively staffed. - -**Rating: 3** — Contribution workflow and reviewer/approver ownership are well -documented. The main gaps are the absence of a documented release-gating process -for docs and the un-staffed documentation SIG. + Yes. Ownership is clearly defined through the repository's `OWNERS` and + `OWNERS_ALIASES` files, which name active reviewers and approvers (and list + emeritus approvers for historical context). Per-section `OWNERS` files under + `docs/` further assign responsibility to the appropriate KubeVirt SIGs, giving + the site both overall and area-specific maintainers. + +##### Comment + +The KubeVirt User Guide has a clear and welcoming content creation process. The +`docs/contributing.md` page lays out the standard GitHub workflow (fork, branch, +commit, pull request, review, merge), explicitly flags the user guide as a good +target for first-time contributors, and links to essential community documents +such as the Code of Conduct, membership policy, and governance. The README +reinforces this with practical authoring guidance: where content lives, how to +sign commits, and how to validate changes locally with `make` targets that run +spelling (yaspeller) and link (HTMLProofer) checks. Together these give new and +returning contributors a well-signposted, repeatable path to landing changes. + +Ownership and review are handled robustly through Kubernetes-style OWNERS files +enforced by Prow. The root `OWNERS` and `OWNERS_ALIASES` define active reviewers +and approvers, while per-section `OWNERS` files under `docs/` delegate to the +appropriate KubeVirt SIGs (for example, `docs/storage` routes to the storage +SIG). This gives the site both overall and area-specific maintainers, and +automatic `kind/documentation` labeling keeps documentation PRs easy to triage. +The one caveat worth surfacing to contributors is that this OWNERS/Prow approval +model is not described in the user guide's own contribution docs; a short note +in `contributing.md` explaining how `/lgtm` and `/approve` work, and who to +expect review from, would make the approval path more transparent to newcomers. + +The most actionable gap is the relationship between the code release process and +documentation. Because the user guide is a separate repository published +continuously from `main`, documentation updates are decoupled from KubeVirt's +release cadence, and nothing in the process requires feature changes to ship +with corresponding docs. This risks documentation drift as the API and features +evolve. The project should consider documenting an expectation that user-facing +changes in `kubevirt/kubevirt` include or track a companion user-guide +update—for example, a release checklist item or a cross-repository issue link—so +that documentation creation is an accountable part of shipping features rather +than an afterthought. #### Inclusive language @@ -519,42 +606,68 @@ Creating inclusive project communities is a key goal for all CNCF projects. We evaluate on the following: -The answers and rating paragraphs in this section were generated by AI: - - Are there any customer-facing utilities, endpoints, class names, or feature names that use non-recommended words as documented by the [Inclusive Naming Initiative](https://inclusivenaming.org) website? - **Answer:** Minor issues present. The word "master" appears in multiple - in-page API reference deep-links (e.g., - `http://kubevirt.io/api-reference/master/definitions.html`), which reflects - the upstream API reference site's URL structure rather than a KubeVirt-owned - naming choice. Within the user guide prose, one code example in - `live_migration.md` shows `"master": "eth1"` as a network interface - configuration key — this is a third-party (libvirt/Linux bridge) configuration - value outside KubeVirt's direct control. No KubeVirt-specific CRD field names, - feature gate names, CLI subcommands, or endpoint names using non-recommended - terms (master/slave, whitelist/blacklist, sanity) were found. + No. A search of the documentation found no KubeVirt-defined utilities, + endpoints, class names, or feature names that use non-recommended terms, and + no occurrences of words such as "slave", "whitelist", "blacklist", "sanity + check", "grandfathered", or "man-in-the-middle". The word "master" does + appear, but only in contexts KubeVirt does not own: external URLs and Git + branch names (for example `.../blob/master/...`), version path segments in the + API reference (`api-reference/master/...`), a third-party CNI/bonding + configuration field (`"master": "eth1"`), a Kubernetes node-label example + (`kubevirt.io/nodeName: master`), and verbatim QEMU/libvirt command output + (`masterKey0`, `master-key.aes`). None of these are customer-facing names + coined by the project, so no renaming action is required within the guide. - Does the project use language like "simple", "easy", etc.? - **Answer:** Yes, occasionally. A scan of the docs found approximately 45 - occurrences of "simple" or "easy" across 42 files. Many of these are benign — - resource names in YAML examples (`simple-vm`, `simple-dv`), architecture asset - filenames (`architecture-simple.png`), and technical terms ("Simple frame - buffer device"). However, some are in prose: "a simple example" (multiple - pages in `storage/`), "easy ways to fix them" - (`containerized_data_importer.md`), "simplest" as a descriptor for a - workaround option (`installation.md`), and "easy guest-host communication" - (`vsock.md`). While these are not egregious uses, they reflect an opportunity - to adopt more neutral, descriptive language consistent with CNCF inclusive - language guidance. - -**Rating: 3** — No KubeVirt-owned CRD names, feature names, or user-visible -identifiers use non-recommended terminology. The "master" references are -inherited from external URL structures. Occasional use of "simple"/"easy" in -prose is present but not pervasive and is addressable through normal doc -editing. + Yes. Minimizing language is common throughout the documentation, with roughly + 80 occurrences of "simple", "simply", "easy", or "easily" across dozens of + pages (in addition to frequent use of "just"). Many are in explanatory prose + that judges difficulty on the reader's behalf—for example "allows easy + creation of", "which can be simply mounted", "switching the cloud-init data + source to ConfigDrive is as easy as", "it is easily fixed", and "updating ... + is as simple as". A smaller number are legitimate proper nouns or identifiers + that should not be changed, such as the passt project's "Plug A Simple Socket + Transport", the "PCI Simple" Windows device, and example resource names like + `simple-vm` and `simple-dv`. Replacing the subjective prose usages with + concrete descriptions (for example, stating the number of steps) would make + the documentation more inclusive of readers with varying experience levels. + +##### Comment + +The KubeVirt User Guide scores well on naming inclusivity. A review of the +documentation found no KubeVirt-defined utilities, endpoints, class names, or +feature names that use non-recommended terms from the Inclusive Naming +Initiative, and no occurrences of words such as "slave", "whitelist", +"blacklist", or "sanity check". The term "master" does appear, but exclusively +in contexts the project does not control—external URLs and Git branch names, +version path segments in the API reference, a third-party CNI bonding field +(`"master": "eth1"`), a Kubernetes node-label example, and verbatim QEMU/libvirt +command output. Because none of these are names coined by KubeVirt, no renaming +is warranted; the guide is already clean on this dimension. + +The clearer opportunity is the pervasive use of minimizing language. Words like +"simple", "simply", "easy", and "easily" appear roughly 80 times across dozens +of pages, often in explanatory prose that judges difficulty on the reader's +behalf—for example "allows easy creation of", "which can be simply mounted", "as +easy as", and "is as simple as". This phrasing can unintentionally discourage +readers who find a task harder than described, and it rarely adds information. +The most actionable improvement is to replace these subjective qualifiers with +concrete, factual descriptions: state the number of steps, name the single +command involved, or simply remove the adjective. Care should be taken to +preserve legitimate proper nouns and identifiers, such as the passt project's +"Plug A Simple Socket Transport", the "PCI Simple" Windows device, and example +resource names like `simple-vm`. + +To make this sustainable, the project could add the flagged minimizing terms to +its existing yaspeller-based checks or adopt a dedicated inclusive-language +linter in CI. Automating detection would keep new contributions consistent and +reduce the manual review burden, building on the strong naming foundation the +guide already demonstrates. ### Recommendations @@ -588,301 +701,134 @@ needs I see as a novice user: and Getting Started content and ideally for each major section. Mermaid code is recommended and be created initially by AI. -#### Overall - AI - -The KubeVirt user guide is a substantive, professionally maintained -documentation site with 94 Markdown pages covering architecture, installation, -cluster administration, user workloads, compute, networking, storage, and -debugging. The breadth of topic coverage is strong for a CNCF incubating -project. Core strengths include copyable YAML examples throughout, a clean -MkDocs Material presentation, good branding consistency, and active release -notes. - -**The primary friction surface is onboarding.** New users — whether -Kubernetes-native engineers evaluating KubeVirt as an extension or traditional -VM operators migrating from VMware or OpenStack — have no clear, self-contained -path from zero to a running VM entirely within the user guide. The Quickstarts -page delegates immediately to external Killercoda labs with no embedded steps -and no "what to read next" guidance. - -**A secondary friction surface is content fragmentation.** The API reference is -externally hosted and loosely integrated; the main kubevirt.io site uses Jekyll -while the user guide uses MkDocs; governance documentation lives in a separate -repo with no cross-links; and the documentation SIG is on paper but un-staffed. -These gaps compound each other and make the documentation harder to maintain and -harder for new contributors to navigate. - -The underlying technology is sound, the community momentum is real, and the -VMware migration window (Broadcom pricing/licensing upheaval, 2024–2026) creates -a direct adoption opportunity. Closing these documentation gaps is the -highest-leverage action the project can take to convert evaluators into -production users. - -**A third, concrete finding comes from the page-level task analysis**. -(kubevirt-analysis.csv): 266 discrete tasks were identified across 94 pages. Of -these, 66 are high-priority, 86 medium, and 114 low. The high-priority tasks -fall into five clusters — each representing a category of technical debt that -erodes reader trust independently of any structural improvement: - -| Cluster | High-pri tasks | -| ------------------------------------------ | -------------- | -| Unofficial/internal dev images in examples | 17 | -| Broken or stale links | 15 | -| Outdated or removed content | 11 | -| Deprecated API references | 6 | -| User-visible typos in code | 6 | - -These are independent of audience targeting or architecture improvements — they -are factual errors and broken examples that any reader can encounter today. They -should be addressed before or alongside any larger structural work. - #### Information architecture -##### Information Architecture Recommendations - Author - -##### Information Architecture Recommendations - AI - -###### Add section overview pages for every major section - -> Priority: High — 6 new pages identified in kubevirt-analysis.csv - -Every major section of the user guide (Cluster Administration, User Workloads, -Compute, Network, Storage, Debug) is missing an `overview.md` landing page. -Readers who navigate into a section from the top-level nav land directly on the -first content page with no orientation. The task analysis identified this gap -consistently (A03-T01, A04-T01, A05-T01, A06-T01, A07-T01, A10-T01): - -- `cluster_admin/overview.md` -- `user_workloads/overview.md` -- `compute/overview.md` -- `network/overview.md` -- `storage/overview.md` -- `debug_virt_stack/overview.md` - -Each overview page should: describe what the section covers, identify the target -reader (cluster admin vs. VM user), and link to the two or three most important -pages within the section. These are low-word-count pages with high impact on -navigability. - -###### Add a user-facing troubleshooting page - -(virsh, QEMU strace, GDB). There is no troubleshooting page for common end-user -failures. Create `user_workloads/troubleshooting.md` covering: - -- VM stuck in Pending or CrashLoopBackOff -- Network connectivity failures from inside a VM -- CDI image import errors -- Live migration failures -- virtctl connection issues - -This is the most common support escalation path and currently has no -documentation home. - -###### Fix API reference links — scheme and versioning - -> Priority: High - -All in-guide links to the API reference use `http://` and hardcode the -`/api-reference/master/` path. Both are problems: - -- `http://` should be `https://` (security, mixed-content warnings) -- `/master/` links point to the development branch, not the version a user is - running; on older releases these links may describe non-existent fields - -Replace with `https://kubevirt.io/api-reference/` (latest stable) or, better, -introduce a versioned link macro tied to the MkDocs release variable. Surface -the API reference link in the site navigation (currently only on the Welcome -page), not just inline in prose. +The following recommendations for improving the information architecture of the +KubVirt User Guide: + +- Group each section's pages by information type (concept, task, reference) + rather than presenting them as long, flat, undifferentiated lists. Prioritize + the Compute, Cluster Administration, and Storage sections, which currently + list roughly twenty or more mixed pages each. +- Separate API reference pages from task-oriented pages within the Storage + section, for example by clustering `clone_api.md`, `export_api.md`, and + `snapshot_restore_api.md` under a dedicated "Reference" grouping distinct from + task pages such as `hotplug_volumes.md` and `disks_and_volumes.md`. +- Apply consistent sub-groupings across all sections, extending the pattern + already used in User Workloads (its "Monitoring" and "Workloads" clusters) so + every section is easier to scan. +- Rename task pages to lead with a verb that names the user goal (for example, + "Configuring hugepages" instead of "hugepages", or "Live migrating a VM" + instead of "live_migration"), so users can locate content by the task they are + trying to accomplish. +- Promote installation and first-run content out of Cluster Administration into + a clearly labeled "Getting Started" or "Installation" entry near the top of + the navigation. +- Strengthen the new-user path so the Quickstarts page offers first-run guidance + directly rather than mainly linking out to external Killercoda and kubevirt.io + resources. +- Add a consolidated FAQ or troubleshooting hub, and consider relocating the + Virtualization Debugging section from the bottom of the navigation to sit + nearer the task content it supports. +- Treat these as targeted, incremental section-level changes; a full, ground-up + restructure of the top-level information architecture is not required. #### New user content -##### New user content Recommendations - Author - -##### New user Recommendations - AI - -The recommendations in this section were generated by AI. - -###### Create a self-contained "Getting Started" page - -> Priority: High - -The current `quickstarts.md` is a curated list of four external links. It -contains no embedded steps and provides no guidance for a user without access to -Killercoda or a cloud provider. Add a page — either replacing or supplementing -the current Quickstarts — that walks through: - -1. Prerequisites check (Kubernetes cluster, kubectl, virtctl) -2. Install the KubeVirt operator (`kubectl apply`) -3. Wait for operator readiness (with expected output) -4. Create a minimal VM (copy-paste manifest provided) -5. Start the VM and connect via `virtctl console` -6. Stop and delete the VM -7. "What to read next" with three recommended follow-on pages - -This page should be completable without leaving the user guide site. - #### Content maintainability & site mechanics -The recommendations in this section were generated by AI. - -##### Adopt doc versioning via the mike plugin - -> Priority: High - -KubeVirt maintains a support matrix (latest three Kubernetes releases). Users on -older KubeVirt versions currently see docs and API reference links that reflect -the development branch, not their installed version. The MkDocs `mike` plugin -(designed for MkDocs Material + GitHub Pages) enables versioned doc sets with a -version dropdown in the header. Recommended approach: - -- Maintain the latest two KubeVirt major versions -- Mark older versions with a clear deprecation notice -- Replace hardcoded `/master/` API reference links with a version variable - -##### Prepare the directory structure for localization - -> Priority: Medium - -There is an open issue proposing Simplified Chinese (zh-CN) documentation. -Currently the directory structure does not support language subdirectories, -meaning accepting that contribution would require a structural refactor. Enable -the MkDocs Material `i18n` plugin and add a documented convention for how -language variants are organized (`docs/zh-CN/`, etc.), even if only English is -populated initially. Cost is low now; cost grows with every page added. - -##### Enable analytics on the user guide - -> Priority: High (from website analysis) - -The user guide has no analytics configured. Without analytics: - -- 404 errors cannot be detected or triaged -- High-traffic pages cannot be prioritized for quality improvement -- New user drop-off points cannot be identified - -Add a privacy-respecting analytics solution (Plausible is CNCF-friendly and -requires no cookie consent banner) via the `extra.analytics` key in -`mkdocs.yml`. Ensure preview/branch builds have indexing disabled -(`X-Robots-Tag: noindex` via Netlify headers) to avoid polluting production -analytics and search indexes. - -##### Document account custodians - -> Priority: Medium (from website analysis) - -There is no documentation of who owns the analytics account, Google Search -Console, or site-search configuration for the user guide. Add a named section to -CONTRIBUTING.md or the community repo listing the current custodians. This is a -low-effort change that prevents account access loss during maintainer -transitions. - -##### Fix the sitemap URL double-slash - -> Priority: Low - -The root `robots.txt` references the sitemap with a double slash -(`//sitemap.xml`). Correct to `https://kubevirt.io/user-guide/sitemap.xml`. +The following recommendations address the content maintainability of the +KubeVirt user guide. + +- Adopt `mike`, the standard versioning tool for MkDocs Material, to publish + documentation versions that align with KubeVirt product releases so readers + can view docs matching their deployment. +- Add a version selector (dropdown) to the theme configuration so users can + switch between the latest and historical documentation snapshots. +- Document the content-versioning method in the README or CONTRIBUTING files, + including how and when new versions are cut relative to KubeVirt releases. +- Decide early on a localization directory convention (for example, per-language + subdirectories such as `en/` or `zh/`) so the current flat, topic-based layout + can accommodate translations without a disruptive future reorganization. +- Evaluate an internationalization plugin such as `mkdocs-static-i18n` and + document the intended localization approach, even if implementation is + deferred, so contributors can plan content accordingly. +- Preserve the existing maintainability strengths—client-side search, explicit + `.nav.yml` ordering, and the `redirects` map in `mkdocs.yml`—and continue + adding redirect entries whenever pages are moved or renamed to prevent link + rot. #### Content creation processes -The recommendations in this section were generated by AI. - -1. Document a release-docs checklist - -> Priority: High - -There is no documented policy requiring documentation updates as part of the -code release process. Features are regularly released without corresponding user -guide updates, and there is no doc-freeze process or release sign-off gate. Add -to `CONTRIBUTING.md` (or a new `docs/release-process.md`): - -- Which types of code changes require a user guide PR before merge -- Who is responsible for user guide completeness per release (SIG/documentation - or the feature author) -- How the sig/documentation SIG is involved in release sign-off -- What the escalation path is for undocumented features discovered post-release - -##### Staff the documentation SIG - -> Priority: High - -The `sig-list.md` in the community repo lists `sig/documentation` with no -chairs, no contact persons, and no meeting schedule. This means documentation -has no governance home, no release accountability, and no single point of -contact for the CNCF documentation review process. Nominate at least one SIG -chair and add them to the sig-list entry. Even a part-time commitment from an -existing committer is significantly better than the current vacuum. +The following recommendations address the content creation process of the +KubeVirt user guide. + +- Document the OWNERS/Prow approval model directly in `contributing.md`, + including how `/lgtm` and `/approve` work and who contributors should expect + review from, so the approval path is transparent to newcomers. +- Establish and document an expectation that user-facing changes in + `kubevirt/kubevirt` ship with a companion user-guide update, for example + through a release checklist item or a cross-repository issue link, to reduce + documentation drift. +- Add documentation creation and updates as an accountable step in the code + release process so docs are no longer decoupled from KubeVirt's release + cadence. +- Preserve and continue to signpost the existing strengths—the clear + `docs/contributing.md` GitHub workflow, the README's local authoring and + validation guidance (yaspeller and HTMLProofer `make` targets), and the + per-section `OWNERS` delegation to KubeVirt SIGs. +- Keep the automatic `kind/documentation` labeling and per-section `OWNERS` + files current as new topic areas are added under `docs/`, so review + responsibility remains clearly assigned. #### Inclusive language -The recommendations in this section were generated by AI. - -#### Additional Recommendations - -The recommendations in this section were generated by AI. - -##### API developer experience - -The API developer experience deserves dedicated investment. The current user -guide is written primarily for operators ("how do I configure live migration?"), -not for developers ("what fields govern a migration policy and what are their -invariants?"). Specific actions: - -- Add the `kubevirt-api-developer-guide.md` content (or equivalent) as a formal - section of the user guide, covering the Kubernetes → KubeVirt concept mapping - table, `kubectl explain` patterns, client library usage, and - controller/operator development guidance. -- Treat the API reference as a product: ensure every CRD field has a prose - description in the OpenAPI spec (auto-populated from Go source comments), - versioned per release, linked bidirectionally from the user guide. -- Add a tracked issue for populating missing field descriptions in - `staging/src/kubevirt.io/api/core/v1/types.go` — developers currently read Go - source code to understand field intent. - -##### Website consolidation - -From the website analysis: the kubevirt.io web presence is split between -`kubevirt/kubevirt.github.io` (Jekyll, main site) and `kubevirt/user-guide` -(MkDocs, docs). These require separate contribution workflows and tooling. While -full consolidation may be a large undertaking, a near-term improvement would be -to document the two-repo split explicitly for contributors (which repo handles -which content and why), and to ensure the main site's "Documentation" navigation -link always points to the current stable user guide. - -##### Governance link visibility - -From the contributor docs review: `GOVERNANCE.md` exists in `kubevirt/community` -but is not linked from the `kubevirt/kubevirt` README or the user-guide -Contributing page. Add a direct link to governance documentation from both entry -points. Also note the maintainer concentration (majority from a single employer) -and document the project's approach to broadening representation — this is a -common CNCF due-diligence concern for graduation review. +The following recommendations address the inclusive language of the KubeVirt +user guide. + +- Replace subjective minimizing qualifiers such as "simple", "simply", "easy", + "easily", and "just" with concrete, factual descriptions—for example, state + the number of steps, name the single command involved, or remove the adjective + entirely. +- Preserve legitimate proper nouns and identifiers when revising, such as the + passt project's "Plug A Simple Socket Transport", the "PCI Simple" Windows + device, and example resource names like `simple-vm` and `simple-dv`. +- Add the flagged minimizing terms to the existing yaspeller-based checks, or + adopt a dedicated inclusive-language linter or Vale style rule in CI, to + automate detection and keep new contributions consistent. +- Leave the "master" occurrences unchanged, since they appear only in contexts + the project does not own—external URLs and Git branch names, API reference + version paths, a third-party CNI bonding field, a Kubernetes node-label + example, and verbatim QEMU/libvirt command output. +- Maintain the strong naming foundation by continuing to avoid non-recommended + terms from the Inclusive Naming Initiative in any new KubeVirt-defined + utilities, endpoints, class names, or feature names. ## Contributor documentation -Section analysis generated by AI, Claude Sonnet 4.6, and includes the answers to -questions, findings, and rating evaluations. - KubeVirt is an **incubating** project of CNCF. This means that the project should be developing professional-quality documentation alongside the project code. -| Criterion | Rating (1-5) | -| ----------------------------------------- | ------------ | -| Communication methods documented | 5 | -| Beginner friendly issue backlog | 4 | -| "New contributor" getting started content | 4 | -| Project governance documentation | 5 | +| Criterion | [Rating (1-5)] | +| ----------------------------------------- | -------------- | +| Communication methods documented | [rating (1-5)] | +| Beginner friendly issue backlog | [rating (1-5)] | +| “New contributor” getting started content | [rating (1-5)] | +| Project governance documentation | [rating (1-5)] | ### Comments -The KubeVirt documentation provides a well-organized documentation set that can -accommodate recommended improvements without a major restructure. +> AUTHOR NOTE: make any overall comments about the Contributor Documentation +> here. The following sections contain brief assessments of each element of the Contributor Documentation rubric. -The answers and rating paragraphs in this section were generated by AI: +> AUTHOR NOTE: For each heading below, discuss how well the in-scope items meet +> these criteria. Keep in mind that much of the contributor documentation might +> be contained in the documentation repository. (Criteria are copied from +> criteria.md) #### Communication methods documented @@ -893,78 +839,21 @@ We evaluate on the following: - Is there a Slack/Discord/Discourse/etc. community and is it prominently linked from your website? - - **Answer:** Partially. Slack is mentioned in the - [Contributing](https://kubevirt.io/user-guide/contributing/) page of the user - guide ("Visit the KubeVirt community page, participate on Slack"), but it is - not prominently linked from the user-guide homepage or navigation. The - `#virtualization` and `#kubevirt-dev` Slack channels are listed in the - [sig-list](https://github.com/kubevirt/community/blob/main/sig-list.md) in the - community repo. The kubevirt.io/community/ page did not render meaningful - content during testing. Slack presence is documented but not prominently - surfaced from the main site. - - Is there a direct link to your GitHub organization/repository? - - **Answer:** Yes. The Contributing page links directly to the - [KubeVirt GitHub organization](https://github.com/kubevirt) and to specific - repos (user-guide, kubevirt.github.io, community, kubevirt/kubevirt). Every - page also has an "Edit this page" link pointing to the GitHub source. - - Are weekly/monthly project meetings documented? Is it clear how someone can join those meetings? - - **Answer:** Yes. The - [sig-list.md](https://github.com/kubevirt/community/blob/main/sig-list.md) in - the community repo documents a weekly community meeting (Wednesdays 15:00 UTC - via Zoom) and multiple SIG meetings (control-plane, compute, storage, - observability, CI, etc.), each with Zoom links. The Contributing page links to - community resources where these are found. The meeting times, cadences, and - Zoom links are clear. - - Are mailing lists documented? - **Answer:** Yes. The - [kubevirt-dev mailing list](https://groups.google.com/forum/#!forum/kubevirt-dev) - is documented in the sig-list and referenced in the GOVERNANCE.md. A private - [cncf-kubevirt-maintainers](mailto:cncf-kubevirt-maintainers@lists.cncf.io) - list is also documented. These are in the community repo, which is linked from - the user-guide Contributing page. - #### Beginner friendly issue backlog We evaluate on the following: - Are docs issues well-triaged? - - **Answer:** Partially. The user-guide repo has very few open issues (only 2 as - of evaluation), with minimal label usage — one is labeled `kind/enhancement` - and one has no labels. Closed issues show some use of lifecycle labels - (`lifecycle/stale`, `lifecycle/rotten`) indicating a staleness bot is in use, - but active triage with descriptive labels appears limited. - - Is there a clearly marked way for new contributors to make code or - documentation contributions (i.e. a "good first issue" label)? - - **Answer:** Partially. The `good-first-issue` label exists and has been used - (e.g., issue 925 in user-guide, and actively in kubevirt/kubevirt). The - Contributing page explicitly directs new contributors to look for this label. - However, there are currently no open `good-first-issue` issues in the - user-guide repo, making the pathway harder to act on in practice. - + documentation contributions (i.e. a “good first issue” label)? - Are issues well-documented (i.e., more than just a title)? - - **Answer:** Mixed. The open issues visible (e.g., "Proposal: Add Simplified - Chinese (zh-CN) Documentation", "Improve the getting started guides of - KubeVirt") appear to have descriptive titles and likely more body content, but - the overall issue count is very small, making it hard to assess a pattern. - - Are issues maintained for staleness? - **Answer:** Yes. Lifecycle labels (`lifecycle/stale`, `lifecycle/rotten`, - `lifecycle/frozen`) are applied to issues over time, indicating an automated - staleness bot (likely prow/tide) is active in the project's repos. - #### New contributor getting started content Open source is complex and projects have many processes to manage that. Are @@ -974,29 +863,9 @@ in easily? We evaluate on the following: - Do you have a community repository or section on your website? - - **Answer:** Yes. There is a dedicated - [kubevirt/community](https://github.com/kubevirt/community) GitHub repository - containing governance docs, SIG charters, membership policy, and the sig-list. - The user-guide Contributing page links to it. The kubevirt.io website also has - a `/community/` page, though it did not render substantive content during - evaluation. - - Is there a document specifically for new contributors/your first contribution? - - **Answer:** Yes. The user-guide has a dedicated - [Contributing](https://kubevirt.io/user-guide/contributing/) page with a "Your - first contribution" section that lists suggested repos, explains the - `good-first-issue` label, and describes other ways to get started. - Prerequisites (Git, GitHub workflow, labs) are also clearly listed. - - Do new users know where to get help? - **Answer:** Yes. The user-guide homepage has an explicit "Getting help" - section. The Contributing page directs users to the community page, Slack, and - GitHub issues. The community repo README also lists communication channels. - Help pathways are documented across multiple locations. - #### Project governance documentation One of the CNCF’s core project values is open governance. @@ -1005,78 +874,58 @@ We evaluate on the following: - Is project governance clearly documented? -**Answer:** Yes. KubeVirt's governance documentation is comprehensive and -well-structured in the `kubevirt/community` repository — covering maintainer -roles, SIG/WG charters, a contributor ladder, voting rules, and active -maintainer/emeritus lists. The primary gap is discoverability: the main -`kubevirt/kubevirt` repository does not link to `GOVERNANCE.md` directly. - ### Recommendations -- Add a visible "Community" section to the `kubevirt/kubevirt` README (or expand - the existing one) that lists Slack channels with direct join links, the - mailing list address, and a link to the weekly meeting schedule — mirroring - the detail already in `kubevirt/community/README.md`. -- Fix or replace the `kubevirt.io/community/` page so it renders usable content: - Slack links, meeting schedule, mailing list, and SIG overview. -- Promote the `#virtualization` and `#kubevirt-dev` Slack channel links more - prominently on the user-guide Contributing page (currently only mentioned in - passing with no direct join URL). +> AUTHOR NOTE: Write general recommendations based on the comments from the +> previous section. #### Communication methods documented -KubeVirt documents its communication channels thoroughly in the community repo -and CONTRIBUTING.md, but discoverability from the main website and the -`kubevirt/kubevirt` README could be improved. The `kubevirt.io/community/` page -did not render meaningful content during evaluation, which is a missed -opportunity for new visitors. - #### Beginner friendly issue backlog -The `good-first-issue` label infrastructure exists and is referenced in the -Contributing page, but the user-guide repo has very few open issues overall and -no open `good-first-issue` issues at the time of evaluation. Without an -actionable backlog, new contributors who follow the guidance reach a dead end. +#### New contributor getting started content + +#### Project governance documentation ## Website and infrastructure -Section analysis generated by AI, Claude Sonnet 4.6, and includes the answers to -questions, findings, and rating evaluations. +> AUTHOR NOTE: Pick the CNCF maturity level of the project: KubeVirt is an **incubating** project of CNCF. This means that the project should be developing professional-quality documentation alongside the project code. -| Criterion | Rating (1-5) | -| ------------------------------------------- | ------------ | -| Single-source for all files | 2 | -| Meets min website req. (for maturity level) | 3 | -| Usability, accessibility, and design | 3 | -| Branding and design | 4 | -| Case studies/social proof | 3 | -| SEO, Analytics, and site-local search | 2 | -| Maintenance planning | 3 | -| A11y plan & implementation | 2 | -| Mobile-first plan & impl. | 3 | -| HTTPS access & HTTP redirect | 5 | -| Google Analytics 4 for production only | 1 | -| Indexing allowed for production server only | 2 | -| Intra-site / local search | 4 | -| Account custodians are documented | 1 | +| Criterion | [Rating (1-5)] | +| ------------------------------------------- | -------------- | +| Single-source for all files | [rating (1-5)] | +| Meets min website req. (for maturity level) | [rating (1-5)] | +| Usability, accessibility, and design | [rating (1-5)] | +| Branding and design | [rating (1-5)] | +| Case studies/social proof | [rating (1-5)] | +| SEO, Analytics, and site-local search | [rating (1-5)] | +| Maintenance planning | [rating (1-5)] | +| A11y plan & implementation | [rating (1-5)] | +| Mobile-first plan & impl. | [rating (1-5)] | +| HTTPS access & HTTP redirect | [rating (1-5)] | +| Google Analytics 4 for production only | [rating (1-5)] | +| Indexing allowed for production server only | [rating (1-5)] | +| Intra-site / local search | [rating (1-5)] | +| Account custodians are documented | [rating (1-5)] | ### Comments +> AUTHOR NOTE: make any overall comments about the Website and documentation +> infrastructure here. + The following sections contain brief assessments of each element of the Website and documentation infrastructure rubric. -The KubeVirt user guide is a well-structured, professional documentation site -built with MkDocs Material, hosted on GitHub Pages at `kubevirt.io/user-guide/`. -The site is responsive, visually clean, and covers a comprehensive breadth of -topics. The primary infrastructure gaps are the absence of analytics on the -user-guide site, no documented a11y plan, no explicit account custodians, and -the split between two separate repos for the overall kubevirt.io web presence -(the main site uses Jekyll/kubevirt.github.io; docs use MkDocs/user-guide). -These are addressable gaps for an incubating project moving toward graduation. +> AUTHOR NOTE: for each heading below, discuss how well the in-scope items meet +> these criteria. Keep in mind that much of the website infrastructure criteria +> depend on the tools (static site generator, website framework and hosting, +> analytics tools, etc.) and processes (project CI, release procedures, +> governance, etc.) used to produce the documentation. (Criteria are copied from +> criteria.md) #### Single-source requirement @@ -1095,20 +944,6 @@ submodules][git-submodules]. If a project chooses to keep source files in multiple repos, they need a clearly documented strategy for managing mirrored files and new contributions. -**Finding:** The user-guide documentation source files all reside in a single -repo ([kubevirt/user-guide](https://github.com/kubevirt/user-guide)) under the -`./docs/` directory — this is good. However, the overall kubevirt.io web -presence is split across two repos with different technology stacks: -[kubevirt/kubevirt.github.io](https://github.com/kubevirt/kubevirt.github.io) -(Jekyll, main website) and kubevirt/user-guide (MkDocs, documentation). The user -guide is deployed as a subdirectory (`/user-guide/`) of the main site. These two -repos require separate contribution workflows, separate tooling, and separate CI -pipelines, which is a coordination overhead and potential source of confusion. -Within the user-guide repo itself, source is properly single-sourced. - -**Rating: 2** — The split between two repos and two static site generators for -the combined web presence needs improvement. - #### Minimal website requirements Listed here are the minimal website requirements for projects based on their @@ -1132,18 +967,6 @@ only two levels for which a tech docs analysis can be requested.) https://github.com/cncf/toc/tree/main/process#ii-stages---definitions--expectations [cncf-servicedesk]: https://servicedesk.cncf.io -**Finding:** The user guide is hosted directly on GitHub Pages at -`kubevirt.io/user-guide/` ✅. This docs analysis has been requested ✅. User -docs are comprehensive, covering architecture, installation, cluster -administration, user workloads, compute, networking, storage, debugging, and -release notes — this addresses most stakeholder needs ✅. Stakeholder roles -(cluster admins, users, developers) are implicitly addressed by the site's -navigation structure, though not explicitly documented as personas. CNCF website -guideline compliance has not been fully verified as part of this analysis. - -**Rating: 3** — Meets incubating requirements on hosting, docs breadth, and -having this analysis, with minor gaps in explicit stakeholder documentation. - #### Usability, accessibility and devices Most CNCF websites are accessed from mobile and other non-desktop devices at @@ -1151,58 +974,24 @@ least 10-20% of the time. Planning for this early in your website's design will be much less effort than retrofitting a desktop-first design. - Is the website usable from mobile? - - **Answer:** Yes. MkDocs Material renders a responsive layout on mobile with a - hamburger menu, collapsible navigation, and readable typography. - - Are doc pages readable? - - **Answer:** Yes. Pages use clean typography, good heading hierarchy, and - syntax-highlighted code blocks. - - Are all / most website features accessible from mobile -- such as the top-nav, site search and in-page table of contents? - - **Answer:** Yes. The Material theme's mobile rendering includes the search - input, collapsible nav, and in-page TOC, all accessible from mobile. - - Might a [mobile-first] design make sense for your project? - **Answer:** Given that KubeVirt targets infrastructure/DevOps engineers who - typically work at desktops, mobile-first is less critical, but the current - responsive design is adequate. - [mobile-first]: https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Responsive/Mobile_first Plan for suitable [accessibility][] measures for your website. For example: - Are color contrasts significant enough for color-impaired readers? - - **Answer:** The teal primary color on a white/dark background generally - provides sufficient contrast, though no formal contrast audit has been - documented. - - Are most website features usable using a keyboard only? - - **Answer:** MkDocs Material provides standard keyboard navigation support - (tab, enter, arrow keys for search results), though no explicit keyboard-only - audit is documented. - - Does text-to-speech offer listeners a good experience? - **Answer:** The Material theme includes ARIA labels for navigation elements - and search, providing a reasonable screen reader experience, though it has not - been explicitly tested. - -It is up to each project to set their own guidelines. No explicit a11y -guidelines or audit are documented for this project. +It is up to each project to set their own guidelines. [accessibility]: https://developer.mozilla.org/en-US/docs/Web/Accessibility -**Rating: 3** — The Material theme provides good usability and mobile support by -default; no formal a11y plan or audit is present. - #### Branding and design CNCF seeks to support enterprise-ready open source software. A key aspect of @@ -1212,23 +1001,8 @@ We evaluate on the following: - Is there an easily recognizable brand for the project (logo + color scheme) clearly identifiable? - - **Answer:** Yes. The KubeVirt logo (cube icon) and teal color scheme are - consistently applied across the user guide and main website. - - Is the brand used across the website consistently? - - **Answer:** Yes. The MkDocs Material theme is configured with the KubeVirt - icon, teal primary/accent colors, and a custom favicon. The branding is - consistent throughout all pages. - -- Is the website's typography clean and well-suited for reading? - - **Answer:** Yes. Material Design's Roboto typeface provides clean, legible - typography with appropriate heading hierarchy and code font differentiation. - -**Rating: 4** — Branding is well-executed and consistent; meets or exceeds -standards for an incubating project. +- Is the website’s typography clean and well-suited for reading? #### Case studies/social proof @@ -1239,38 +1013,11 @@ We evaluate on the following: - Are there case studies available for the project and are they documented on the website? - - **Answer:** Not in the user guide. The main kubevirt.io site features a logo - wall of 14 end users (ARM, Cloudflare, NVIDIA, Microsoft, Oracle, Red Hat, - CoreWeave, SUSE, etc.) and 17 vendors. However, there are no dedicated - narrative case studies in the user guide. - - Are there user testimonials available? - - **Answer:** No explicit testimonials are present in the user guide or visibly - on the main site. - - Is there an active project blog? - - **Answer:** Yes. The kubevirt.io main site has an active blog with recent - posts (KubeVirt v1.8 release announcement in March 2026, security audit - results, technical articles on migration networks, and more). - - Are there community talks for the project and are they present on the website? - - **Answer:** Not prominently on the user guide. The Contributing page links to - a New Contributor session recording on YouTube, but there is no dedicated - talks/conference section in the user guide. - - Is there a logo wall of users/participating organizations? - **Answer:** Yes, on the main kubevirt.io homepage — End Users, Vendors, and - Integrations sections show logos with links. - -**Rating: 3** — Strong adopter presence on the main site; the user guide itself -lacks case studies and talks sections, but this is typical for a doc-focused -sub-site. - #### SEO, Analytics and site-local search SEO helps users find your project and it's documentation, and analytics helps @@ -1281,56 +1028,16 @@ We evaluate on the following: - Analytics: - Is analytics enabled for the production server? - - **Answer:** No analytics is configured in the user guide's `mkdocs.yml` or - detected in the live site HTML. The main kubevirt.io site has an Adobe - Analytics comment tag in its HTML, but no analytics code was found in the - user-guide site. - - Is analytics disabled for all other deploys? - - **Answer:** Not applicable — no analytics is configured at all for the user - guide. - - If your project used Google Analytics, have you migrated to GA4? - - **Answer:** Google Analytics is not used on the user guide. No GA4 - configuration was found. - - Can Page-not-found (404) reports easily be generated from you site analytics? Provide a sample of the site's current top-10 404s. - - **Answer:** No — without analytics configured on the user guide, 404 reports - cannot be generated from it. - - Is site indexing supported for the production server, while disabled for website previews and builds for non-default branches? - - **Answer:** A `sitemap.xml` is generated at - `kubevirt.io/user-guide/sitemap.xml` ✅, and the root `robots.txt` contains - only a `Sitemap:` directive with no `Disallow` rules — meaning the production - site is fully indexable. However, there is no evidence that Netlify preview - builds (which are configured via `netlify.toml`) have indexing disabled via - `X-Robots-Tag` headers or a preview-specific `robots.txt`. - - Is local intra-site search available from the website? - - **Answer:** Yes. The MkDocs `search` plugin is configured in `mkdocs.yml` and - confirmed functional in the live site HTML. Search is available in the header - on all pages. - - Are the current custodian(s) of the following accounts clearly documented: analytics, Google Search Console, site-search (such as Google CSE or Algolia) - **Answer:** No. There is no documentation of account custodians for analytics, - Google Search Console, or site search anywhere in the user-guide repo or - community repo. - -**Rating: 2** — Intra-site search is well-implemented, a sitemap exists, and -HTTPS is enforced. However, the absence of any analytics on the user guide, no -confirmed indexing control for preview builds, and no custodian documentation -are significant gaps. - #### Maintenance planning Website maintenance is an important part of project success, especially when @@ -1340,129 +1047,36 @@ We evaluate on the following: - Is your website tooling well supported by the community (i.e., Hugo with the Docsy theme) or commonly used by CNCF projects (our recommended tech stack?) - - **Answer:** MkDocs with the Material theme is widely used in the CNCF - ecosystem and is well-supported by the community. It is not the - CNCF-recommended Hugo/Docsy stack, but is a valid and popular alternative. The - `mkdocs-awesome-nav` and `mkdocs-redirects` plugins are also well-maintained. - The main kubevirt.io site uses Jekyll, a different stack, which adds - complexity. - - Are you actively cultivating website maintainers from within the community? - - **Answer:** The OWNERS and OWNERS_ALIASES files in the user-guide repo define - approvers and reviewers. The Contributing page encourages docs contributions. - No explicit program for cultivating dedicated website maintainers is - described. - - Are site build times reasonable? - - **Answer:** Yes. MkDocs builds are typically fast (seconds to low minutes for - a site this size). Netlify is configured for preview builds and GitHub Pages - for production. Build configuration is in `netlify.toml`. - - Do site maintainers have adequate permissions? - **Answer:** The repo uses Kubernetes-style OWNERS files for managing merge - permissions. GitHub repository access is managed through the kubevirt GitHub - organization. This appears adequate. - -**Rating: 3** — The toolchain is solid and appropriate. The two-repo split -(Jekyll + MkDocs) adds some maintenance overhead but each site is individually -well-maintained. - #### Other - Is your website accessible via HTTPS? - - **Answer:** Yes. The site responds with HTTP/2 200 over HTTPS at - `https://kubevirt.io/user-guide/`. ✅ - - Does HTTP access, if any, redirect to HTTPS? - **Answer:** Yes. An HTTP request to `http://kubevirt.io/user-guide/` returns - HTTP 301 redirecting to the HTTPS URL. ✅ - -**Rating: 5** — Full marks; HTTPS is enforced with proper HTTP→HTTPS redirect -via GitHub Pages. - ### Recommendations -#### Single-source requirement +> AUTHOR NOTE: Write general recommendations based on the comments from the +> previous section. -Consider consolidating the kubevirt.io web presence into a single repo or -establishing a clearly documented strategy for the two-repo split. One practical -approach would be to serve the user guide from a `docs/` subdirectory of the -main `kubevirt.github.io` repo using a git submodule pointing to the -`user-guide` repo, or to document explicitly that the two repos are -intentionally separate with different purposes. A migration guide for -contributors explaining which repo handles which content would reduce confusion. -Alternatively, migrating the main kubevirt.io site to MkDocs Material (to match -the user guide) would unify tooling and contributor experience. +#### Single-source requirement #### Minimal website requirements -Explicitly document the target stakeholder personas (cluster administrators, VM -users, KubeVirt developers) and their documentation needs. This would help the -project track coverage gaps and prioritize new documentation work. Consider also -performing a formal CNCF website guidelines review to identify any outstanding -compliance gaps before graduation. - #### Usability, accessibility and devices -Adopt a basic accessibility policy and document it (even a brief statement in -CONTRIBUTING.md is sufficient). Run a [WAVE](https://wave.webaim.org/) or -[axe](https://www.deque.com/axe/) accessibility audit on at least the homepage -and a representative doc page, and address any high-severity findings. Consider -enabling the MkDocs Material for automated a11y checks during build. - #### Branding and design -No significant action required. Branding is consistent and professional. -Consider adding the CNCF Incubating project badge to the user-guide homepage to -reinforce project maturity signaling. - #### Case studies/social proof -Consider adding a "Who uses KubeVirt?" section or page to the user guide that -links to the adopters logos on the main site, notable blog posts from end users, -and any conference talk recordings. This would help new evaluators of the -project quickly understand the production usage breadth without needing to -navigate away from the docs. - #### SEO, Analytics and site-local search -This is the highest-priority gap. The following actions are recommended: - -1. **Add analytics to the user guide**: Configure a privacy-respecting analytics - solution (e.g., [Plausible](https://plausible.io/), which is CNCF-friendly - and privacy-focused, or GA4) in `mkdocs.yml` under the `extra.analytics` key. - This enables 404 detection and traffic visibility. -2. **Disable indexing on preview/non-production builds**: Add a - `X-Robots-Tag: noindex` header or include a preview-specific `robots.txt` - disallow in Netlify configuration for branch deploys and PR previews. -3. **Document account custodians**: Create a section in the community repo (or - the user-guide CONTRIBUTING.md) listing the named owners of the analytics - account, Google Search Console, and any other site-related accounts. -4. **Improve robots.txt**: The current root-level `robots.txt` only has a - sitemap reference. Verify that the sitemap URL is correct (note: it has a - double slash `//sitemap.xml` which should be fixed) and consider adding - explicit `Allow` directives for clarity. - #### Maintenance planning -Document a succession plan for website maintainers in the community repo — who -approves content changes, who has GitHub Pages deployment access, and how new -maintainers are onboarded. Consider consolidating the user-guide and main site -under a single `sig/documentation` ownership model (the documentation SIG -already exists in sig-list.md but has no chairs or contact listed — this should -be filled in). - #### Other -No action required for HTTPS/HTTP redirect — this is handled correctly by GitHub -Pages. - #### References and notes ##### Rating values @@ -1475,6 +1089,14 @@ The numeric rating values used in this document are as follows 4. Meets or exceeds standards 5. Exemplary +[criteria]: ../criteria.md +[implementation]: ./implementation.md +[issues list]: ./issues-list.md +[project-website]: ?fixme-target-dne=_PROJECT-WEBSITE_ +[Rating (1-5)]: #rating-values +[rfc-spec]: https://www.rfc-editor.org/rfc/rfc2119 +[website guidelines]: ../../website-guidelines-checklist.md + ## Appendices ### Appendix A - Technical Debt & Content Accuracy - AI @@ -1619,198 +1241,3 @@ the source is the doc. Fix immediately. **Recommendation:** These are the most visible credibility issues in the release notes. Retrieve the complete text from the corresponding GitHub PR or release tag and complete both entries. - -### Appendix B - Medium and low recommendations - AI - -#### Information Architecture - -##### Refactor large reference pages into focused task pages - -> Priority: Medium - -`disks_and_volumes.md` is the largest single page in the guide and attempts to -cover conceptual explanation, reference tables, and task instructions in one -document. Split it into: - -- `disks_and_volumes/concepts.md` — what volumes and disks are, how they relate - to PVCs -- `disks_and_volumes/reference.md` — field catalog and type descriptions -- `disks_and_volumes/tasks/` — individual how-tos (attach a DataVolume, hotplug - a disk, etc.) - -Similarly, `network_binding_plugins.md` and `hook-sidecar.md` describe -architecture well but provide no end-to-end worked examples. Add at minimum one -complete task per page that a reader can follow from start to finish. - -##### Add a "Coming from VMware" onboarding path - -> Priority: Medium (High if targeting the 2024–2026 VMware migration window) - -Organizations migrating from VMware bring traditional virtualization -expectations and limited Kubernetes fluency. There is no documentation bridge. -Create a short guide that maps: - -| VMware concept | KubeVirt equivalent | Notes/gaps | -| ----------------- | --------------------------------------- | ---------- | -| vCenter / vSphere | Kubernetes API server + KubeVirt | | -| VM template | VirtualMachineInstancetype + Preference | | -| vMotion | Live migration | | -| Datastore | PVC / DataVolume (CDI) | | -| vDS / portgroup | Multus / secondary networks | | -| Snapshots | VM snapshot API | | - -Be honest about gaps (DRS-style scheduling, mature backup tooling, deep Windows -integration) — building trust with evaluators is more valuable than obscuring -shortcomings they will discover in production. - -##### Create an end-to-end instancetype/preference tutorial - -> Priority: Medium - -`instancetypes.md` and `creating_it_pref.md` describe the instancetype model but -do not walk through a complete "VM from scratch using instancetype and -preference" scenario. Add a single tutorial page that goes from defining an -instancetype and preference through creating a VM and verifying resource -allocation. This scenario represents the KubeVirt-recommended path for VM -resource management and deserves a dedicated page. - -#### New User Content - -##### Expand the Basic Use page into a meaningful getting-started flow - -> Priority: Medium (A04-B02-T01 in kubevirt-analysis.csv) - -`user_workloads/basic_use.md` is currently a thin page that covers VM start/stop -commands but does not walk through a meaningful first-use scenario. It is the -logical destination after Installation but does not build on it. Expand to -include: - -- The VM/VMI distinction (A04-B01-T01 — many readers do not understand that a - `VirtualMachine` manages lifecycle while a `VirtualMachineInstance` is the - running unit) -- Start, stop, restart, and migrate commands in a single reference table - (A04-B01-T03) -- How to verify the VM is running (status fields, events) -- A "What to read next" pointer to Networking and Storage pages - -This is distinct from the "Getting Started" self-contained quickstart (§1 above) -— the Basic Use page is the permanent reference for the most common operations, -while the quickstart is the narrative onboarding experience. - -##### Add a common prerequisites section to Quickstarts - -> Priority: Medium (A02-T04 in kubevirt-analysis.csv) - -The Quickstarts page links to four separate external environments but does not -list shared prerequisites. A reader needs kubectl, virtctl, and cluster access -for all of them. Add a brief prerequisites block at the top of `quickstarts.md`: - -- `kubectl` configured against a cluster -- `virtctl` plugin installed (link to virtctl_client_tool.md) -- Minimum cluster resources (RAM, CPUs) -- KubeVirt operator installed (link to installation.md) - -Also ensure the `virtctl_client_tool.md` page covers macOS and Windows install -instructions (A04-B05-T01, currently high-priority missing content) so the -prerequisites link is useful for all readers. - -##### Add "What to read next" sections - -> Priority: Medium - -The Quickstarts page and the Installation page both end without directing users -to their next logical step. Add a brief "Next steps" section to each: - -- After Quickstarts: point to User Workloads → Basic Use, and Storage → CDI -- After Installation: point to Quickstarts, then Feature Gates and Authorization - -##### Add an audience orientation statement to the homepage - -> Priority: Medium - -From the high-level review (kubevirt-reviews.md): the guide currently tries to -serve Kubernetes-native engineers and traditional VM operators simultaneously -without acknowledging either. Add a brief orientation paragraph near the top of -`index.md` that identifies who the guide is for and what prerequisite knowledge -is assumed (Kubernetes familiarity, cluster access). This sets expectations -correctly and reduces early drop-off from users who feel lost. - -#### Content creation process - -##### Curate an active good-first-issue backlog - -> Priority: Medium (from contributor docs review) - -The `good-first-issue` label infrastructure exists but the user-guide repo has -no open good-first issues at the time of review. New contributors who follow the -contributing guide reach a dead end. Maintain a rolling set of 3–5 small, -well-scoped documentation tasks: - -- Missing feature documentation stubs -- Broken or stale links -- Pages needing a "What to read next" section -- Prose uses of "simple"/"easy" that can be replaced - -Activate the `help-wanted` label and use it consistently as a triage step for -incoming issues. - -##### Consolidate new contributor onboarding - -> Priority: Medium (from contributor docs review) - -New contributor guidance is spread across at least four locations: -`kubevirt/kubevirt` CONTRIBUTING.md, `docs/getting-started.md`, the user-guide -Contributing page, and the community repo. Create a single "New Contributor -Guide" landing page that aggregates the full end-to-end path, and add a "Quick -Start (docs only)" path at the top for contributors who only want to fix -documentation — the current guide leads immediately into -Bazel/Docker/nested-virtualization setup that is unnecessary for documentation -contributions. - -##### Establish a release notes template - -> Priority: Medium (A08-T01 in kubevirt-analysis.csv) - -The `release_notes.md` file has inconsistent formatting across releases, two -incomplete entries (a truncated note, a placeholder — see Technical Debt §7), -and no documented template for contributors. Create a release notes template -(either a comment block at the top of `release_notes.md` or a separate -`docs/release-notes-template.md`) that specifies: - -- Required sections per release (breaking changes, new features, deprecations, - bug fixes, known issues) -- How to link to the corresponding GitHub milestone -- The Kubernetes support matrix line format (several releases are missing this) -- Who is responsible for completing the notes before release tag - -This pairs with the release-docs checklist recommendation (#1 above). - -#### Inclusive Language - -##### Replace prose uses of "simple" and "easy" - -> Priority: Low - -Approximately 45 occurrences of "simple" or "easy" exist across 42 files. Most -are in code example resource names (acceptable) but some are in prose that can -be improved: - -| Current | Suggested replacement | -| ----------------------- | -------------------------------------------- | -| "a simple example" | "the following example", "a minimal example" | -| "easy ways to fix them" | "common ways to resolve them" | -| "simplest" | "the most direct" / "the least-invasive" | - -This is a low-effort improvement that aligns with CNCF inclusive language -guidance from the [Inclusive Naming Initiative](https://inclusivenaming.org). - -##### Track the "master" API reference URL path - -> Priority: Low - -All deep-links to the API reference use -`/api-reference/master/definitions.html`. This is the upstream API reference -site's URL structure, not a KubeVirt-owned naming choice — but it does embed a -non-recommended term in user-visible URLs. Open an issue (or add a link-checker -CI note) to flag when the upstream adopts a non-master stable URL, at which -point all deep-links can be updated in a single pass. From 5ab7d05801a18ed3c6d405335c4b0dad21c1a734 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 22 Jul 2026 11:03:06 -0700 Subject: [PATCH 24/49] spelling fixes Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/analysis.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/analyses/2026/kubevirt/analysis.md b/analyses/2026/kubevirt/analysis.md index f483ff09..84c08298 100644 --- a/analyses/2026/kubevirt/analysis.md +++ b/analyses/2026/kubevirt/analysis.md @@ -333,7 +333,7 @@ with its "Monitoring" and "Workloads" clusters—would make each section easier scan and would bring the guide closer to the clear concept/task/reference separation modeled by the Prometheus documentation. -Two secondary issues also affect wayfinding. First, most pages are named as +Two secondary issues also affect navigation. First, most pages are named as nouns or feature names ("hugepages", "live_migration", "host-devices") rather than as goal-oriented verb phrases, which makes it harder for users to locate content by the task they are trying to accomplish. Second, the new-user path is @@ -493,7 +493,7 @@ and enforces ordering explicitly through per-directory `.nav.yml` files rather than relying on alphabetical sorting. Search is enabled out of the box via the `search` plugin, and the contribution workflow is well documented: the README describes forking, signing commits, and local validation through `make` targets -that check spelling (yaspeller) and links (HTMLProofer). Page moves are handled +that check spelling and links (HTMLProofer). Page moves are handled gracefully through an extensive `redirects` map in `mkdocs.yml`, which preserves old URLs and reduces link rot. These are strong maintainability practices. @@ -535,7 +535,7 @@ We evaluate on the following: links to community resources such as the Code of Conduct, membership policy, and governance. The repository README complements this with the local authoring workflow: where content lives (`./docs`), how to sign commits, and - how to validate changes with `make` targets for spelling (yaspeller) and link + how to validate changes with `make` targets for spelling and link checking (HTMLProofer) before opening a PR. - Does the code release process account for documentation creation & updates? @@ -575,7 +575,7 @@ target for first-time contributors, and links to essential community documents such as the Code of Conduct, membership policy, and governance. The README reinforces this with practical authoring guidance: where content lives, how to sign commits, and how to validate changes locally with `make` targets that run -spelling (yaspeller) and link (HTMLProofer) checks. Together these give new and +spelling and link (HTMLProofer) checks. Together these give new and returning contributors a well-signposted, repeatable path to landing changes. Ownership and review are handled robustly through Kubernetes-style OWNERS files @@ -664,7 +664,7 @@ preserve legitimate proper nouns and identifiers, such as the passt project's resource names like `simple-vm`. To make this sustainable, the project could add the flagged minimizing terms to -its existing yaspeller-based checks or adopt a dedicated inclusive-language +its existing spelling check checks or adopt a dedicated inclusive-language linter in CI. Automating detection would keep new contributions consistent and reduce the manual review burden, building on the strong naming foundation the guide already demonstrates. @@ -1089,13 +1089,13 @@ The numeric rating values used in this document are as follows 4. Meets or exceeds standards 5. Exemplary -[criteria]: ../criteria.md + ## Appendices From dc92f7d93d955e5532719aa137678246eb4bd911 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 22 Jul 2026 11:38:08 -0700 Subject: [PATCH 25/49] spell and format fixes Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/analysis.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/analyses/2026/kubevirt/analysis.md b/analyses/2026/kubevirt/analysis.md index 84c08298..9e7cf461 100644 --- a/analyses/2026/kubevirt/analysis.md +++ b/analyses/2026/kubevirt/analysis.md @@ -493,9 +493,9 @@ and enforces ordering explicitly through per-directory `.nav.yml` files rather than relying on alphabetical sorting. Search is enabled out of the box via the `search` plugin, and the contribution workflow is well documented: the README describes forking, signing commits, and local validation through `make` targets -that check spelling and links (HTMLProofer). Page moves are handled -gracefully through an extensive `redirects` map in `mkdocs.yml`, which preserves -old URLs and reduces link rot. These are strong maintainability practices. +that check spelling and links (HTMLProofer). Page moves are handled gracefully +through an extensive `redirects` map in `mkdocs.yml`, which preserves old URLs +and reduces link rot. These are strong maintainability practices. The most significant gap is content versioning. The site publishes a single "latest" build from the `main` branch, with no versioning tooling such as `mike` @@ -535,8 +535,8 @@ We evaluate on the following: links to community resources such as the Code of Conduct, membership policy, and governance. The repository README complements this with the local authoring workflow: where content lives (`./docs`), how to sign commits, and - how to validate changes with `make` targets for spelling and link - checking (HTMLProofer) before opening a PR. + how to validate changes with `make` targets for spelling and link checking + (HTMLProofer) before opening a PR. - Does the code release process account for documentation creation & updates? @@ -575,8 +575,8 @@ target for first-time contributors, and links to essential community documents such as the Code of Conduct, membership policy, and governance. The README reinforces this with practical authoring guidance: where content lives, how to sign commits, and how to validate changes locally with `make` targets that run -spelling and link (HTMLProofer) checks. Together these give new and -returning contributors a well-signposted, repeatable path to landing changes. +spelling and link (HTMLProofer) checks. Together these give new and returning +contributors a well-signposted, repeatable path to landing changes. Ownership and review are handled robustly through Kubernetes-style OWNERS files enforced by Prow. The root `OWNERS` and `OWNERS_ALIASES` define active reviewers @@ -775,7 +775,7 @@ KubeVirt user guide. cadence. - Preserve and continue to signpost the existing strengths—the clear `docs/contributing.md` GitHub workflow, the README's local authoring and - validation guidance (yaspeller and HTMLProofer `make` targets), and the + validation guidance (spell check and HTMLProofer `make` targets), and the per-section `OWNERS` delegation to KubeVirt SIGs. - Keep the automatic `kind/documentation` labeling and per-section `OWNERS` files current as new topic areas are added under `docs/`, so review @@ -793,9 +793,9 @@ user guide. - Preserve legitimate proper nouns and identifiers when revising, such as the passt project's "Plug A Simple Socket Transport", the "PCI Simple" Windows device, and example resource names like `simple-vm` and `simple-dv`. -- Add the flagged minimizing terms to the existing yaspeller-based checks, or - adopt a dedicated inclusive-language linter or Vale style rule in CI, to - automate detection and keep new contributions consistent. +- Add the flagged minimizing terms to the existing spell check checks, or adopt + a dedicated inclusive-language linter or Vale style rule in CI, to automate + detection and keep new contributions consistent. - Leave the "master" occurrences unchanged, since they appear only in contexts the project does not own—external URLs and Git branch names, API reference version paths, a third-party CNI bonding field, a Kubernetes node-label From dcfcfe8d83c9bbc4f05edaef28b856b1ef08204d Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 22 Jul 2026 11:53:41 -0700 Subject: [PATCH 26/49] spelling Signed-off-by: Bruce Hamilton --- .cspell.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.cspell.yml b/.cspell.yml index ffac7344..5e26160a 100644 --- a/.cspell.yml +++ b/.cspell.yml @@ -75,3 +75,7 @@ words: - portgroup - Multus - multus + - Falco + - inclusivity + - passt + \ No newline at end of file From 7a7a6483b09af3ade366e967c1192bc7fcd37780 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 22 Jul 2026 12:01:54 -0700 Subject: [PATCH 27/49] prettier on cspell Signed-off-by: Bruce Hamilton --- .cspell.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/.cspell.yml b/.cspell.yml index 5e26160a..9e83f742 100644 --- a/.cspell.yml +++ b/.cspell.yml @@ -78,4 +78,3 @@ words: - Falco - inclusivity - passt - \ No newline at end of file From b342124f3a7619a5f9280bf85750b9f1fbcdb864 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Mon, 27 Jul 2026 20:58:19 -0700 Subject: [PATCH 28/49] finished AI update Signed-off-by: Bruce Hamilton --- .cspell.yml | 1 + analyses/2026/kubevirt/analysis.md | 573 ++++++++++++++++++----------- 2 files changed, 358 insertions(+), 216 deletions(-) diff --git a/.cspell.yml b/.cspell.yml index 9e83f742..d5affcf4 100644 --- a/.cspell.yml +++ b/.cspell.yml @@ -78,3 +78,4 @@ words: - Falco - inclusivity - passt + - WCAG diff --git a/analyses/2026/kubevirt/analysis.md b/analyses/2026/kubevirt/analysis.md index 9e7cf461..b9d3d542 100644 --- a/analyses/2026/kubevirt/analysis.md +++ b/analyses/2026/kubevirt/analysis.md @@ -234,7 +234,7 @@ Virtualization Debugging: - Overview needs examples of debugging scenarios. -#### Information architecture (AI) +#### Information architecture The overall structure (pages/subpages/sections/subsections) of your project documentation. We evaluate on the following: @@ -242,213 +242,105 @@ documentation. We evaluate on the following: - Is there high level conceptual/"About" content? Is the documentation feature complete? (i.e., each product feature is documented) - Yes to conceptual content. The top-level `architecture.md` explains the - service-oriented architecture and component stack, and the Welcome page - (`index.md`) together with most section indexes provide "About"-style framing. - Feature coverage is largely complete: the 94-page guide documents live - migration, CPU and memory hotplug, hugepages, NUMA, host devices, storage - import/export/snapshot/clone, network binding plugins, and ARM64. A few - features are described only as mechanisms rather than with full task coverage. + Yes. The guide provides high-level conceptual content. The [Architecture](docs/architecture.md) page gives a technical and conceptual overview of the KubeVirt components, the service-oriented design, and the layered virtualization stack, and the Welcome page introduces each major section of the guide. + + The documentation is broadly feature complete. Major product areas each have dedicated sections: cluster administration, user workloads, compute, network, and storage. Individual features such as live migration, CPU and memory hotplug, hugepages, NUMA, instance types and preferences, snapshots, volume export, and network binding plugins each have their own pages. Coverage is wide enough that most shipped features have at least a conceptual description. - Are there step-by-step instructions (tasks, tutorials) documented for features? - Mostly yes. Most feature pages include procedures with copy-pasteable - `kubectl` and `virtctl` examples, and the Welcome page links to external - hands-on labs. Presentation is inconsistent, however: only about 20 of 94 - pages use explicit numbered steps, and many procedures are presented as prose - interspersed with command blocks (for example, `user_workloads/basic_use.md`). - Converting multi-step procedures to numbered steps would make tasks easier to - follow. + Yes. Most feature pages include step-by-step instructions with copy-paste capable shell and YAML examples. For example, the [live migration](docs/compute/live_migration.md) page walks through enabling the feature, initiating and canceling a migration, and configuring a dedicated migration network, and the [creating VirtualMachines](docs/user_workloads/creating_vms.md) page shows how to build manifests with `virtctl`. + + For tutorials, the guide links out to external interactive labs and quickstarts (Killercoda, minikube, kind, and cloud providers) from both the Welcome and Quickstarts pages rather than hosting long-form tutorials inline. This keeps hands-on learning paths available, though they live outside the user guide itself. - Are there any key features which are documented but missing task documentation? - Yes, a few. `network/network_binding_plugins.md` and - `user_workloads/hook-sidecar.md` describe mechanisms without end-to-end worked - examples, and `user_workloads/virtctl_client_tool.md` covers only downloading - and installing `virtctl` rather than providing a consolidated command - reference. Adding a complete task walkthrough for each would close these gaps. + Some pages lean conceptual or reference-oriented and would benefit from added task steps, but there are no major features that are described without any actionable guidance. A few areas mix concept and procedure heavily (for example, migration strategies and some networking topics), where a reader must extract the steps from surrounding explanation. + + The most common gap is depth rather than absence: certain advanced features document the "what" and configuration fields well but provide fewer end-to-end, goal-oriented walkthroughs. Reviewers should confirm that newer features listed in recent release notes each have a corresponding task page. - Is the "happy path"/most common use case documented? Does task and tutorial content demonstrate atomicity and isolation of concerns? (Are tasks clearly named according to user goals?) - The happy path is not documented as a single flow: - `cluster_admin/installation.md` and `user_workloads/basic_use.md` are never - chained into an "install to first running VM" tutorial, and `quickstarts.md` - is only a short list of external links. Atomicity is partial. Most task pages - are goal-named, but oversized pages such as `storage/disks_and_volumes.md` - (roughly 2,160 lines) combine many loosely related tasks and concepts. Task - naming is inconsistent: `compute/live_migration.md` mixes verb-phrase headings - ("Enabling the live-migration support", "Canceling a live migration") with - noun-phrase headings ("Limitations", "Migration Status Reporting"). + Yes. The happy path is documented. A new user can follow installation, then create and access a virtual machine, which covers the most common use case. The quickstarts and labs reinforce this path for first-time users. + + Task content generally demonstrates atomicity and isolation of concerns, and headings are largely named according to user goals using verb or gerund phrases, such as "Creating VirtualMachines on a cluster", "Enabling the live-migration support", "Initiate live migration", and "Configuring a migration network on a cluster". This makes individual tasks easy to scan and follow. A minority of headings are noun-based topic labels rather than goal phrases, so naming is strong but not fully consistent. - If the documentation does not suffice, is there a clear escalation path for users needing more help? (FAQ, Troubleshooting) - Partially. The Welcome page includes a "Getting help" section linking to file - a bug, the mailing list, and Slack, which is a good external escalation path. - However, there is no in-documentation FAQ or user-facing troubleshooting page; - `debug_virt_stack/` is developer-oriented. A user troubleshooting page would - provide first-line help before external channels. + Yes. The Welcome page provides a "Getting help" section that links to filing bugs on GitHub, the kubevirt-dev mailing list, and the community Slack channel, giving users a clear escalation path. + + There is also a dedicated Virtualization Debugging section covering log verbosity, privileged node debugging, virsh commands, and running QEMU under strace or gdb, and several feature pages include debugging notes. However, there is no single, consolidated FAQ or troubleshooting landing page, so common problems and their fixes are spread across individual pages rather than centralized. - If the product exposes an API, is there a complete reference? - Partially. A complete API reference exists but is hosted externally and linked - from `index.md`. The links use `http://` and deep-link to `master`-pinned - paths, so they are neither secure nor version-stable. Co-hosting or linking a - versioned `https://` reference would make it durable and release-accurate. + Yes. KubeVirt exposes a Kubernetes-style API, and the Welcome page links to the generated API reference at kubevirt.io/api-reference, which provides a complete, versioned reference for the custom resources and fields. + + Because the reference is generated from source and hosted separately from the user guide, it stays current with releases but is one click removed from the task content. Cross-linking specific fields from task pages to the reference would tighten the connection between instructions and reference material. - Is content up to date and accurate? - Yes. `release_notes.md` is current (v1.8.0) and feature coverage reflects - recent capabilities. Content is generally accurate; the main freshness risk is - the externally hosted, `master`-pinned API reference, which can drift from - released versions. + Yes. The content is current. The release notes document releases through v1.8.0 (released March 2026, built for Kubernetes v1.35), and feature pages reference current resources, feature gates, and `virtctl` subcommands consistent with recent releases. + + Accuracy appears high overall, with concrete command output and manifests shown inline. As with any fast-moving project, reviewers should periodically verify that examples and feature-gate names match the latest release, since some pages describe features that graduate through alpha, beta, and GA over time. + +- Restructure needed? + + False. A restructure of the content is not needed. The information architecture is sound: content is organized into clear conceptual, task, and reference layers, navigation order is deliberately controlled per section, and features are grouped logically by domain (cluster administration, user workloads, compute, network, storage). Improvements should focus on incremental additions — a consolidated troubleshooting/FAQ entry point, tighter cross-linking to the API reference, and more consistent goal-oriented headings — rather than reorganizing the existing structure. ##### Comment -The KubeVirt User Guide is organized into clear, domain-oriented top-level -sections (Architecture, Quickstarts, Cluster Administration, User Workloads, -Compute, Network, Storage, Release Notes, Contributing, and Virtualization -Debugging), and navigation order is explicitly controlled through `.nav.yml` -files rather than left to alphabetization. This gives the guide a predictable -structure that maps reasonably well to the two implied personas—cluster -administrators and workload owners—and the presence of dedicated conceptual -content in `architecture.md` and an entry point in `quickstarts.md` is a solid -foundation. The overall shape of the site is sound and does not require a -ground-up rebuild. - -The most significant architectural weakness is that conceptual, task, and -reference information are interleaved within sections rather than separated by -information type. The Storage section, for example, places API reference pages -(`clone_api.md`, `export_api.md`, `snapshot_restore_api.md`) alongside -task-oriented pages (`hotplug_volumes.md`, `disks_and_volumes.md`) in a single -flat list, and Compute and Cluster Administration present roughly twenty pages -each in long, largely undifferentiated lists. Readers cannot easily tell whether -a given page teaches a concept, walks through a task, or documents an API -surface. Introducing consistent sub-groupings—as User Workloads already does -with its "Monitoring" and "Workloads" clusters—would make each section easier to -scan and would bring the guide closer to the clear concept/task/reference -separation modeled by the Prometheus documentation. - -Two secondary issues also affect navigation. First, most pages are named as -nouns or feature names ("hugepages", "live_migration", "host-devices") rather -than as goal-oriented verb phrases, which makes it harder for users to locate -content by the task they are trying to accomplish. Second, the new-user path is -thin: the Quickstarts page mainly links out to external Killercoda and -kubevirt.io resources, and installation is nested inside Cluster Administration -rather than surfaced as a clearly labeled "Getting Started" or "Installation" -entry near the top of the information architecture. The escalation path (bug -tracker, mailing list, and Slack) is present on the landing page, but there is -no consolidated FAQ or troubleshooting hub beyond the debugging section, which -sits at the very bottom of the navigation after Contributing. - -To improve the architecture, group each section's pages by information type and -use case, rename task pages to lead with a verb that names the user goal, -promote installation and first-run content into a clearly labeled -getting-started entry high in the navigation, and consider relocating -Virtualization Debugging nearer the task content it supports. These are -targeted, incremental changes rather than a wholesale reorganization. - -Is a restructure of the content needed? False. The top-level information -architecture is fundamentally sound; the guide needs targeted section-level -reorganization, clearer separation of information types, and improved page -naming rather than a full restructure. +The KubeVirt user guide has a solid information architecture. Content is organized into clear domains — cluster administration, user workloads, compute, network, and storage — and each section uses an explicit navigation order rather than alphabetical sorting, so related tasks sit together in a logical reading sequence. The guide also layers the three information types well: conceptual material (the Architecture page and per-section overviews), task material (step-by-step pages with copy-paste capable shell and YAML examples), and reference material (release notes and the generated API reference). Most task headings are named after user goals using verb or gerund phrases, such as "Creating VirtualMachines on a cluster" and "Enabling the live-migration support," which makes pages easy to scan. + +The most valuable improvement would be a single, consolidated troubleshooting and FAQ entry point. Today, help is available through the "Getting help" links and a capable Virtualization Debugging section, but common problems and their fixes are scattered across individual feature pages. A dedicated troubleshooting landing page — organized by symptom and linking out to the relevant debugging topics — would give users a predictable escalation path when a task page alone does not resolve their issue. The Prometheus documentation (https://prometheus.io/docs) is a good model here: it keeps concepts, tasks, and reference clearly separated while still offering obvious paths to deeper help. + +Two smaller refinements would tighten the architecture further. First, tutorials currently live outside the guide as external labs and quickstarts; surfacing an explicit, in-guide learning path (or at least a clearly labeled "Tutorials" grouping that frames those external resources) would help new users find hands-on content without leaving the site. Second, the API reference is complete but hosted separately and only reachable from the Welcome page — cross-linking specific custom resources and fields from the task pages that use them would connect instructions to reference material more directly. Normalizing the minority of noun-based headings into goal-oriented verb phrases would also improve scanning and consistency. + +Restructure needed: False. The existing structure is sound and does not require reorganization. The recommended changes are incremental additions — a troubleshooting/FAQ hub, clearer tutorial signposting, tighter cross-linking to the API reference, and more consistent heading phrasing — that build on the current architecture rather than replace it. + +Rating: 4 - Meets or exceeds standards #### New user content New users are the most avid users of documentation, and need content specifically for them. We evaluate on the following: -- Is "getting started" clearly labeled? ("Getting started", "Installation", - "First steps", etc.) +- Is "getting started" clearly labeled? ("Getting started", "Installation", "First steps", etc.) - Partially. There is no page or navigation entry titled "Getting Started" or - "First steps." New-user entry points are instead spread across a top-level - "Quickstarts" item, an "Installation" page (the first page under Cluster - Administration), and a "Try it out" section on the homepage. "Installation" is - clearly labeled, but the absence of a single, consistently named - getting-started landing page makes the on-ramp harder to find than a - conventional "Getting Started" label would. + Partially. There is no page or navigation entry titled "Getting Started" or "First steps." New-user entry points are instead spread across a top-level "Quickstarts" item, an "Installation" page (the first page under Cluster Administration), and a "Try it out" section on the homepage. "Installation" is clearly labeled, but the absence of a single, consistently named getting-started landing page makes the on-ramp harder to find than a conventional "Getting Started" label would. - Is installation documented step-by-step? - Yes. `cluster_admin/installation.md` lists prerequisites and then provides - copy-pasteable, ordered commands to deploy the KubeVirt operator, create the - KubeVirt CR, wait for the components to become available, and verify the - running pods. It also covers optional steps such as software emulation - fallback and node-placement restrictions. + Yes. `cluster_admin/installation.md` lists prerequisites and then provides copy-pasteable, ordered commands to deploy the KubeVirt operator, create the KubeVirt CR, wait for the components to become available, and verify the running pods. It also covers optional steps such as software emulation fallback and node-placement restrictions. - If needed, are multiple OSes documented? - Partially. Because KubeVirt is a Kubernetes add-on, the installation guide - documents multiple Kubernetes platforms (Kubernetes, OKD, k3OS) and both the - x86_64 and Arm64 architectures, rather than host operating systems. - Host-OS-specific concerns are limited to AppArmor and SELinux notes. - Separately, guest operating systems (for example Windows and Linux) are - documented under User Workloads. There is no per-Linux-distribution - installation walkthrough, which is reasonable for a cluster add-on but worth - noting. + Partially. Because KubeVirt is a Kubernetes add-on, the installation guide documents multiple Kubernetes platforms (Kubernetes, OKD, k3OS) and both the x86_64 and Arm64 architectures, rather than host operating systems. Host-OS-specific concerns are limited to AppArmor and SELinux notes. Separately, guest operating systems (for example Windows and Linux) are documented under User Workloads. There is no per-Linux-distribution installation walkthrough, which is reasonable for a cluster add-on but worth noting. - Do users know where to go after reading the getting started guide? - Partially. The installation page ends with optional topics (network plugins, - node placement) rather than an explicit "Next steps" pointer to creating a - first virtual machine. Users must navigate on their own to "User Workloads" - (for example `basic_use.md` or `creating_vms.md`). Adding a clear "Next steps" - link from installation to the first-VM tasks would close this gap. + Partially. The installation page ends with optional topics (network plugins, node placement) rather than an explicit "Next steps" pointer to creating a first virtual machine. Users must navigate on their own to "User Workloads" (for example `basic_use.md` or `creating_vms.md`). Adding a clear "Next steps" link from installation to the first-VM tasks would close this gap. -- Is your new user content clearly signposted on your site's homepage or at the - top of your information architecture? +- Is your new user content clearly signposted on your site's homepage or at the top of your information architecture? - Yes. The homepage lists all major sections and includes prominent "Try it - out," "KubeVirt Labs," and "Getting help" sections, and "Quickstarts" appears - near the top of the navigation. However, much of this new-user content relies - on external links (Killercoda, minikube/kind/cloud quickstarts, and the - kubevirt.io labs) rather than in-guide getting-started material, so the - signposting leads users off-site fairly quickly. + Yes. The homepage lists all major sections and includes prominent "Try it out," "KubeVirt Labs," and "Getting help" sections, and "Quickstarts" appears near the top of the navigation. However, much of this new-user content relies on external links (Killercoda, minikube/kind/cloud quickstarts, and the kubevirt.io labs) rather than in-guide getting-started material, so the signposting leads users off-site fairly quickly. - Is there sample code or other example content that can easily be copy-pasted? - Yes. The documentation makes extensive use of fenced and indented code blocks - with ready-to-run examples, including installation shell commands, - `virtctl create vm` invocations, `kubectl` lifecycle commands, and YAML - manifests. These are formatted for direct copy-paste. + Yes. The documentation makes extensive use of fenced and indented code blocks with ready-to-run examples, including installation shell commands, `virtctl create vm` invocations, `kubectl` lifecycle commands, and YAML manifests. These are formatted for direct copy-paste. ##### Comment -The KubeVirt User Guide gives new users a solid technical starting point, but -its on-ramp is fragmented across several differently named locations. New-user -material is split between a top-level "Quickstarts" entry, an "Installation" -page buried as the first item under "Cluster Administration," and "Try it out" -and "KubeVirt Labs" sections on the homepage. Because none of these is labeled -"Getting Started" or "First Steps," newcomers must piece the path together -themselves. Consolidating these entry points under a single, clearly named -"Getting Started" section—ideally as its own top-level navigation item—would -match the convention new users expect and provide one obvious front door. The -Falco getting-started guide (https://falco.org/docs/getting-started/) is a good -model for this unified structure. - -The installation documentation itself is strong: it lists prerequisites, -provides ordered and copy-pasteable operator and CR commands, shows how to -verify a healthy deployment, and covers multiple platforms (Kubernetes, OKD, -k3OS) and architectures (x86_64 and Arm64). The main weakness is that the guide -leans heavily on external links—Killercoda, the minikube/kind/cloud quickstarts, -and the kubevirt.io labs—rather than an in-guide walkthrough that carries a -reader from a fresh cluster to a running virtual machine. Bringing at least one -complete, end-to-end "deploy KubeVirt and launch your first VM" tutorial into -the guide would reduce reliance on off-site content and give users a -self-contained first success. - -The most actionable single improvement is to close the gap between installation -and first use. The installation page currently ends with optional topics -(network plugins, node placement) and offers no explicit "Next steps" pointer -toward the first-VM tasks in "User Workloads" (such as `basic_use.md` and -`creating_vms.md`). Adding a clear "Next steps" call-to-action at the end of -installation, linking directly to creating and accessing a first virtual -machine, would give new users an unbroken path from setup to a working workload. +The KubeVirt user guide gives new users a solid technical starting point, but its on-ramp is fragmented across several differently named locations. New-user material is split between a top-level "Quickstarts" entry, an "Installation" page buried as the first item under "Cluster Administration," and "Try it out" and "KubeVirt Labs" sections on the homepage. Because none of these is labeled "Getting Started" or "First Steps," newcomers must piece the path together themselves. Consolidating these entry points under a single, clearly named "Getting Started" section—ideally as its own top-level navigation item—would match the convention new users expect and provide one obvious front door. The Falco getting-started guide (https://falco.org/docs/getting-started/) is a good model for this unified structure. + +The installation documentation itself is strong: it lists prerequisites, provides ordered and copy-pasteable operator and CR commands, shows how to verify a healthy deployment, and covers multiple platforms (Kubernetes, OKD, k3OS) and architectures (x86_64 and Arm64). The main weakness is that the guide leans heavily on external links—Killercoda, the minikube/kind/cloud quickstarts, and the kubevirt.io labs—rather than an in-guide walkthrough that carries a reader from a fresh cluster to a running virtual machine. Bringing at least one complete, end-to-end "deploy KubeVirt and launch your first VM" tutorial into the guide would reduce reliance on off-site content and give users a self-contained first success. + +The most actionable single improvement is to close the gap between installation and first use. The installation page currently ends with optional topics (network plugins, node placement) and offers no explicit "Next steps" pointer toward the first-VM tasks in "User Workloads" (such as `basic_use.md` and `creating_vms.md`). Adding a clear "Next steps" call-to-action at the end of installation, linking directly to creating and accessing a first virtual machine, would give new users an unbroken path from setup to a working workload. + +Rating: 3 - Meets standards #### Content maintainability & site mechanics @@ -519,6 +411,8 @@ without a disruptive reorganization. In the near term, documenting the intended approach—even if implementation is deferred—would help contributors plan content accordingly. +Rating: 3 - Meets standards + #### Content creation processes Documentation is only as useful as it is accurate and well-maintained, and @@ -600,6 +494,8 @@ update—for example, a release checklist item or a cross-repository issue link that documentation creation is an accountable part of shipping features rather than an afterthought. +Rating: 4 - Meets or exceeds standards + #### Inclusive language Creating inclusive project communities is a key goal for all CNCF projects. @@ -669,6 +565,8 @@ linter in CI. Automating detection would keep new contributions consistent and reduce the manual review burden, building on the strong naming foundation the guide already demonstrates. +Rating: 3 - Meets standards + ### Recommendations #### Overall - Author @@ -706,32 +604,14 @@ needs I see as a novice user: The following recommendations for improving the information architecture of the KubVirt User Guide: -- Group each section's pages by information type (concept, task, reference) - rather than presenting them as long, flat, undifferentiated lists. Prioritize - the Compute, Cluster Administration, and Storage sections, which currently - list roughly twenty or more mixed pages each. -- Separate API reference pages from task-oriented pages within the Storage - section, for example by clustering `clone_api.md`, `export_api.md`, and - `snapshot_restore_api.md` under a dedicated "Reference" grouping distinct from - task pages such as `hotplug_volumes.md` and `disks_and_volumes.md`. -- Apply consistent sub-groupings across all sections, extending the pattern - already used in User Workloads (its "Monitoring" and "Workloads" clusters) so - every section is easier to scan. -- Rename task pages to lead with a verb that names the user goal (for example, - "Configuring hugepages" instead of "hugepages", or "Live migrating a VM" - instead of "live_migration"), so users can locate content by the task they are - trying to accomplish. -- Promote installation and first-run content out of Cluster Administration into - a clearly labeled "Getting Started" or "Installation" entry near the top of - the navigation. -- Strengthen the new-user path so the Quickstarts page offers first-run guidance - directly rather than mainly linking out to external Killercoda and kubevirt.io - resources. -- Add a consolidated FAQ or troubleshooting hub, and consider relocating the - Virtualization Debugging section from the bottom of the navigation to sit - nearer the task content it supports. -- Treat these as targeted, incremental section-level changes; a full, ground-up - restructure of the top-level information architecture is not required. +- Add a single, consolidated troubleshooting and FAQ entry point, organized by symptom, that links out to the relevant pages in the Virtualization Debugging section and to the scattered debugging notes on individual feature pages. This gives users a predictable escalation path when a task page alone does not resolve their issue. +- Preserve the current overall structure rather than reorganizing it. The domain-based sections (cluster administration, user workloads, compute, network, storage) and explicit per-section navigation order are sound; focus effort on incremental additions instead of a restructure. +- Surface an explicit, in-guide learning path for new users. Add a clearly labeled "Tutorials" grouping that frames the existing external labs and quickstarts (Killercoda, minikube, kind, cloud providers) so hands-on content is discoverable without leaving the guide. +- Cross-link the API reference from the task pages that use each resource. Link specific custom resources and fields (for example, from live migration, instance types, and storage pages) to their entries at kubevirt.io/api-reference so instructions connect directly to reference material. +- Normalize the minority of noun-based topic headings into goal-oriented verb or gerund phrases, matching the existing style of headings such as "Creating VirtualMachines on a cluster" and "Enabling the live-migration support." This improves scanning and consistency across pages. +- Audit task coverage depth against recent release notes. Confirm that each newer feature (for example, those introduced through v1.8.0) has a corresponding end-to-end, goal-oriented task page, not just a conceptual or configuration-field description. +- Separate concept from procedure on pages that currently interleave them, such as the migration strategies and some networking topics, so readers can extract the steps without reading through surrounding explanation. +- Periodically verify that inline examples, command output, and feature-gate names match the latest release, since features graduate through alpha, beta, and GA over time and can drift from the documented behavior. #### New user content @@ -837,23 +717,68 @@ to reach you. We evaluate on the following: -- Is there a Slack/Discord/Discourse/etc. community and is it prominently linked - from your website? +- Is there a Slack/Discord/Discourse/etc. community and is it prominently linked from your website? + + Yes. The user guide's home page links directly to the KubeVirt Slack channel (`https://kubernetes.slack.com/messages/virtualization`) in its "Getting help" section, and the Contributing page invites readers to "participate on Slack" through the KubeVirt community page. The broader project website (`https://kubevirt.io/community/`) also surfaces the Slack workspace and channels alongside a forum. Within the user guide, the Slack link is reasonably visible on the landing page, but it appears only in a short "Getting help" list rather than in the persistent site navigation, so its prominence is limited. + - Is there a direct link to your GitHub organization/repository? -- Are weekly/monthly project meetings documented? Is it clear how someone can - join those meetings? + + Yes. The Contributing page links to the KubeVirt GitHub organization (`https://github.com/kubevirt`) and to individual repositories such as `user-guide`, `kubevirt`, `containerized-data-importer`, and `community`. The home page's "Getting help" section links directly to the issue tracker (`https://github.com/kubevirt/kubevirt/issues`). Direct GitHub links appear consistently throughout the guide. + +- Are weekly/monthly project meetings documented? Is it clear how someone can join those meetings? + + Not within the user guide itself. The guide does not state the cadence of community meetings or provide direct joining instructions; instead, the Contributing page defers to the community page to "learn about local meetups and events." The linked community page (`https://kubevirt.io/community/`) does document recurring community meetings and embeds a public Google Calendar (`kubevirt@cncf.io`) that readers can use to join. However, someone reading only the user guide would not find meeting times, cadence, or a join link without following that external link. + - Are mailing lists documented? + Yes. The home page's "Getting help" section links to the kubevirt-dev mailing list (`https://groups.google.com/forum/#!forum/kubevirt-dev`), which is also reachable from the community page. The mailing list is documented, though it is presented as a bare link without describing its purpose or how it differs from Slack or the forum. + +##### Comment + +The KubeVirt user guide provides a solid foundation of communication links for both users and contributors. The home page's "Getting help" section and the Contributing page together surface the Slack channel, the kubevirt-dev mailing list, the GitHub organization and its key repositories, and a pointer to the wider community page. As a result, readers have clear starting points to reach the project and its maintainers. + +The most significant gap is project meetings. The user guide does not document meeting cadence, times, or how to join; it only links to the community page for "meetups and events." Because those details live entirely on the external community page, a reader who stays within the user guide cannot learn when community meetings happen or how to attend. Adding a short "Community meetings" subsection that names the cadence and includes the public calendar link would close this gap and keep the information where contributors are already reading. + +Discoverability of the channels that are present could also be stronger. The Slack, mailing list, and issue links appear only in a brief list near the bottom of the landing page, and the Contributing page's community links are spread across several sections. Consolidating these into a single, clearly labeled "Community and communication" section—covering Slack, the forum, the mailing list, meetings, and social accounts—would make them easier to find. Giving each channel a one-line description of its purpose would also help newcomers choose where to ask a question versus where to follow announcements. + +Overall, the essential channels are documented and correctly linked, but meetings are absent from the guide itself and the presentation is uneven. Small, well-placed additions would move this area from adequate to strong. + +Rating: 3 - Meets standards + #### Beginner friendly issue backlog We evaluate on the following: - Are docs issues well-triaged? + + Documentation issues are only partially triaged. At the time of review the user-guide repository had four open issues, and three of them carried no labels at all; only one was categorized (with `kind/enhancement`). The repository does provide a complete triage label taxonomy (`kind/*`, `triage/accepted`, `triage/needs-information`, `sig/documentation`, and others), and closed issues show that labels such as `kind/bug` and `kind/enhancement` were applied over time. However, `triage/accepted` is rarely used, and the currently open backlog is largely uncategorized, so triage is inconsistent in practice. + - Is there a clearly marked way for new contributors to make code or documentation contributions (i.e. a “good first issue” label)? + + Yes, a mechanism exists and is documented, but it is currently underused. The user-guide repository has a `good-first-issue` label that has been applied to 24 issues historically, and the contributing page explicitly tells newcomers to "look for any labeled 'good-first-issue', which are triaged to help new contributors." Two caveats reduce its effectiveness. First, there are currently zero open `good-first-issue` items in both the user-guide and the core kubevirt/kubevirt repositories, so a new contributor arriving today finds an empty beginner backlog. Second, the repository has two near-duplicate labels — the hyphenated `good-first-issue` that the team actually uses and the standard spaced `good first issue` that is unused — which is inconsistent and prevents GitHub's native "Contribute" tab from surfacing these issues. + - Are issues well-documented (i.e., more than just a title)? + + Yes. Issues generally contain substantive descriptions rather than bare titles. Bug reports follow a template with **Description**, **What you expected**, and **URL** sections, and enhancement requests use the feature-request template. The open issues ranged from roughly 400 to nearly 1,900 characters of body text; for example, the Simplified Chinese documentation proposal includes detailed context about the contributing team and scope. This indicates issues are typically actionable and provide enough information to begin work. + - Are issues maintained for staleness? + Yes, staleness is actively — and aggressively — managed by the shared KubeVirt Prow automation. Issues progress through `lifecycle/stale` and `lifecycle/rotten` and are then auto-closed, with `lifecycle/frozen` available to exempt long-lived items. Many closed user-guide issues carry the `lifecycle/rotten` label, and the core kubevirt/kubevirt repository currently shows roughly 31 stale, 32 rotten, and 30 frozen open issues. The main risk is that valid but unattended issues (including enhancements) are closed purely for inactivity rather than being triaged or preserved, so the backlog stays small partly through automated closure. + +##### Comment + +The KubeVirt user guide has the building blocks of a healthy beginner-friendly issue backlog, but the pieces are not consistently applied. A dedicated `good-first-issue` label exists and has been used on two dozen issues over time, and the contributing page clearly tells newcomers to look for it. Issues are generally well written: bug reports and feature requests follow templates with description, expectation, and URL fields, so most issues give a contributor enough context to start work rather than just a title. Staleness is handled automatically through the shared Prow lifecycle bot, which moves inactive issues through `lifecycle/stale` and `lifecycle/rotten` before closing them. + +The main gap is that the beginner backlog is effectively empty and the currently open issues are under-triaged. At the time of review there were no open `good-first-issue` items in either the user-guide or the core repository, so a new contributor who follows the documentation's advice finds nothing to pick up. Of the small number of open documentation issues, most carried no labels at all — no `kind/*`, no `sig/documentation`, and no `triage/accepted` — which means the backlog is not being actively categorized even though the label taxonomy is available. + +A specific, fixable inconsistency is the presence of two near-duplicate labels: the hyphenated `good-first-issue` that the team actually applies and the standard spaced `good first issue` that sits unused. GitHub's native "Contribute" experience and the good-first-issues discovery tooling key off the standard spaced label, so the project's real beginner issues are invisible to those channels. Consolidating on the standard label (or aliasing consistently) would immediately widen discovery. + +Finally, the aggressive auto-close behavior deserves attention. Because inactive issues — including valid enhancements — are closed as `lifecycle/rotten` rather than triaged or frozen, the backlog stays small in part by discarding work rather than curating it. A light triage pass that accepts, labels, and where appropriate freezes beginner-suitable issues would turn the existing automation and labels into a genuinely inviting on-ramp for new contributors. + +Rating: 3 - Meets standards + + #### New contributor getting started content Open source is complex and projects have many processes to manage that. Are @@ -863,9 +788,29 @@ in easily? We evaluate on the following: - Do you have a community repository or section on your website? + + Yes, both exist. KubeVirt maintains a dedicated `kubevirt/community` repository that holds governance, the membership policy and checklist, a maintainers list, per-SIG and working-group directories, community meeting information, and a code of conduct. The project website also has a community section at https://kubevirt.io/community/, and the user guide's contributing page links to it directly. New contributors therefore have a clear, discoverable home for community structure and processes. + - Is there a document specifically for new contributors/your first contribution? + + Yes. The user guide's [Contributing](https://kubevirt.io/user-guide/contributing/) page is the canonical getting-started document, and the community repository's own contributor file simply redirects to it, which avoids duplication. The page includes a "Prerequisites" section, a "Your first contribution" section that points newcomers to `good-first-issue` labeled work and to low-barrier documentation and community repositories, separate guidance for code contributors, a list of important community resources (code of conduct, membership policy, governance), and a link to a New Contributor session recording. This is a well-structured first-contribution path rather than a bare pointer to the issue tracker. + - Do new users know where to get help? + Yes, though the help information is somewhat scattered and minimal in places. The user guide's landing page has a "Getting help" section listing the issue tracker, the `kubevirt-dev` mailing list, and the `#virtualization` Slack channel. The contributing page additionally points to the community page and the project's social channels, and the community repository README lists both the `#virtualization` and `#kubevirt-dev` Slack channels. The main weaknesses are that the user guide's "Getting help" section is only three bullets placed at the bottom of the index page, it does not link the community page, and it omits the `#kubevirt-dev` Slack channel, so the help entry points are not fully consistent across sources. + +##### Comment + +KubeVirt provides strong new contributor getting started content. The user guide's Contributing page serves as a single, well-organized entry point that covers prerequisites, a clear "Your first contribution" section, separate tracks for documentation and code contributors, and links to essential community resources such as the code of conduct, membership policy, and governance. Importantly, the community repository's own contributor file redirects to this page rather than duplicating it, so there is one canonical source of truth. This structure reflects a deliberate onboarding path rather than a bare pointer to the issue tracker. + +The project also gives newcomers a real community home. The `kubevirt/community` repository documents SIGs and working groups, community meetings, membership progression, and maintainers, and the website exposes a companion community section that the contributing page links to directly. Combined with a linked New Contributor session recording, a first-time contributor has both written and video onboarding material and a clear picture of how the community is organized. + +The main opportunity for improvement is the "Getting help" experience, which is thinner and less consistent than the rest of the onboarding content. In the user guide it is a three-bullet section at the bottom of the landing page that lists the issue tracker, mailing list, and the `#virtualization` Slack channel, but it omits the community page and the `#kubevirt-dev` Slack channel that appear in other sources. Consolidating these entry points and surfacing them more prominently would remove ambiguity about where to ask questions. + +A second, smaller gap connects to the beginner issue backlog: the contributing page tells newcomers to look for `good-first-issue` items, but that backlog is currently empty, so a motivated first-timer following the documentation can reach a dead end. Keeping a small pool of curated beginner issues would let the otherwise excellent onboarding content deliver on its promise. + +Rating: 4 - Meets or exceeds standards + #### Project governance documentation One of the CNCF’s core project values is open governance. @@ -874,6 +819,22 @@ We evaluate on the following: - Is project governance clearly documented? +Yes. Project governance is clearly and comprehensively documented, and the user guide points contributors to it. The community repository contains a dedicated `GOVERNANCE.md` that covers the membership policy, maintainer responsibilities and selection, meetings, CNCF resources, the code of conduct, off-boarding and removing maintainers, voting, SIGs, subprojects, working groups, and roles and organization management. It is complemented by a `MAINTAINERS.md` that lists current maintainers with their areas of responsibility and employers, tracks emeritus maintainers, and is kept in sync with the CNCF project-maintainers list. A `membership_policy.md` document defines a full contributor ladder — from new contributor through org member, reviewer, approver, SIG chair, subproject lead, and working-group chair — with explicit requirements, responsibilities, privileges, and an inactivity policy. An autogenerated `sig-list.md` (built from `sigs.yaml`) enumerates the SIGs, working groups, chairs, contacts, and meeting schedules. + +From the user guide's own perspective, the contributing page surfaces the governance material by linking to the project governance document, the membership policy, the code of conduct, and the AI contribution policy under its "Important community resources" section. The main limitation is discoverability rather than content: governance is only reachable through that one list on the contributing page, and the user guide has no dedicated governance or community landing page in its own navigation. The governance documentation itself, however, is thorough, versioned, and aligned with CNCF expectations. + +##### Comment + +KubeVirt's project governance documentation is a clear strength. The `kubevirt/community` repository provides a dedicated `GOVERNANCE.md` that addresses the full range of governance concerns: the membership policy, maintainer responsibilities and selection, meetings, voting, off-boarding and removal of maintainers, code of conduct, and the organization of SIGs, subprojects, and working groups. This is backed by a `MAINTAINERS.md` that names current maintainers and their areas of responsibility, records emeritus maintainers, and is explicitly kept in sync with the CNCF project-maintainers list. Together these documents give contributors an unambiguous picture of who leads the project and how decisions are made. + +The contributor ladder is especially well defined. The membership policy lays out each role — from new contributor through org member, reviewer, approver, SIG chair, subproject lead, and working-group chair — with concrete requirements, responsibilities, privileges, and an inactivity policy that explains how roles are maintained or lapse. The autogenerated SIG list, produced from a machine-readable `sigs.yaml`, keeps the list of groups, chairs, contacts, and meeting times consistent and current. This structure reflects mature, CNCF-aligned governance rather than a token document. + +The primary opportunity for improvement is discoverability from within the user guide itself. Governance is reachable only through a single "Important community resources" list on the contributing page; the user guide's own navigation has no dedicated community or governance entry point. A reader browsing the documentation site would not easily find how the project is governed without first landing on the contributing page. + +Because the analysis is scoped to the user guide, a light improvement would be to surface governance more prominently — for example, a short "How KubeVirt is governed" pointer or a community landing page that links to `GOVERNANCE.md`, the maintainers list, and the membership ladder. The underlying governance content is comprehensive and current; the gap is purely one of navigation from the documentation site. + +Rating: 4 - Meets or exceeds standards + ### Recommendations > AUTHOR NOTE: Write general recommendations based on the comments from the @@ -881,12 +842,44 @@ We evaluate on the following: #### Communication methods documented +- Add a dedicated "Community and communication" section to the user guide that consolidates Slack, the forum, the kubevirt-dev mailing list, community meetings, and social accounts in one clearly labeled place, rather than spreading these links across the home page and Contributing page. +- Document community meetings within the guide itself: state the cadence (for example, weekly or monthly), list the meeting times, and include the public Google Calendar link (`kubevirt@cncf.io`) so readers can join without leaving the guide. +- Give each communication channel a one-line description of its purpose so newcomers know where to ask a question, where to hold discussions, and where to follow announcements (for example, Slack for real-time chat, the mailing list or forum for longer discussions). +- Improve the discoverability of existing links by surfacing the Slack, mailing list, and GitHub links more prominently—such as in the persistent site navigation or a footer—instead of only in a short "Getting help" list near the bottom of the landing page. +- Clarify how the mailing list, the forum, and Slack relate to one another, since all three are currently presented as bare links; a brief note on when to use each avoids confusion for first-time contributors. +- Keep the community page and the user guide consistent so that channels documented on `kubevirt.io/community` (meetings, calendar, YouTube, social accounts) are either mirrored or clearly linked from the guide, ensuring readers who stay in the user guide are not missing key channels. + #### Beginner friendly issue backlog +- Consolidate the duplicate labels by standardizing on the GitHub-native `good first issue` label (spaced) and retiring or aliasing the hyphenated `good-first-issue`, so beginner issues appear in GitHub's "Contribute" tab and good-first-issue discovery tooling. Update the reference on the contributing page to match the chosen label. +- Maintain a small, non-empty pool of beginner issues. Periodically identify documentation gaps, typos, and small feature-doc updates and file them as `good first issue` so a new contributor always finds something to pick up. +- Triage the currently open backlog. Apply `kind/*` and `sig/documentation` labels to unlabeled issues, and use `triage/accepted` to signal that an issue is ready to be worked on. +- Add a `help wanted` complement for slightly larger but still approachable tasks, and reference both `good first issue` and `help wanted` on the contributing page so contributors understand the difference. +- Preserve valuable issues from aggressive auto-close by applying `lifecycle/frozen` (or promptly triaging) to still-relevant enhancements and documentation requests, rather than letting them reach `lifecycle/rotten` and close for inactivity alone. +- Keep issue quality high by continuing to use the description/expectation/URL templates, and add a short "good first issue" checklist to those templates (affected page, expected outcome, pointers to relevant docs) so beginner issues are self-contained. +- Link directly to a filtered beginner view from the contributing page — for example, the repository's `good first issue` label query — so newcomers reach actionable issues in one click instead of browsing the full issue list. +- Publish a lightweight triage cadence (for example, a periodic documentation-issue triage during a SIG or community meeting) to keep labeling, acceptance, and staleness decisions consistent over time. + #### New contributor getting started content +- Consolidate and strengthen the "Getting help" section on the user guide landing page so it lists all primary channels in one place: the `#virtualization` and `#kubevirt-dev` Slack channels, the `kubevirt-dev` mailing list, the community page, and the issue tracker. +- Make the "Getting help" information easier to find by linking to it from the contributing page and considering a more prominent placement than the bottom of the index page. +- Keep a small, curated pool of open `good-first-issue` items so that newcomers who follow the "Your first contribution" guidance always have actionable work, rather than reaching an empty backlog. +- Add a direct, filtered link from the contributing page to the current `good-first-issue` list (for example, a saved label query) so first-timers reach real issues in one click. +- Ensure help and community entry points are consistent across the user guide, the contributing page, and the `kubevirt/community` README, since they currently list slightly different channels. +- Consider adding a brief "how to ask a good question" note or expected-response-time guidance near the help channels so new contributors know what to include and where questions are best directed. +- Continue using the community repository's redirect-to-canonical approach for contributor docs, and periodically verify that all "get started" links across repositories still resolve to the single canonical contributing page. +- Optionally surface the New Contributor session recording and the community meeting schedule closer to the "Your first contribution" section so newcomers can quickly find live, synchronous ways to get onboarded. + #### Project governance documentation +- Improve discoverability from the documentation site by adding a short "How KubeVirt is governed" pointer or a dedicated community/governance landing page that links to `GOVERNANCE.md`, the maintainers list, and the membership ladder, rather than relying solely on the contributing page's resource list. +- Surface the governance links in the user guide navigation (for example, under a community or contributing section) so readers can reach them without first knowing to open the contributing page. +- Add a brief, plain-language summary of the governance model and the contributor ladder in the user guide, with a clear link out to the authoritative documents in the community repository, so newcomers get an overview without reading the full policy. +- Continue keeping `MAINTAINERS.md` synchronized with the CNCF project-maintainers list, and note the last-reviewed date on the maintainers and governance documents so readers can gauge currency. +- Ensure the SIG list and its meeting details remain generated from `sigs.yaml`, and link the SIG list from the user guide so contributors can find the right group and meeting to join. +- Cross-link related governance artifacts (code of conduct, membership policy, AI contribution policy, and voting process) from a single place so contributors can navigate the full set without hunting across repositories. + ## Website and infrastructure > AUTHOR NOTE: Pick the CNCF maturity level of the project: @@ -974,23 +967,40 @@ least 10-20% of the time. Planning for this early in your website's design will be much less effort than retrofitting a desktop-first design. - Is the website usable from mobile? + + Yes. The live pages include a responsive viewport meta tag (`width=device-width,initial-scale=1`), and the Material for MkDocs theme is mobile-first and responsive, so the layout adapts to small screens. + - Are doc pages readable? -- Are all / most website features accessible from mobile -- such as the top-nav, - site search and in-page table of contents? -- Might a [mobile-first] design make sense for your project? -[mobile-first]: - https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Responsive/Mobile_first + Yes. Pages use the theme's clean Roboto typography, clear heading hierarchy, an in-page table of contents, admonitions, and syntax-highlighted code blocks, all of which support comfortable reading on the documentation site. -Plan for suitable [accessibility][] measures for your website. For example: +- Are all / most website features accessible from mobile -- such as the top-nav, site search and in-page table of contents? + + Yes. The primary navigation (rendered as tabs on desktop) collapses into a mobile drawer, site search is present (`md-search`), and the in-page table of contents is available. All are exposed with descriptive ARIA labels (for example, "Header," "Navigation," "Search," "Table of contents," and "Tabs"), so the key features remain reachable on mobile. - Are color contrasts significant enough for color-impaired readers? + + Partially, and this is the area's weakest point. The brand teal used as the primary color (`--md-primary-fg-color: #0db2b6`, set in `docs/stylesheets/extra.css`) provides only about a 2.6:1 contrast ratio with the white header text, which is below the WCAG AA threshold of 4.5:1 for normal text and even below the 3:1 threshold for large text. Body links are darkened with `filter: brightness(80%)`, which improves them to roughly 3.96:1 but still falls short of the 4.5:1 AA requirement for normal text. Contrast therefore needs improvement for color-impaired readers. + - Are most website features usable using a keyboard only? + + Yes. The page includes a "Skip to content" link (`md-skip`), and the Material theme provides full keyboard navigation and search keyboard shortcuts, so the main features can be operated without a mouse. + - Does text-to-speech offer listeners a good experience? -It is up to each project to set their own guidelines. + Largely yes. The document declares its language (``), uses semantic landmarks and ARIA labels, provides a skip link, and every image in the documentation carries non-empty alt text (25 markdown images, none with empty alt, and no raw `` tags lacking `alt`). These give screen readers and text-to-speech tools a solid foundation, though the ongoing quality of alt text and heading order depends on authors. + +##### Comment + +The KubeVirt user guide is highly usable and, for the most part, accessible, thanks to its Material for MkDocs foundation. The site is responsive and works well on mobile: it sets a proper viewport, collapses the top navigation into a mobile drawer, and keeps site search and the in-page table of contents reachable on small screens. Pages are readable, with clean typography, clear heading structure, and syntax-highlighted code, so readers can move through technical content comfortably on any device. + +Accessibility support is strong at the structural level. The document declares its language, exposes semantic landmarks and descriptive ARIA labels (Header, Navigation, Search, Table of contents, Tabs), and provides a "Skip to content" link, all of which help keyboard and screen-reader users. Keyboard-only operation is well supported through the theme's navigation and search shortcuts. Text-to-speech users are also well served: every image in the documentation carries non-empty alt text, and there are no raw image tags missing an `alt` attribute. + +The clear weak point is color contrast. The brand teal used as the primary color (`#0db2b6` in `docs/stylesheets/extra.css`) yields only about 2.6:1 against the white header text, which fails the WCAG AA requirement of 4.5:1 for normal text and even the 3:1 threshold for large text. Body links, darkened with `filter: brightness(80%)`, reach roughly 3.96:1 but still fall short of 4.5:1. This affects color-impaired and low-vision readers most, and it is the single most impactful fix in this area. -[accessibility]: https://developer.mozilla.org/en-US/docs/Web/Accessibility +Addressing contrast would be straightforward and high value: darken the primary teal (or the text placed on it) until header text and links meet WCAG AA, and verify the result in both the light and dark schemes. To sustain accessibility over time, maintainers could add an automated contrast and accessibility check to the build and keep encouraging descriptive alt text and correct heading order in new pages. + +Rating: 4 - Meets or exceeds standards #### Branding and design @@ -999,10 +1009,29 @@ this is branding and marketing. We evaluate on the following: -- Is there an easily recognizable brand for the project (logo + color scheme) - clearly identifiable? +- Is there an easily recognizable brand for the project (logo + color scheme) clearly identifiable? + + Yes. The KubeVirt logo, a teal heptagon enclosing a stylized "V," is displayed in the site header and configured through `theme.logo: assets/KubeVirt_icon.png`, with matching favicons (`assets/favicon.ico` and `assets/favicon32x32.png`) in `mkdocs.yml`. The color scheme reinforces the logo: the Material theme uses a teal palette, and `docs/stylesheets/extra.css` pins the exact brand colors (`--md-primary-fg-color: #0db2b6` and `--md-accent-fg-color: #006166`). Together the logo and teal palette make the project brand clearly identifiable on every page. + - Is the brand used across the website consistently? -- Is the website’s typography clean and well-suited for reading? + + Within the user guide, yes. The teal palette is applied globally through the Material theme and `extra.css`, so the primary and accent colors are consistent across all pages and are defined for both the light (`default`) and dark (`slate`) schemes. The logo appears in the header site-wide, and section labels in the navigation are given a coordinated teal tone (`#00797f`). One caveat is that the user guide is a MkDocs Material site, while the main `kubevirt.io` website is a separate property with its own styling, so the two share the logo and general color family but do not share an identical look and feel. + +- Is the website's typography clean and well-suited for reading? + + Yes. The guide does not override the theme fonts, so it inherits the Material theme's default typeface (Roboto for body text and Roboto Mono for code), which is a clean, legible sans-serif well-suited to on-screen reading. Headings, body copy, tables, and code blocks are styled consistently by the theme, code uses monospaced type with syntax highlighting, and tables are set to full width (`min-width: 100%`) for readability. The custom `filter: brightness(80%)` applied to links slightly darkens link text, which is a minor contrast consideration but does not materially harm readability. + +##### Comment + +The KubeVirt user guide presents a clear and recognizable brand. The project's teal heptagon logo appears in the site header, and the Material theme is configured with a teal palette that is anchored to the exact brand colors in `docs/stylesheets/extra.css` (`#0db2b6` primary and `#006166` accent). Because these colors are defined at the theme level, the brand identity carries across every page rather than depending on individual authors, which is the right approach for a documentation site. + +Brand usage is consistent within the guide. The palette is defined for both the light and dark color schemes, the logo and favicons are set globally, and navigation section labels use a coordinated teal tone. The main point of friction is cross-property consistency: the user guide is a MkDocs Material site, while the primary `kubevirt.io` website is a separate property with its own styling. The two share the logo and color family but not an identical look and feel, so a reader moving between them will notice the shift. Documenting a small set of shared brand values (hex colors, logo files, and font choices) would help keep the properties aligned over time. + +Typography is clean and well-suited for reading. By not overriding the theme fonts, the guide inherits Material's default Roboto and Roboto Mono, which are legible on screen and applied consistently to headings, body text, tables, and syntax-highlighted code. One minor design choice worth revisiting is the `filter: brightness(80%)` rule applied to links, which darkens link text and could reduce contrast in some contexts; verifying it against accessibility contrast targets would remove any doubt. + +Overall, the branding and design are in good shape: the brand is identifiable, applied consistently within the guide, and paired with readable typography. The main opportunities are cross-site brand alignment and a quick contrast check of the customized link styling. + +Rating: 4 - Meets or exceeds standards #### Case studies/social proof @@ -1011,13 +1040,36 @@ organizations using it. We evaluate on the following: -- Are there case studies available for the project and are they documented on - the website? +fic organizations adopted and benefited from KubeVirt. The user guide itself contains only technical documentation and does not link to any case studies. + - Are there user testimonials available? + + Not evident. The website lists adopting organizations by logo, but there are no quoted testimonials from users describing their experience or outcomes. The user guide does not include or reference testimonials. + - Is there an active project blog? + + Yes. The `kubevirt.io` site maintains an active blog with regular posts; recent entries are dated 2026 (for example, "Beta Features Enabled by Default in KubeVirt v1.9" and "Announcing the release of KubeVirt v1.8"), covering releases, features, and technical topics. The blog lives on the main site; the user guide links to release notes but does not link directly to the blog. + - Are there community talks for the project and are they present on the website? + + Yes. The `kubevirt.io/videos/` page organizes community talks into curated YouTube playlists, including Talks, Demos, Interviews, and the annual KubeVirt Summit, alongside recorded community meetings. This content is well organized on the main site, but the user guide does not surface or link to it. + - Is there a logo wall of users/participating organizations? + Yes. The website homepage features a prominent logo wall grouped into End Users (such as Arm, Aussie Broadband, Cloudflare, CoreWeave, and NVIDIA), Vendors (such as Deckhouse, Microsoft, Oracle, Red Hat, and SUSE), and Integrations. The user guide does not display or link to this logo wall. + +##### Comment + +KubeVirt has a strong base of community and adoption content, though it lives on the main `kubevirt.io` website rather than in the user guide. The website maintains an active blog with recent posts dated 2026, organizes community talks into curated YouTube playlists (Talks, Demos, Interviews, and the annual KubeVirt Summit), and presents an extensive logo wall of adopting organizations grouped into End Users, Vendors, and Integrations. These are clear signals of a healthy, active project and provide good social proof for prospective users. + +The main gaps are dedicated case studies and user testimonials. The adopter logo walls show who uses KubeVirt but do not explain how or why, and there are no quoted testimonials describing real-world outcomes. Narrative case studies, even a small number, would help prospective adopters understand practical use cases, migration paths, and the benefits organizations have realized. These carry particular weight for an infrastructure project where adoption decisions are significant. + +From the user guide's perspective, the more immediate issue is discoverability. The guide is technical documentation and does not link to the blog, community talks, or adopter logo wall at all. A reader who lands in the user guide has no easy path to this adoption and community content, even though it exists one site over. Adding a few targeted links, for example from the landing page or a "Community" or "Adopters" entry, would connect readers to material that builds confidence in the project. + +Overall, the project scores well on blog, talks, and a logo wall, but lacks true case studies and testimonials, and the user guide does not surface the adoption content that already exists. Closing those gaps would round out this area. + +Rating: 3 - Meets standards + #### SEO, Analytics and site-local search SEO helps users find your project and it's documentation, and analytics helps @@ -1026,17 +1078,45 @@ while optional, can offer your readers a site-focused search results. We evaluate on the following: -- Analytics: - - Is analytics enabled for the production server? - - Is analytics disabled for all other deploys? - - If your project used Google Analytics, have you migrated to GA4? - - Can Page-not-found (404) reports easily be generated from you site - analytics? Provide a sample of the site's current top-10 404s. -- Is site indexing supported for the production server, while disabled for - website previews and builds for non-default branches? +- Is analytics enabled for the production server? + + No. The user guide's `mkdocs.yml` has no `extra.analytics` configuration, and the live production pages contain no analytics tags (no Google Analytics, Google Tag Manager, or measurement ID). The main `kubevirt.io` homepage likewise shows no analytics tags. This appears consistent with the project's privacy stance, but it means no usage analytics are collected. + +- Is analytics disabled for all other deploys? + + Not applicable in practice. Because no analytics is configured anywhere, it is inherently absent from pull-request previews and non-default branch builds as well. The intended "production-only analytics" pattern cannot be assessed since there is no analytics to scope. + +- If project is using Google Analytics, has it migrated to GA4? + + Not applicable. The project does not use Google Analytics on the user guide, so there is no Universal Analytics or GA4 property in use to migrate. + +- Can Page-not-found (404) reports easily be generated from site analytics? + + No. Material for MkDocs generates a `404.html` page, but without any analytics in place there is no mechanism to report on 404 hits or generate not-found reports from site analytics. + +- Is site indexing supported for the production server, while disabled for website previews and builds for non-default branches? + + Partially. Production indexing is supported: a site-wide `robots.txt` is served (returning 200) with a `Sitemap` directive and no `Disallow` rules, MkDocs generates a `sitemap.xml`, and pages carry no `noindex` meta tag. Pull-request previews are built on Netlify, whose deploy-preview and branch-deploy subdomains are served with a `noindex` `X-Robots-Tag` by Netlify's default behavior; however, this preview-noindex behavior is not explicitly configured in `netlify.toml`, so it relies on the platform default rather than an intentional project setting. One minor SEO defect is that the `robots.txt` Sitemap URL contains a double slash (`https://kubevirt.io//sitemap.xml`). + - Is local intra-site search available from the website? -- Are the current custodian(s) of the following accounts clearly documented: - analytics, Google Search Console, site-search (such as Google CSE or Algolia) + + Yes. The MkDocs `search` plugin is enabled in `mkdocs.yml` (with a customized separator), and the Material theme provides the search box and results UI, giving readers client-side, intra-site search across the user guide. + +- Are the current custodian(s) of the analytics accounts (such as Google CSE) documented? + + No. No analytics or search-account custodians are documented in the repository. Since no analytics account currently exists there is nothing to attribute, but there is also no documented owner should analytics be introduced. + +##### Comment + +The KubeVirt user guide handles site search and basic SEO well but has no analytics at all. Local intra-site search is enabled through the MkDocs `search` plugin and surfaced by the Material theme, giving readers fast client-side search across the documentation. For discoverability, the production site is indexable: a site-wide `robots.txt` is served with a `Sitemap` directive and no blocking rules, MkDocs generates a `sitemap.xml`, and pages carry no `noindex` tag. Pull-request previews are built on Netlify, whose preview subdomains are `noindex` by default, which keeps previews out of search results. + +The clear gap is analytics. Neither the user guide nor the main site includes any analytics tags, so there is no visibility into traffic, popular pages, search terms, or broken links. In particular, 404 reports cannot be generated from analytics, which makes it harder to find and fix broken inbound links over time. This absence appears consistent with the project's privacy posture, and that is a legitimate trade-off; but if the project wants data to guide documentation improvements, a privacy-respecting analytics option would fill an important blind spot. + +If analytics is introduced, a few practices are worth adopting up front. Use a GA4 property (or a privacy-friendly alternative), enable it only on the production deploy while leaving previews and non-default branches untracked, and document the account custodians so ownership is clear as maintainers change. Configuring these through the theme rather than per page keeps the setup consistent. + +Two smaller items round out the SEO picture: make the preview `noindex` behavior an explicit project setting rather than relying on the Netlify default, and fix the double slash in the `robots.txt` Sitemap URL (`https://kubevirt.io//sitemap.xml`). + +Rating: 2 - Needs improvement #### Maintenance planning @@ -1045,17 +1125,42 @@ project maintainers aren’t web developers. We evaluate on the following: -- Is your website tooling well supported by the community (i.e., Hugo with the - Docsy theme) or commonly used by CNCF projects (our recommended tech stack?) -- Are you actively cultivating website maintainers from within the community? +- Is the website tooling well supported by the community (i.e., Hugo with the Docsy theme) or commonly used by CNCF projects? + + Yes. The user guide is built with MkDocs and the Material for MkDocs theme, along with the `awesome-nav`, `redirects`, and `html-proofer` plugins (see `mkdocs.yml`, `Makefile`, and `netlify.toml`). While this is not the Hugo and Docsy stack named in the question, MkDocs Material is a mature, actively maintained, and widely adopted documentation tool used across many CNCF and Kubernetes-ecosystem projects, so the tooling is well supported. Note that the main `kubevirt.io` website is a separate Jekyll site, so the project maintains two different stacks. + +- Is there active cultivating website maintainers from within the community? + + Yes. The repository has an `OWNERS` file that defines reviewers and approvers roles (via aliases) and lists emeritus approvers, and the project uses the Kubernetes-style OWNERS model for delegating maintenance. Git history shows sustained activity, with roughly 49 distinct authors contributing in the last 12 months and a steady stream of merged pull requests, indicating an active and growing maintainer and contributor base. + - Are site build times reasonable? + + Yes. MkDocs produces a static site of this size quickly, typically well under a minute, and the build is a straightforward `mkdocs build`. Netlify builds preview deployments for pull requests and the project's Prow-based CI builds the site as well, so build times are reasonable for both previews and production. + - Do site maintainers have adequate permissions? -#### Other + Yes. Permissions are managed through the Kubernetes-style OWNERS model, where designated approvers can approve and merge changes and reviewers can review. The `OWNERS` file separates reviewers and approvers and records emeritus approvers, giving maintainers the access they need while keeping the roles documented. + +- Is the website accessible via HTTPS? + + Yes. Requesting `https://kubevirt.io/user-guide/` returns HTTP 200 over HTTPS. -- Is your website accessible via HTTPS? - Does HTTP access, if any, redirect to HTTPS? + Yes. Requesting `http://kubevirt.io/user-guide/` returns a 301 redirect to the HTTPS URL, and the apex `http://kubevirt.io/` likewise 301-redirects to HTTPS. + +##### Comment + +The KubeVirt user guide is on a solid maintenance footing. It is built with MkDocs and the Material for MkDocs theme, supplemented by the `awesome-nav`, `redirects`, and `html-proofer` plugins. Although this differs from the Hugo and Docsy stack, MkDocs Material is a mature and widely adopted documentation toolchain used across the CNCF and Kubernetes ecosystems, so maintainers can rely on strong community support and a steady stream of upstream updates. + +Maintenance responsibility is clearly structured and actively exercised. The repository uses the Kubernetes-style OWNERS model, defining reviewers and approvers roles and recording emeritus approvers, which gives maintainers appropriate permissions to review and merge changes. The commit history reflects a healthy, cultivated community, with roughly 49 distinct authors in the last twelve months and a continuous flow of merged pull requests, so the guide is not dependent on a single maintainer. + +The build and hosting setup is dependable. MkDocs builds this static site quickly, Netlify produces per-pull-request previews, and the project's Prow-based CI builds the site as well. The site is served securely: HTTPS returns a 200 response, and HTTP requests are 301-redirected to HTTPS for both the user guide path and the apex domain. These are exactly the properties one wants for low-friction, secure maintenance. + +The main opportunities are around build reproducibility and stack consolidation. The build installs MkDocs and its plugins without pinned versions (in `netlify.toml` and the `Makefile`), which risks non-reproducible builds or breakage when an upstream package changes; pinning versions would harden this. Maintaining two separate stacks (MkDocs for the user guide and Jekyll for the main site) also adds ongoing overhead worth periodically reviewing. + +Rating: 4 - Meets or exceeds standards + ### Recommendations > AUTHOR NOTE: Write general recommendations based on the comments from the @@ -1067,14 +1172,50 @@ We evaluate on the following: #### Usability, accessibility and devices +- Increase color contrast for the brand teal primary color (`#0db2b6` in `docs/stylesheets/extra.css`) so that white header text meets the WCAG AA contrast ratio of at least 4.5:1 for normal text, either by darkening the teal or by adjusting the text color placed on it. +- Adjust the body link color (currently the primary color darkened with `filter: brightness(80%)`) so that links reach at least 4.5:1 contrast against the page background, rather than the roughly 3.96:1 they achieve today. +- Verify all contrast changes in both the light (`default`) and dark (`slate`) schemes, checking header text, links, navigation section labels, and code blocks. +- Add a-ln automated accessibility and contrast check to the site build (for example, a Lighthouse or axe-based check) so contrast regressions are caught before publishing. +- Continue requiring descriptive, non-empty alt text on all images and maintain correct heading order in new pages, so screen-reader and text-to-speech users keep getting a good experience. +- Preserve the existing strengths, keeping the responsive viewport, mobile drawer navigation, site search, in-page table of contents, skip-to-content link, and ARIA labels intact as the theme is upgraded. + #### Branding and design +- Document a small set of shared brand values in the repository, such as the brand hex colors (`#0db2b6` and `#006166`), the logo and favicon files, and the chosen fonts, so the branding is defined in one place rather than implied by the theme configuration. +- Align the user guide's look and feel more closely with the main `kubevirt.io` website by agreeing on a shared logo, color family, and typography across both properties, so readers experience a consistent brand as they move between the sites. +- Verify the customized link styling (`filter: brightness(80%)` in `docs/stylesheets/extra.css`) against accessibility contrast targets in both the light and dark schemes, and adjust or remove the filter if it reduces contrast below recommended levels. +- Keep relying on the Material theme's default Roboto and Roboto Mono typography, and if a custom font is ever introduced, apply it through the theme configuration so it remains consistent across all pages. +- Confirm the teal palette renders correctly in the dark (`slate`) scheme, checking that logo, links, code blocks, and navigation labels retain sufficient contrast and remain on-brand. +- Continue defining brand colors through theme-level variables in `extra.css` rather than per-page styling, so the brand stays consistent as new pages are added. + #### Case studies/social proof +- Publish a small set of narrative case studies on the project website that describe how specific organizations adopted KubeVirt, the problems they solved, and the outcomes they achieved, going beyond the existing adopter logo walls. +- Gather and display user testimonials, for example short quotes from adopting organizations, to complement the logo walls with real-world perspectives on the project's value. +- Link the user guide to the project's adoption and community content so readers can discover it, for example by adding references to the blog, the community talks and videos page, and the adopters logo wall from the user guide landing page. +- Add a "Community" or "Adopters" entry to the user guide that points to the case studies, testimonials, and logo wall once they exist, giving documentation readers a clear path to social proof. +- Continue maintaining the active blog and the curated talk playlists (Talks, Demos, Interviews, and KubeVirt Summit), and consider surfacing the most relevant posts or talks from within related documentation pages. +- Where a case study or talk illustrates a documented feature, cross-link it from the corresponding user guide page so readers can see the feature applied in practice. + #### SEO, Analytics and site-local search +- Decide whether to adopt analytics for the documentation, and if so, choose either a GA4 property or a privacy-respecting alternative that aligns with the project's privacy policy, so maintainers gain visibility into traffic and popular content. +- If analytics is adopted, enable it only on the production deploy and keep it disabled for pull-request previews and non-default branch builds, configuring it through the Material theme's analytics integration rather than per page. +- If analytics is adopted, ensure Page-not-found (404) reporting is available so broken inbound links can be identified and fixed over time. +- Document the custodians of any analytics or search accounts (for example, who owns the analytics property) in the repository, so ownership remains clear as maintainers change. +- Make the preview `noindex` behavior an explicit project setting (for example, an `X-Robots-Tag` header for Netlify preview and branch deploys) rather than relying solely on the Netlify default, so indexing rules are intentional and documented. +- Fix the double slash in the `robots.txt` Sitemap URL (`https://kubevirt.io//sitemap.xml`) so it points to a single canonical sitemap location. +- Keep the MkDocs `search` plugin enabled and continue to benefit from the Material theme's intra-site search, periodically reviewing the search separator configuration as content grows. + #### Maintenance planning +- Pin the versions of MkDocs and its plugins (`mkdocs`, `mkdocs-material`, `mkdocs-awesome-nav`, `mkdocs-redirects`, and `mkdocs-html-proofer-plugin`) in the build definitions, for example via a `requirements.txt`, so that Netlify and Prow builds are reproducible and resistant to breaking upstream changes. +- Keep the pinned dependency versions current through a regular update cadence, ideally automated (for example with Dependabot or Renovate), so the guide continues to benefit from the actively maintained MkDocs Material toolchain. +- Continue cultivating maintainers through the OWNERS model, and periodically review the reviewers and approvers lists to confirm they reflect currently active contributors and that coverage is not concentrated in too few people. +- Preserve the existing HTTPS posture, keeping the site accessible over HTTPS and retaining the HTTP-to-HTTPS redirects for both the user guide path and the apex domain. +- Periodically review the overhead of maintaining two separate stacks (MkDocs for the user guide and Jekyll for the main `kubevirt.io` site), and consider whether consolidation or closer alignment would reduce long-term maintenance effort. +- Document the local and CI build process (build commands, dependencies, and preview workflow) in a contributor-facing location so new maintainers can reproduce and troubleshoot builds easily. + #### Other #### References and notes From 5ab5bae5e42e94c00ebcff24065f84a6737bfc78 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Mon, 27 Jul 2026 21:11:24 -0700 Subject: [PATCH 29/49] format fixes Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/analysis.md | 1160 ++++++++++++++++++++++------ 1 file changed, 943 insertions(+), 217 deletions(-) diff --git a/analyses/2026/kubevirt/analysis.md b/analyses/2026/kubevirt/analysis.md index b9d3d542..0b2fdc1b 100644 --- a/analyses/2026/kubevirt/analysis.md +++ b/analyses/2026/kubevirt/analysis.md @@ -242,64 +242,155 @@ documentation. We evaluate on the following: - Is there high level conceptual/"About" content? Is the documentation feature complete? (i.e., each product feature is documented) - Yes. The guide provides high-level conceptual content. The [Architecture](docs/architecture.md) page gives a technical and conceptual overview of the KubeVirt components, the service-oriented design, and the layered virtualization stack, and the Welcome page introduces each major section of the guide. - - The documentation is broadly feature complete. Major product areas each have dedicated sections: cluster administration, user workloads, compute, network, and storage. Individual features such as live migration, CPU and memory hotplug, hugepages, NUMA, instance types and preferences, snapshots, volume export, and network binding plugins each have their own pages. Coverage is wide enough that most shipped features have at least a conceptual description. + Yes. The guide provides high-level conceptual content. The + [Architecture](https://kubevirt.io/user-guide/architecture/) page gives a + technical and conceptual overview of the KubeVirt components, the + service-oriented design, and the layered virtualization stack, and the Welcome + page introduces each major section of the guide. + + The documentation is broadly feature complete. Major product areas each have + dedicated sections: cluster administration, user workloads, compute, network, + and storage. Individual features such as live migration, CPU and memory + hotplug, hugepages, NUMA, instance types and preferences, snapshots, volume + export, and network binding plugins each have their own pages. Coverage is + wide enough that most shipped features have at least a conceptual description. - Are there step-by-step instructions (tasks, tutorials) documented for features? - Yes. Most feature pages include step-by-step instructions with copy-paste capable shell and YAML examples. For example, the [live migration](docs/compute/live_migration.md) page walks through enabling the feature, initiating and canceling a migration, and configuring a dedicated migration network, and the [creating VirtualMachines](docs/user_workloads/creating_vms.md) page shows how to build manifests with `virtctl`. + Yes. Most feature pages include step-by-step instructions with copy-paste + capable shell and YAML examples. For example, the + [live migration](https://kubevirt.io/user-guide/compute/live_migration/) page + walks through enabling the feature, initiating and canceling a migration, and + configuring a dedicated migration network, and the + [creating VirtualMachines](https://kubevirt.io/user-guide/user_workloads/creating_vms/) + page shows how to build manifests with `virtctl`. - For tutorials, the guide links out to external interactive labs and quickstarts (Killercoda, minikube, kind, and cloud providers) from both the Welcome and Quickstarts pages rather than hosting long-form tutorials inline. This keeps hands-on learning paths available, though they live outside the user guide itself. + For tutorials, the guide links out to external interactive labs and + quickstarts (Killercoda, minikube, kind, and cloud providers) from both the + Welcome and Quickstarts pages rather than hosting long-form tutorials inline. + This keeps hands-on learning paths available, though they live outside the + user guide itself. - Are there any key features which are documented but missing task documentation? - Some pages lean conceptual or reference-oriented and would benefit from added task steps, but there are no major features that are described without any actionable guidance. A few areas mix concept and procedure heavily (for example, migration strategies and some networking topics), where a reader must extract the steps from surrounding explanation. + Some pages lean conceptual or reference-oriented and would benefit from added + task steps, but there are no major features that are described without any + actionable guidance. A few areas mix concept and procedure heavily (for + example, migration strategies and some networking topics), where a reader must + extract the steps from surrounding explanation. - The most common gap is depth rather than absence: certain advanced features document the "what" and configuration fields well but provide fewer end-to-end, goal-oriented walkthroughs. Reviewers should confirm that newer features listed in recent release notes each have a corresponding task page. + The most common gap is depth rather than absence: certain advanced features + document the "what" and configuration fields well but provide fewer + end-to-end, goal-oriented walkthroughs. Reviewers should confirm that newer + features listed in recent release notes each have a corresponding task page. - Is the "happy path"/most common use case documented? Does task and tutorial content demonstrate atomicity and isolation of concerns? (Are tasks clearly named according to user goals?) - Yes. The happy path is documented. A new user can follow installation, then create and access a virtual machine, which covers the most common use case. The quickstarts and labs reinforce this path for first-time users. + Yes. The happy path is documented. A new user can follow installation, then + create and access a virtual machine, which covers the most common use case. + The quickstarts and labs reinforce this path for first-time users. - Task content generally demonstrates atomicity and isolation of concerns, and headings are largely named according to user goals using verb or gerund phrases, such as "Creating VirtualMachines on a cluster", "Enabling the live-migration support", "Initiate live migration", and "Configuring a migration network on a cluster". This makes individual tasks easy to scan and follow. A minority of headings are noun-based topic labels rather than goal phrases, so naming is strong but not fully consistent. + Task content generally demonstrates atomicity and isolation of concerns, and + headings are largely named according to user goals using verb or gerund + phrases, such as "Creating VirtualMachines on a cluster", "Enabling the + live-migration support", "Initiate live migration", and "Configuring a + migration network on a cluster". This makes individual tasks easy to scan and + follow. A minority of headings are noun-based topic labels rather than goal + phrases, so naming is strong but not fully consistent. - If the documentation does not suffice, is there a clear escalation path for users needing more help? (FAQ, Troubleshooting) - Yes. The Welcome page provides a "Getting help" section that links to filing bugs on GitHub, the kubevirt-dev mailing list, and the community Slack channel, giving users a clear escalation path. + Yes. The Welcome page provides a "Getting help" section that links to filing + bugs on GitHub, the kubevirt-dev mailing list, and the community Slack + channel, giving users a clear escalation path. - There is also a dedicated Virtualization Debugging section covering log verbosity, privileged node debugging, virsh commands, and running QEMU under strace or gdb, and several feature pages include debugging notes. However, there is no single, consolidated FAQ or troubleshooting landing page, so common problems and their fixes are spread across individual pages rather than centralized. + There is also a dedicated Virtualization Debugging section covering log + verbosity, privileged node debugging, virsh commands, and running QEMU under + strace or gdb, and several feature pages include debugging notes. However, + there is no single, consolidated FAQ or troubleshooting landing page, so + common problems and their fixes are spread across individual pages rather than + centralized. - If the product exposes an API, is there a complete reference? - Yes. KubeVirt exposes a Kubernetes-style API, and the Welcome page links to the generated API reference at kubevirt.io/api-reference, which provides a complete, versioned reference for the custom resources and fields. + Yes. KubeVirt exposes a Kubernetes-style API, and the Welcome page links to + the generated API reference at kubevirt.io/api-reference, which provides a + complete, versioned reference for the custom resources and fields. - Because the reference is generated from source and hosted separately from the user guide, it stays current with releases but is one click removed from the task content. Cross-linking specific fields from task pages to the reference would tighten the connection between instructions and reference material. + Because the reference is generated from source and hosted separately from the + user guide, it stays current with releases but is one click removed from the + task content. Cross-linking specific fields from task pages to the reference + would tighten the connection between instructions and reference material. - Is content up to date and accurate? - Yes. The content is current. The release notes document releases through v1.8.0 (released March 2026, built for Kubernetes v1.35), and feature pages reference current resources, feature gates, and `virtctl` subcommands consistent with recent releases. + Yes. The content is current. The release notes document releases through + v1.8.0 (released March 2026, built for Kubernetes v1.35), and feature pages + reference current resources, feature gates, and `virtctl` subcommands + consistent with recent releases. - Accuracy appears high overall, with concrete command output and manifests shown inline. As with any fast-moving project, reviewers should periodically verify that examples and feature-gate names match the latest release, since some pages describe features that graduate through alpha, beta, and GA over time. + Accuracy appears high overall, with concrete command output and manifests + shown inline. As with any fast-moving project, reviewers should periodically + verify that examples and feature-gate names match the latest release, since + some pages describe features that graduate through alpha, beta, and GA over + time. - Restructure needed? - False. A restructure of the content is not needed. The information architecture is sound: content is organized into clear conceptual, task, and reference layers, navigation order is deliberately controlled per section, and features are grouped logically by domain (cluster administration, user workloads, compute, network, storage). Improvements should focus on incremental additions — a consolidated troubleshooting/FAQ entry point, tighter cross-linking to the API reference, and more consistent goal-oriented headings — rather than reorganizing the existing structure. + False. A restructure of the content is not needed. The information + architecture is sound: content is organized into clear conceptual, task, and + reference layers, navigation order is deliberately controlled per section, and + features are grouped logically by domain (cluster administration, user + workloads, compute, network, storage). Improvements should focus on + incremental additions — a consolidated troubleshooting/FAQ entry point, + tighter cross-linking to the API reference, and more consistent goal-oriented + headings — rather than reorganizing the existing structure. ##### Comment -The KubeVirt user guide has a solid information architecture. Content is organized into clear domains — cluster administration, user workloads, compute, network, and storage — and each section uses an explicit navigation order rather than alphabetical sorting, so related tasks sit together in a logical reading sequence. The guide also layers the three information types well: conceptual material (the Architecture page and per-section overviews), task material (step-by-step pages with copy-paste capable shell and YAML examples), and reference material (release notes and the generated API reference). Most task headings are named after user goals using verb or gerund phrases, such as "Creating VirtualMachines on a cluster" and "Enabling the live-migration support," which makes pages easy to scan. - -The most valuable improvement would be a single, consolidated troubleshooting and FAQ entry point. Today, help is available through the "Getting help" links and a capable Virtualization Debugging section, but common problems and their fixes are scattered across individual feature pages. A dedicated troubleshooting landing page — organized by symptom and linking out to the relevant debugging topics — would give users a predictable escalation path when a task page alone does not resolve their issue. The Prometheus documentation (https://prometheus.io/docs) is a good model here: it keeps concepts, tasks, and reference clearly separated while still offering obvious paths to deeper help. - -Two smaller refinements would tighten the architecture further. First, tutorials currently live outside the guide as external labs and quickstarts; surfacing an explicit, in-guide learning path (or at least a clearly labeled "Tutorials" grouping that frames those external resources) would help new users find hands-on content without leaving the site. Second, the API reference is complete but hosted separately and only reachable from the Welcome page — cross-linking specific custom resources and fields from the task pages that use them would connect instructions to reference material more directly. Normalizing the minority of noun-based headings into goal-oriented verb phrases would also improve scanning and consistency. - -Restructure needed: False. The existing structure is sound and does not require reorganization. The recommended changes are incremental additions — a troubleshooting/FAQ hub, clearer tutorial signposting, tighter cross-linking to the API reference, and more consistent heading phrasing — that build on the current architecture rather than replace it. +The KubeVirt user guide has a solid information architecture. Content is +organized into clear domains — cluster administration, user workloads, compute, +network, and storage — and each section uses an explicit navigation order rather +than alphabetical sorting, so related tasks sit together in a logical reading +sequence. The guide also layers the three information types well: conceptual +material (the Architecture page and per-section overviews), task material +(step-by-step pages with copy-paste capable shell and YAML examples), and +reference material (release notes and the generated API reference). Most task +headings are named after user goals using verb or gerund phrases, such as +"Creating VirtualMachines on a cluster" and "Enabling the live-migration +support," which makes pages easy to scan. + +The most valuable improvement would be a single, consolidated troubleshooting +and FAQ entry point. Today, help is available through the "Getting help" links +and a capable Virtualization Debugging section, but common problems and their +fixes are scattered across individual feature pages. A dedicated troubleshooting +landing page — organized by symptom and linking out to the relevant debugging +topics — would give users a predictable escalation path when a task page alone +does not resolve their issue. The Prometheus documentation +(https://prometheus.io/docs) is a good model here: it keeps concepts, tasks, and +reference clearly separated while still offering obvious paths to deeper help. + +Two smaller refinements would tighten the architecture further. First, tutorials +currently live outside the guide as external labs and quickstarts; surfacing an +explicit, in-guide learning path (or at least a clearly labeled "Tutorials" +grouping that frames those external resources) would help new users find +hands-on content without leaving the site. Second, the API reference is complete +but hosted separately and only reachable from the Welcome page — cross-linking +specific custom resources and fields from the task pages that use them would +connect instructions to reference material more directly. Normalizing the +minority of noun-based headings into goal-oriented verb phrases would also +improve scanning and consistency. + +Restructure needed: False. The existing structure is sound and does not require +reorganization. The recommended changes are incremental additions — a +troubleshooting/FAQ hub, clearer tutorial signposting, tighter cross-linking to +the API reference, and more consistent heading phrasing — that build on the +current architecture rather than replace it. Rating: 4 - Meets or exceeds standards @@ -308,37 +399,93 @@ Rating: 4 - Meets or exceeds standards New users are the most avid users of documentation, and need content specifically for them. We evaluate on the following: -- Is "getting started" clearly labeled? ("Getting started", "Installation", "First steps", etc.) +- Is "getting started" clearly labeled? ("Getting started", "Installation", + "First steps", etc.) - Partially. There is no page or navigation entry titled "Getting Started" or "First steps." New-user entry points are instead spread across a top-level "Quickstarts" item, an "Installation" page (the first page under Cluster Administration), and a "Try it out" section on the homepage. "Installation" is clearly labeled, but the absence of a single, consistently named getting-started landing page makes the on-ramp harder to find than a conventional "Getting Started" label would. + Partially. There is no page or navigation entry titled "Getting Started" or + "First steps." New-user entry points are instead spread across a top-level + "Quickstarts" item, an "Installation" page (the first page under Cluster + Administration), and a "Try it out" section on the homepage. "Installation" is + clearly labeled, but the absence of a single, consistently named + getting-started landing page makes the on-ramp harder to find than a + conventional "Getting Started" label would. - Is installation documented step-by-step? - Yes. `cluster_admin/installation.md` lists prerequisites and then provides copy-pasteable, ordered commands to deploy the KubeVirt operator, create the KubeVirt CR, wait for the components to become available, and verify the running pods. It also covers optional steps such as software emulation fallback and node-placement restrictions. + Yes. `cluster_admin/installation.md` lists prerequisites and then provides + copy-pasteable, ordered commands to deploy the KubeVirt operator, create the + KubeVirt CR, wait for the components to become available, and verify the + running pods. It also covers optional steps such as software emulation + fallback and node-placement restrictions. - If needed, are multiple OSes documented? - Partially. Because KubeVirt is a Kubernetes add-on, the installation guide documents multiple Kubernetes platforms (Kubernetes, OKD, k3OS) and both the x86_64 and Arm64 architectures, rather than host operating systems. Host-OS-specific concerns are limited to AppArmor and SELinux notes. Separately, guest operating systems (for example Windows and Linux) are documented under User Workloads. There is no per-Linux-distribution installation walkthrough, which is reasonable for a cluster add-on but worth noting. + Partially. Because KubeVirt is a Kubernetes add-on, the installation guide + documents multiple Kubernetes platforms (Kubernetes, OKD, k3OS) and both the + x86_64 and Arm64 architectures, rather than host operating systems. + Host-OS-specific concerns are limited to AppArmor and SELinux notes. + Separately, guest operating systems (for example Windows and Linux) are + documented under User Workloads. There is no per-Linux-distribution + installation walkthrough, which is reasonable for a cluster add-on but worth + noting. - Do users know where to go after reading the getting started guide? - Partially. The installation page ends with optional topics (network plugins, node placement) rather than an explicit "Next steps" pointer to creating a first virtual machine. Users must navigate on their own to "User Workloads" (for example `basic_use.md` or `creating_vms.md`). Adding a clear "Next steps" link from installation to the first-VM tasks would close this gap. + Partially. The installation page ends with optional topics (network plugins, + node placement) rather than an explicit "Next steps" pointer to creating a + first virtual machine. Users must navigate on their own to "User Workloads" + (for example `basic_use.md` or `creating_vms.md`). Adding a clear "Next steps" + link from installation to the first-VM tasks would close this gap. -- Is your new user content clearly signposted on your site's homepage or at the top of your information architecture? +- Is your new user content clearly signposted on your site's homepage or at the + top of your information architecture? - Yes. The homepage lists all major sections and includes prominent "Try it out," "KubeVirt Labs," and "Getting help" sections, and "Quickstarts" appears near the top of the navigation. However, much of this new-user content relies on external links (Killercoda, minikube/kind/cloud quickstarts, and the kubevirt.io labs) rather than in-guide getting-started material, so the signposting leads users off-site fairly quickly. + Yes. The homepage lists all major sections and includes prominent "Try it + out," "KubeVirt Labs," and "Getting help" sections, and "Quickstarts" appears + near the top of the navigation. However, much of this new-user content relies + on external links (Killercoda, minikube/kind/cloud quickstarts, and the + kubevirt.io labs) rather than in-guide getting-started material, so the + signposting leads users off-site fairly quickly. - Is there sample code or other example content that can easily be copy-pasted? - Yes. The documentation makes extensive use of fenced and indented code blocks with ready-to-run examples, including installation shell commands, `virtctl create vm` invocations, `kubectl` lifecycle commands, and YAML manifests. These are formatted for direct copy-paste. + Yes. The documentation makes extensive use of fenced and indented code blocks + with ready-to-run examples, including installation shell commands, + `virtctl create vm` invocations, `kubectl` lifecycle commands, and YAML + manifests. These are formatted for direct copy-paste. ##### Comment -The KubeVirt user guide gives new users a solid technical starting point, but its on-ramp is fragmented across several differently named locations. New-user material is split between a top-level "Quickstarts" entry, an "Installation" page buried as the first item under "Cluster Administration," and "Try it out" and "KubeVirt Labs" sections on the homepage. Because none of these is labeled "Getting Started" or "First Steps," newcomers must piece the path together themselves. Consolidating these entry points under a single, clearly named "Getting Started" section—ideally as its own top-level navigation item—would match the convention new users expect and provide one obvious front door. The Falco getting-started guide (https://falco.org/docs/getting-started/) is a good model for this unified structure. - -The installation documentation itself is strong: it lists prerequisites, provides ordered and copy-pasteable operator and CR commands, shows how to verify a healthy deployment, and covers multiple platforms (Kubernetes, OKD, k3OS) and architectures (x86_64 and Arm64). The main weakness is that the guide leans heavily on external links—Killercoda, the minikube/kind/cloud quickstarts, and the kubevirt.io labs—rather than an in-guide walkthrough that carries a reader from a fresh cluster to a running virtual machine. Bringing at least one complete, end-to-end "deploy KubeVirt and launch your first VM" tutorial into the guide would reduce reliance on off-site content and give users a self-contained first success. - -The most actionable single improvement is to close the gap between installation and first use. The installation page currently ends with optional topics (network plugins, node placement) and offers no explicit "Next steps" pointer toward the first-VM tasks in "User Workloads" (such as `basic_use.md` and `creating_vms.md`). Adding a clear "Next steps" call-to-action at the end of installation, linking directly to creating and accessing a first virtual machine, would give new users an unbroken path from setup to a working workload. +The KubeVirt user guide gives new users a solid technical starting point, but +its on-ramp is fragmented across several differently named locations. New-user +material is split between a top-level "Quickstarts" entry, an "Installation" +page buried as the first item under "Cluster Administration," and "Try it out" +and "KubeVirt Labs" sections on the homepage. Because none of these is labeled +"Getting Started" or "First Steps," newcomers must piece the path together +themselves. Consolidating these entry points under a single, clearly named +"Getting Started" section—ideally as its own top-level navigation item—would +match the convention new users expect and provide one obvious front door. The +Falco getting-started guide (https://falco.org/docs/getting-started/) is a good +model for this unified structure. + +The installation documentation itself is strong: it lists prerequisites, +provides ordered and copy-pasteable operator and CR commands, shows how to +verify a healthy deployment, and covers multiple platforms (Kubernetes, OKD, +k3OS) and architectures (x86_64 and Arm64). The main weakness is that the guide +leans heavily on external links—Killercoda, the minikube/kind/cloud quickstarts, +and the kubevirt.io labs—rather than an in-guide walkthrough that carries a +reader from a fresh cluster to a running virtual machine. Bringing at least one +complete, end-to-end "deploy KubeVirt and launch your first VM" tutorial into +the guide would reduce reliance on off-site content and give users a +self-contained first success. + +The most actionable single improvement is to close the gap between installation +and first use. The installation page currently ends with optional topics +(network plugins, node placement) and offers no explicit "Next steps" pointer +toward the first-VM tasks in "User Workloads" (such as `basic_use.md` and +`creating_vms.md`). Adding a clear "Next steps" call-to-action at the end of +installation, linking directly to creating and accessing a first virtual +machine, would give new users an unbroken path from setup to a working workload. Rating: 3 - Meets standards @@ -604,14 +751,38 @@ needs I see as a novice user: The following recommendations for improving the information architecture of the KubVirt User Guide: -- Add a single, consolidated troubleshooting and FAQ entry point, organized by symptom, that links out to the relevant pages in the Virtualization Debugging section and to the scattered debugging notes on individual feature pages. This gives users a predictable escalation path when a task page alone does not resolve their issue. -- Preserve the current overall structure rather than reorganizing it. The domain-based sections (cluster administration, user workloads, compute, network, storage) and explicit per-section navigation order are sound; focus effort on incremental additions instead of a restructure. -- Surface an explicit, in-guide learning path for new users. Add a clearly labeled "Tutorials" grouping that frames the existing external labs and quickstarts (Killercoda, minikube, kind, cloud providers) so hands-on content is discoverable without leaving the guide. -- Cross-link the API reference from the task pages that use each resource. Link specific custom resources and fields (for example, from live migration, instance types, and storage pages) to their entries at kubevirt.io/api-reference so instructions connect directly to reference material. -- Normalize the minority of noun-based topic headings into goal-oriented verb or gerund phrases, matching the existing style of headings such as "Creating VirtualMachines on a cluster" and "Enabling the live-migration support." This improves scanning and consistency across pages. -- Audit task coverage depth against recent release notes. Confirm that each newer feature (for example, those introduced through v1.8.0) has a corresponding end-to-end, goal-oriented task page, not just a conceptual or configuration-field description. -- Separate concept from procedure on pages that currently interleave them, such as the migration strategies and some networking topics, so readers can extract the steps without reading through surrounding explanation. -- Periodically verify that inline examples, command output, and feature-gate names match the latest release, since features graduate through alpha, beta, and GA over time and can drift from the documented behavior. +- Add a single, consolidated troubleshooting and FAQ entry point, organized by + symptom, that links out to the relevant pages in the Virtualization Debugging + section and to the scattered debugging notes on individual feature pages. This + gives users a predictable escalation path when a task page alone does not + resolve their issue. +- Preserve the current overall structure rather than reorganizing it. The + domain-based sections (cluster administration, user workloads, compute, + network, storage) and explicit per-section navigation order are sound; focus + effort on incremental additions instead of a restructure. +- Surface an explicit, in-guide learning path for new users. Add a clearly + labeled "Tutorials" grouping that frames the existing external labs and + quickstarts (Killercoda, minikube, kind, cloud providers) so hands-on content + is discoverable without leaving the guide. +- Cross-link the API reference from the task pages that use each resource. Link + specific custom resources and fields (for example, from live migration, + instance types, and storage pages) to their entries at + kubevirt.io/api-reference so instructions connect directly to reference + material. +- Normalize the minority of noun-based topic headings into goal-oriented verb or + gerund phrases, matching the existing style of headings such as "Creating + VirtualMachines on a cluster" and "Enabling the live-migration support." This + improves scanning and consistency across pages. +- Audit task coverage depth against recent release notes. Confirm that each + newer feature (for example, those introduced through v1.8.0) has a + corresponding end-to-end, goal-oriented task page, not just a conceptual or + configuration-field description. +- Separate concept from procedure on pages that currently interleave them, such + as the migration strategies and some networking topics, so readers can extract + the steps without reading through surrounding explanation. +- Periodically verify that inline examples, command output, and feature-gate + names match the latest release, since features graduate through alpha, beta, + and GA over time and can drift from the documented behavior. #### New user content @@ -717,31 +888,77 @@ to reach you. We evaluate on the following: -- Is there a Slack/Discord/Discourse/etc. community and is it prominently linked from your website? +- Is there a Slack/Discord/Discourse/etc. community and is it prominently linked + from your website? - Yes. The user guide's home page links directly to the KubeVirt Slack channel (`https://kubernetes.slack.com/messages/virtualization`) in its "Getting help" section, and the Contributing page invites readers to "participate on Slack" through the KubeVirt community page. The broader project website (`https://kubevirt.io/community/`) also surfaces the Slack workspace and channels alongside a forum. Within the user guide, the Slack link is reasonably visible on the landing page, but it appears only in a short "Getting help" list rather than in the persistent site navigation, so its prominence is limited. + Yes. The user guide's home page links directly to the KubeVirt Slack channel + (`https://kubernetes.slack.com/messages/virtualization`) in its "Getting help" + section, and the Contributing page invites readers to "participate on Slack" + through the KubeVirt community page. The broader project website + (`https://kubevirt.io/community/`) also surfaces the Slack workspace and + channels alongside a forum. Within the user guide, the Slack link is + reasonably visible on the landing page, but it appears only in a short + "Getting help" list rather than in the persistent site navigation, so its + prominence is limited. - Is there a direct link to your GitHub organization/repository? - Yes. The Contributing page links to the KubeVirt GitHub organization (`https://github.com/kubevirt`) and to individual repositories such as `user-guide`, `kubevirt`, `containerized-data-importer`, and `community`. The home page's "Getting help" section links directly to the issue tracker (`https://github.com/kubevirt/kubevirt/issues`). Direct GitHub links appear consistently throughout the guide. - -- Are weekly/monthly project meetings documented? Is it clear how someone can join those meetings? - - Not within the user guide itself. The guide does not state the cadence of community meetings or provide direct joining instructions; instead, the Contributing page defers to the community page to "learn about local meetups and events." The linked community page (`https://kubevirt.io/community/`) does document recurring community meetings and embeds a public Google Calendar (`kubevirt@cncf.io`) that readers can use to join. However, someone reading only the user guide would not find meeting times, cadence, or a join link without following that external link. + Yes. The Contributing page links to the KubeVirt GitHub organization + (`https://github.com/kubevirt`) and to individual repositories such as + `user-guide`, `kubevirt`, `containerized-data-importer`, and `community`. The + home page's "Getting help" section links directly to the issue tracker + (`https://github.com/kubevirt/kubevirt/issues`). Direct GitHub links appear + consistently throughout the guide. + +- Are weekly/monthly project meetings documented? Is it clear how someone can + join those meetings? + + Not within the user guide itself. The guide does not state the cadence of + community meetings or provide direct joining instructions; instead, the + Contributing page defers to the community page to "learn about local meetups + and events." The linked community page (`https://kubevirt.io/community/`) does + document recurring community meetings and embeds a public Google Calendar + (`kubevirt@cncf.io`) that readers can use to join. However, someone reading + only the user guide would not find meeting times, cadence, or a join link + without following that external link. - Are mailing lists documented? - Yes. The home page's "Getting help" section links to the kubevirt-dev mailing list (`https://groups.google.com/forum/#!forum/kubevirt-dev`), which is also reachable from the community page. The mailing list is documented, though it is presented as a bare link without describing its purpose or how it differs from Slack or the forum. + Yes. The home page's "Getting help" section links to the kubevirt-dev mailing + list (`https://groups.google.com/forum/#!forum/kubevirt-dev`), which is also + reachable from the community page. The mailing list is documented, though it + is presented as a bare link without describing its purpose or how it differs + from Slack or the forum. ##### Comment -The KubeVirt user guide provides a solid foundation of communication links for both users and contributors. The home page's "Getting help" section and the Contributing page together surface the Slack channel, the kubevirt-dev mailing list, the GitHub organization and its key repositories, and a pointer to the wider community page. As a result, readers have clear starting points to reach the project and its maintainers. - -The most significant gap is project meetings. The user guide does not document meeting cadence, times, or how to join; it only links to the community page for "meetups and events." Because those details live entirely on the external community page, a reader who stays within the user guide cannot learn when community meetings happen or how to attend. Adding a short "Community meetings" subsection that names the cadence and includes the public calendar link would close this gap and keep the information where contributors are already reading. - -Discoverability of the channels that are present could also be stronger. The Slack, mailing list, and issue links appear only in a brief list near the bottom of the landing page, and the Contributing page's community links are spread across several sections. Consolidating these into a single, clearly labeled "Community and communication" section—covering Slack, the forum, the mailing list, meetings, and social accounts—would make them easier to find. Giving each channel a one-line description of its purpose would also help newcomers choose where to ask a question versus where to follow announcements. - -Overall, the essential channels are documented and correctly linked, but meetings are absent from the guide itself and the presentation is uneven. Small, well-placed additions would move this area from adequate to strong. +The KubeVirt user guide provides a solid foundation of communication links for +both users and contributors. The home page's "Getting help" section and the +Contributing page together surface the Slack channel, the kubevirt-dev mailing +list, the GitHub organization and its key repositories, and a pointer to the +wider community page. As a result, readers have clear starting points to reach +the project and its maintainers. + +The most significant gap is project meetings. The user guide does not document +meeting cadence, times, or how to join; it only links to the community page for +"meetups and events." Because those details live entirely on the external +community page, a reader who stays within the user guide cannot learn when +community meetings happen or how to attend. Adding a short "Community meetings" +subsection that names the cadence and includes the public calendar link would +close this gap and keep the information where contributors are already reading. + +Discoverability of the channels that are present could also be stronger. The +Slack, mailing list, and issue links appear only in a brief list near the bottom +of the landing page, and the Contributing page's community links are spread +across several sections. Consolidating these into a single, clearly labeled +"Community and communication" section—covering Slack, the forum, the mailing +list, meetings, and social accounts—would make them easier to find. Giving each +channel a one-line description of its purpose would also help newcomers choose +where to ask a question versus where to follow announcements. + +Overall, the essential channels are documented and correctly linked, but +meetings are absent from the guide itself and the presentation is uneven. Small, +well-placed additions would move this area from adequate to strong. Rating: 3 - Meets standards @@ -751,34 +968,92 @@ We evaluate on the following: - Are docs issues well-triaged? - Documentation issues are only partially triaged. At the time of review the user-guide repository had four open issues, and three of them carried no labels at all; only one was categorized (with `kind/enhancement`). The repository does provide a complete triage label taxonomy (`kind/*`, `triage/accepted`, `triage/needs-information`, `sig/documentation`, and others), and closed issues show that labels such as `kind/bug` and `kind/enhancement` were applied over time. However, `triage/accepted` is rarely used, and the currently open backlog is largely uncategorized, so triage is inconsistent in practice. + Documentation issues are only partially triaged. At the time of review the + user-guide repository had four open issues, and three of them carried no + labels at all; only one was categorized (with `kind/enhancement`). The + repository does provide a complete triage label taxonomy (`kind/*`, + `triage/accepted`, `triage/needs-information`, `sig/documentation`, and + others), and closed issues show that labels such as `kind/bug` and + `kind/enhancement` were applied over time. However, `triage/accepted` is + rarely used, and the currently open backlog is largely uncategorized, so + triage is inconsistent in practice. - Is there a clearly marked way for new contributors to make code or documentation contributions (i.e. a “good first issue” label)? - Yes, a mechanism exists and is documented, but it is currently underused. The user-guide repository has a `good-first-issue` label that has been applied to 24 issues historically, and the contributing page explicitly tells newcomers to "look for any labeled 'good-first-issue', which are triaged to help new contributors." Two caveats reduce its effectiveness. First, there are currently zero open `good-first-issue` items in both the user-guide and the core kubevirt/kubevirt repositories, so a new contributor arriving today finds an empty beginner backlog. Second, the repository has two near-duplicate labels — the hyphenated `good-first-issue` that the team actually uses and the standard spaced `good first issue` that is unused — which is inconsistent and prevents GitHub's native "Contribute" tab from surfacing these issues. + Yes, a mechanism exists and is documented, but it is currently underused. The + user-guide repository has a `good-first-issue` label that has been applied to + 24 issues historically, and the contributing page explicitly tells newcomers + to "look for any labeled 'good-first-issue', which are triaged to help new + contributors." Two caveats reduce its effectiveness. First, there are + currently zero open `good-first-issue` items in both the user-guide and the + core kubevirt/kubevirt repositories, so a new contributor arriving today finds + an empty beginner backlog. Second, the repository has two near-duplicate + labels — the hyphenated `good-first-issue` that the team actually uses and the + standard spaced `good first issue` that is unused — which is inconsistent and + prevents GitHub's native "Contribute" tab from surfacing these issues. - Are issues well-documented (i.e., more than just a title)? - Yes. Issues generally contain substantive descriptions rather than bare titles. Bug reports follow a template with **Description**, **What you expected**, and **URL** sections, and enhancement requests use the feature-request template. The open issues ranged from roughly 400 to nearly 1,900 characters of body text; for example, the Simplified Chinese documentation proposal includes detailed context about the contributing team and scope. This indicates issues are typically actionable and provide enough information to begin work. + Yes. Issues generally contain substantive descriptions rather than bare + titles. Bug reports follow a template with **Description**, **What you + expected**, and **URL** sections, and enhancement requests use the + feature-request template. The open issues ranged from roughly 400 to nearly + 1,900 characters of body text; for example, the Simplified Chinese + documentation proposal includes detailed context about the contributing team + and scope. This indicates issues are typically actionable and provide enough + information to begin work. - Are issues maintained for staleness? - Yes, staleness is actively — and aggressively — managed by the shared KubeVirt Prow automation. Issues progress through `lifecycle/stale` and `lifecycle/rotten` and are then auto-closed, with `lifecycle/frozen` available to exempt long-lived items. Many closed user-guide issues carry the `lifecycle/rotten` label, and the core kubevirt/kubevirt repository currently shows roughly 31 stale, 32 rotten, and 30 frozen open issues. The main risk is that valid but unattended issues (including enhancements) are closed purely for inactivity rather than being triaged or preserved, so the backlog stays small partly through automated closure. + Yes, staleness is actively — and aggressively — managed by the shared KubeVirt + Prow automation. Issues progress through `lifecycle/stale` and + `lifecycle/rotten` and are then auto-closed, with `lifecycle/frozen` available + to exempt long-lived items. Many closed user-guide issues carry the + `lifecycle/rotten` label, and the core kubevirt/kubevirt repository currently + shows roughly 31 stale, 32 rotten, and 30 frozen open issues. The main risk is + that valid but unattended issues (including enhancements) are closed purely + for inactivity rather than being triaged or preserved, so the backlog stays + small partly through automated closure. ##### Comment -The KubeVirt user guide has the building blocks of a healthy beginner-friendly issue backlog, but the pieces are not consistently applied. A dedicated `good-first-issue` label exists and has been used on two dozen issues over time, and the contributing page clearly tells newcomers to look for it. Issues are generally well written: bug reports and feature requests follow templates with description, expectation, and URL fields, so most issues give a contributor enough context to start work rather than just a title. Staleness is handled automatically through the shared Prow lifecycle bot, which moves inactive issues through `lifecycle/stale` and `lifecycle/rotten` before closing them. - -The main gap is that the beginner backlog is effectively empty and the currently open issues are under-triaged. At the time of review there were no open `good-first-issue` items in either the user-guide or the core repository, so a new contributor who follows the documentation's advice finds nothing to pick up. Of the small number of open documentation issues, most carried no labels at all — no `kind/*`, no `sig/documentation`, and no `triage/accepted` — which means the backlog is not being actively categorized even though the label taxonomy is available. - -A specific, fixable inconsistency is the presence of two near-duplicate labels: the hyphenated `good-first-issue` that the team actually applies and the standard spaced `good first issue` that sits unused. GitHub's native "Contribute" experience and the good-first-issues discovery tooling key off the standard spaced label, so the project's real beginner issues are invisible to those channels. Consolidating on the standard label (or aliasing consistently) would immediately widen discovery. - -Finally, the aggressive auto-close behavior deserves attention. Because inactive issues — including valid enhancements — are closed as `lifecycle/rotten` rather than triaged or frozen, the backlog stays small in part by discarding work rather than curating it. A light triage pass that accepts, labels, and where appropriate freezes beginner-suitable issues would turn the existing automation and labels into a genuinely inviting on-ramp for new contributors. +The KubeVirt user guide has the building blocks of a healthy beginner-friendly +issue backlog, but the pieces are not consistently applied. A dedicated +`good-first-issue` label exists and has been used on two dozen issues over time, +and the contributing page clearly tells newcomers to look for it. Issues are +generally well written: bug reports and feature requests follow templates with +description, expectation, and URL fields, so most issues give a contributor +enough context to start work rather than just a title. Staleness is handled +automatically through the shared Prow lifecycle bot, which moves inactive issues +through `lifecycle/stale` and `lifecycle/rotten` before closing them. + +The main gap is that the beginner backlog is effectively empty and the currently +open issues are under-triaged. At the time of review there were no open +`good-first-issue` items in either the user-guide or the core repository, so a +new contributor who follows the documentation's advice finds nothing to pick up. +Of the small number of open documentation issues, most carried no labels at all +— no `kind/*`, no `sig/documentation`, and no `triage/accepted` — which means +the backlog is not being actively categorized even though the label taxonomy is +available. + +A specific, fixable inconsistency is the presence of two near-duplicate labels: +the hyphenated `good-first-issue` that the team actually applies and the +standard spaced `good first issue` that sits unused. GitHub's native +"Contribute" experience and the good-first-issues discovery tooling key off the +standard spaced label, so the project's real beginner issues are invisible to +those channels. Consolidating on the standard label (or aliasing consistently) +would immediately widen discovery. + +Finally, the aggressive auto-close behavior deserves attention. Because inactive +issues — including valid enhancements — are closed as `lifecycle/rotten` rather +than triaged or frozen, the backlog stays small in part by discarding work +rather than curating it. A light triage pass that accepts, labels, and where +appropriate freezes beginner-suitable issues would turn the existing automation +and labels into a genuinely inviting on-ramp for new contributors. Rating: 3 - Meets standards - #### New contributor getting started content Open source is complex and projects have many processes to manage that. Are @@ -789,25 +1064,73 @@ We evaluate on the following: - Do you have a community repository or section on your website? - Yes, both exist. KubeVirt maintains a dedicated `kubevirt/community` repository that holds governance, the membership policy and checklist, a maintainers list, per-SIG and working-group directories, community meeting information, and a code of conduct. The project website also has a community section at https://kubevirt.io/community/, and the user guide's contributing page links to it directly. New contributors therefore have a clear, discoverable home for community structure and processes. + Yes, both exist. KubeVirt maintains a dedicated `kubevirt/community` + repository that holds governance, the membership policy and checklist, a + maintainers list, per-SIG and working-group directories, community meeting + information, and a code of conduct. The project website also has a community + section at https://kubevirt.io/community/, and the user guide's contributing + page links to it directly. New contributors therefore have a clear, + discoverable home for community structure and processes. - Is there a document specifically for new contributors/your first contribution? - Yes. The user guide's [Contributing](https://kubevirt.io/user-guide/contributing/) page is the canonical getting-started document, and the community repository's own contributor file simply redirects to it, which avoids duplication. The page includes a "Prerequisites" section, a "Your first contribution" section that points newcomers to `good-first-issue` labeled work and to low-barrier documentation and community repositories, separate guidance for code contributors, a list of important community resources (code of conduct, membership policy, governance), and a link to a New Contributor session recording. This is a well-structured first-contribution path rather than a bare pointer to the issue tracker. + Yes. The user guide's + [Contributing](https://kubevirt.io/user-guide/contributing/) page is the + canonical getting-started document, and the community repository's own + contributor file simply redirects to it, which avoids duplication. The page + includes a "Prerequisites" section, a "Your first contribution" section that + points newcomers to `good-first-issue` labeled work and to low-barrier + documentation and community repositories, separate guidance for code + contributors, a list of important community resources (code of conduct, + membership policy, governance), and a link to a New Contributor session + recording. This is a well-structured first-contribution path rather than a + bare pointer to the issue tracker. - Do new users know where to get help? - Yes, though the help information is somewhat scattered and minimal in places. The user guide's landing page has a "Getting help" section listing the issue tracker, the `kubevirt-dev` mailing list, and the `#virtualization` Slack channel. The contributing page additionally points to the community page and the project's social channels, and the community repository README lists both the `#virtualization` and `#kubevirt-dev` Slack channels. The main weaknesses are that the user guide's "Getting help" section is only three bullets placed at the bottom of the index page, it does not link the community page, and it omits the `#kubevirt-dev` Slack channel, so the help entry points are not fully consistent across sources. + Yes, though the help information is somewhat scattered and minimal in places. + The user guide's landing page has a "Getting help" section listing the issue + tracker, the `kubevirt-dev` mailing list, and the `#virtualization` Slack + channel. The contributing page additionally points to the community page and + the project's social channels, and the community repository README lists both + the `#virtualization` and `#kubevirt-dev` Slack channels. The main weaknesses + are that the user guide's "Getting help" section is only three bullets placed + at the bottom of the index page, it does not link the community page, and it + omits the `#kubevirt-dev` Slack channel, so the help entry points are not + fully consistent across sources. ##### Comment -KubeVirt provides strong new contributor getting started content. The user guide's Contributing page serves as a single, well-organized entry point that covers prerequisites, a clear "Your first contribution" section, separate tracks for documentation and code contributors, and links to essential community resources such as the code of conduct, membership policy, and governance. Importantly, the community repository's own contributor file redirects to this page rather than duplicating it, so there is one canonical source of truth. This structure reflects a deliberate onboarding path rather than a bare pointer to the issue tracker. - -The project also gives newcomers a real community home. The `kubevirt/community` repository documents SIGs and working groups, community meetings, membership progression, and maintainers, and the website exposes a companion community section that the contributing page links to directly. Combined with a linked New Contributor session recording, a first-time contributor has both written and video onboarding material and a clear picture of how the community is organized. - -The main opportunity for improvement is the "Getting help" experience, which is thinner and less consistent than the rest of the onboarding content. In the user guide it is a three-bullet section at the bottom of the landing page that lists the issue tracker, mailing list, and the `#virtualization` Slack channel, but it omits the community page and the `#kubevirt-dev` Slack channel that appear in other sources. Consolidating these entry points and surfacing them more prominently would remove ambiguity about where to ask questions. - -A second, smaller gap connects to the beginner issue backlog: the contributing page tells newcomers to look for `good-first-issue` items, but that backlog is currently empty, so a motivated first-timer following the documentation can reach a dead end. Keeping a small pool of curated beginner issues would let the otherwise excellent onboarding content deliver on its promise. +KubeVirt provides strong new contributor getting started content. The user +guide's Contributing page serves as a single, well-organized entry point that +covers prerequisites, a clear "Your first contribution" section, separate tracks +for documentation and code contributors, and links to essential community +resources such as the code of conduct, membership policy, and governance. +Importantly, the community repository's own contributor file redirects to this +page rather than duplicating it, so there is one canonical source of truth. This +structure reflects a deliberate onboarding path rather than a bare pointer to +the issue tracker. + +The project also gives newcomers a real community home. The `kubevirt/community` +repository documents SIGs and working groups, community meetings, membership +progression, and maintainers, and the website exposes a companion community +section that the contributing page links to directly. Combined with a linked New +Contributor session recording, a first-time contributor has both written and +video onboarding material and a clear picture of how the community is organized. + +The main opportunity for improvement is the "Getting help" experience, which is +thinner and less consistent than the rest of the onboarding content. In the user +guide it is a three-bullet section at the bottom of the landing page that lists +the issue tracker, mailing list, and the `#virtualization` Slack channel, but it +omits the community page and the `#kubevirt-dev` Slack channel that appear in +other sources. Consolidating these entry points and surfacing them more +prominently would remove ambiguity about where to ask questions. + +A second, smaller gap connects to the beginner issue backlog: the contributing +page tells newcomers to look for `good-first-issue` items, but that backlog is +currently empty, so a motivated first-timer following the documentation can +reach a dead end. Keeping a small pool of curated beginner issues would let the +otherwise excellent onboarding content deliver on its promise. Rating: 4 - Meets or exceeds standards @@ -819,19 +1142,65 @@ We evaluate on the following: - Is project governance clearly documented? -Yes. Project governance is clearly and comprehensively documented, and the user guide points contributors to it. The community repository contains a dedicated `GOVERNANCE.md` that covers the membership policy, maintainer responsibilities and selection, meetings, CNCF resources, the code of conduct, off-boarding and removing maintainers, voting, SIGs, subprojects, working groups, and roles and organization management. It is complemented by a `MAINTAINERS.md` that lists current maintainers with their areas of responsibility and employers, tracks emeritus maintainers, and is kept in sync with the CNCF project-maintainers list. A `membership_policy.md` document defines a full contributor ladder — from new contributor through org member, reviewer, approver, SIG chair, subproject lead, and working-group chair — with explicit requirements, responsibilities, privileges, and an inactivity policy. An autogenerated `sig-list.md` (built from `sigs.yaml`) enumerates the SIGs, working groups, chairs, contacts, and meeting schedules. - -From the user guide's own perspective, the contributing page surfaces the governance material by linking to the project governance document, the membership policy, the code of conduct, and the AI contribution policy under its "Important community resources" section. The main limitation is discoverability rather than content: governance is only reachable through that one list on the contributing page, and the user guide has no dedicated governance or community landing page in its own navigation. The governance documentation itself, however, is thorough, versioned, and aligned with CNCF expectations. +Yes. Project governance is clearly and comprehensively documented, and the user +guide points contributors to it. The community repository contains a dedicated +`GOVERNANCE.md` that covers the membership policy, maintainer responsibilities +and selection, meetings, CNCF resources, the code of conduct, off-boarding and +removing maintainers, voting, SIGs, subprojects, working groups, and roles and +organization management. It is complemented by a `MAINTAINERS.md` that lists +current maintainers with their areas of responsibility and employers, tracks +emeritus maintainers, and is kept in sync with the CNCF project-maintainers +list. A `membership_policy.md` document defines a full contributor ladder — from +new contributor through org member, reviewer, approver, SIG chair, subproject +lead, and working-group chair — with explicit requirements, responsibilities, +privileges, and an inactivity policy. An autogenerated `sig-list.md` (built from +`sigs.yaml`) enumerates the SIGs, working groups, chairs, contacts, and meeting +schedules. + +From the user guide's own perspective, the contributing page surfaces the +governance material by linking to the project governance document, the +membership policy, the code of conduct, and the AI contribution policy under its +"Important community resources" section. The main limitation is discoverability +rather than content: governance is only reachable through that one list on the +contributing page, and the user guide has no dedicated governance or community +landing page in its own navigation. The governance documentation itself, +however, is thorough, versioned, and aligned with CNCF expectations. ##### Comment -KubeVirt's project governance documentation is a clear strength. The `kubevirt/community` repository provides a dedicated `GOVERNANCE.md` that addresses the full range of governance concerns: the membership policy, maintainer responsibilities and selection, meetings, voting, off-boarding and removal of maintainers, code of conduct, and the organization of SIGs, subprojects, and working groups. This is backed by a `MAINTAINERS.md` that names current maintainers and their areas of responsibility, records emeritus maintainers, and is explicitly kept in sync with the CNCF project-maintainers list. Together these documents give contributors an unambiguous picture of who leads the project and how decisions are made. - -The contributor ladder is especially well defined. The membership policy lays out each role — from new contributor through org member, reviewer, approver, SIG chair, subproject lead, and working-group chair — with concrete requirements, responsibilities, privileges, and an inactivity policy that explains how roles are maintained or lapse. The autogenerated SIG list, produced from a machine-readable `sigs.yaml`, keeps the list of groups, chairs, contacts, and meeting times consistent and current. This structure reflects mature, CNCF-aligned governance rather than a token document. - -The primary opportunity for improvement is discoverability from within the user guide itself. Governance is reachable only through a single "Important community resources" list on the contributing page; the user guide's own navigation has no dedicated community or governance entry point. A reader browsing the documentation site would not easily find how the project is governed without first landing on the contributing page. - -Because the analysis is scoped to the user guide, a light improvement would be to surface governance more prominently — for example, a short "How KubeVirt is governed" pointer or a community landing page that links to `GOVERNANCE.md`, the maintainers list, and the membership ladder. The underlying governance content is comprehensive and current; the gap is purely one of navigation from the documentation site. +KubeVirt's project governance documentation is a clear strength. The +`kubevirt/community` repository provides a dedicated `GOVERNANCE.md` that +addresses the full range of governance concerns: the membership policy, +maintainer responsibilities and selection, meetings, voting, off-boarding and +removal of maintainers, code of conduct, and the organization of SIGs, +subprojects, and working groups. This is backed by a `MAINTAINERS.md` that names +current maintainers and their areas of responsibility, records emeritus +maintainers, and is explicitly kept in sync with the CNCF project-maintainers +list. Together these documents give contributors an unambiguous picture of who +leads the project and how decisions are made. + +The contributor ladder is especially well defined. The membership policy lays +out each role — from new contributor through org member, reviewer, approver, SIG +chair, subproject lead, and working-group chair — with concrete requirements, +responsibilities, privileges, and an inactivity policy that explains how roles +are maintained or lapse. The autogenerated SIG list, produced from a +machine-readable `sigs.yaml`, keeps the list of groups, chairs, contacts, and +meeting times consistent and current. This structure reflects mature, +CNCF-aligned governance rather than a token document. + +The primary opportunity for improvement is discoverability from within the user +guide itself. Governance is reachable only through a single "Important community +resources" list on the contributing page; the user guide's own navigation has no +dedicated community or governance entry point. A reader browsing the +documentation site would not easily find how the project is governed without +first landing on the contributing page. + +Because the analysis is scoped to the user guide, a light improvement would be +to surface governance more prominently — for example, a short "How KubeVirt is +governed" pointer or a community landing page that links to `GOVERNANCE.md`, the +maintainers list, and the membership ladder. The underlying governance content +is comprehensive and current; the gap is purely one of navigation from the +documentation site. Rating: 4 - Meets or exceeds standards @@ -842,43 +1211,111 @@ Rating: 4 - Meets or exceeds standards #### Communication methods documented -- Add a dedicated "Community and communication" section to the user guide that consolidates Slack, the forum, the kubevirt-dev mailing list, community meetings, and social accounts in one clearly labeled place, rather than spreading these links across the home page and Contributing page. -- Document community meetings within the guide itself: state the cadence (for example, weekly or monthly), list the meeting times, and include the public Google Calendar link (`kubevirt@cncf.io`) so readers can join without leaving the guide. -- Give each communication channel a one-line description of its purpose so newcomers know where to ask a question, where to hold discussions, and where to follow announcements (for example, Slack for real-time chat, the mailing list or forum for longer discussions). -- Improve the discoverability of existing links by surfacing the Slack, mailing list, and GitHub links more prominently—such as in the persistent site navigation or a footer—instead of only in a short "Getting help" list near the bottom of the landing page. -- Clarify how the mailing list, the forum, and Slack relate to one another, since all three are currently presented as bare links; a brief note on when to use each avoids confusion for first-time contributors. -- Keep the community page and the user guide consistent so that channels documented on `kubevirt.io/community` (meetings, calendar, YouTube, social accounts) are either mirrored or clearly linked from the guide, ensuring readers who stay in the user guide are not missing key channels. +- Add a dedicated "Community and communication" section to the user guide that + consolidates Slack, the forum, the kubevirt-dev mailing list, community + meetings, and social accounts in one clearly labeled place, rather than + spreading these links across the home page and Contributing page. +- Document community meetings within the guide itself: state the cadence (for + example, weekly or monthly), list the meeting times, and include the public + Google Calendar link (`kubevirt@cncf.io`) so readers can join without leaving + the guide. +- Give each communication channel a one-line description of its purpose so + newcomers know where to ask a question, where to hold discussions, and where + to follow announcements (for example, Slack for real-time chat, the mailing + list or forum for longer discussions). +- Improve the discoverability of existing links by surfacing the Slack, mailing + list, and GitHub links more prominently—such as in the persistent site + navigation or a footer—instead of only in a short "Getting help" list near the + bottom of the landing page. +- Clarify how the mailing list, the forum, and Slack relate to one another, + since all three are currently presented as bare links; a brief note on when to + use each avoids confusion for first-time contributors. +- Keep the community page and the user guide consistent so that channels + documented on `kubevirt.io/community` (meetings, calendar, YouTube, social + accounts) are either mirrored or clearly linked from the guide, ensuring + readers who stay in the user guide are not missing key channels. #### Beginner friendly issue backlog -- Consolidate the duplicate labels by standardizing on the GitHub-native `good first issue` label (spaced) and retiring or aliasing the hyphenated `good-first-issue`, so beginner issues appear in GitHub's "Contribute" tab and good-first-issue discovery tooling. Update the reference on the contributing page to match the chosen label. -- Maintain a small, non-empty pool of beginner issues. Periodically identify documentation gaps, typos, and small feature-doc updates and file them as `good first issue` so a new contributor always finds something to pick up. -- Triage the currently open backlog. Apply `kind/*` and `sig/documentation` labels to unlabeled issues, and use `triage/accepted` to signal that an issue is ready to be worked on. -- Add a `help wanted` complement for slightly larger but still approachable tasks, and reference both `good first issue` and `help wanted` on the contributing page so contributors understand the difference. -- Preserve valuable issues from aggressive auto-close by applying `lifecycle/frozen` (or promptly triaging) to still-relevant enhancements and documentation requests, rather than letting them reach `lifecycle/rotten` and close for inactivity alone. -- Keep issue quality high by continuing to use the description/expectation/URL templates, and add a short "good first issue" checklist to those templates (affected page, expected outcome, pointers to relevant docs) so beginner issues are self-contained. -- Link directly to a filtered beginner view from the contributing page — for example, the repository's `good first issue` label query — so newcomers reach actionable issues in one click instead of browsing the full issue list. -- Publish a lightweight triage cadence (for example, a periodic documentation-issue triage during a SIG or community meeting) to keep labeling, acceptance, and staleness decisions consistent over time. +- Consolidate the duplicate labels by standardizing on the GitHub-native + `good first issue` label (spaced) and retiring or aliasing the hyphenated + `good-first-issue`, so beginner issues appear in GitHub's "Contribute" tab and + good-first-issue discovery tooling. Update the reference on the contributing + page to match the chosen label. +- Maintain a small, non-empty pool of beginner issues. Periodically identify + documentation gaps, typos, and small feature-doc updates and file them as + `good first issue` so a new contributor always finds something to pick up. +- Triage the currently open backlog. Apply `kind/*` and `sig/documentation` + labels to unlabeled issues, and use `triage/accepted` to signal that an issue + is ready to be worked on. +- Add a `help wanted` complement for slightly larger but still approachable + tasks, and reference both `good first issue` and `help wanted` on the + contributing page so contributors understand the difference. +- Preserve valuable issues from aggressive auto-close by applying + `lifecycle/frozen` (or promptly triaging) to still-relevant enhancements and + documentation requests, rather than letting them reach `lifecycle/rotten` and + close for inactivity alone. +- Keep issue quality high by continuing to use the description/expectation/URL + templates, and add a short "good first issue" checklist to those templates + (affected page, expected outcome, pointers to relevant docs) so beginner + issues are self-contained. +- Link directly to a filtered beginner view from the contributing page — for + example, the repository's `good first issue` label query — so newcomers reach + actionable issues in one click instead of browsing the full issue list. +- Publish a lightweight triage cadence (for example, a periodic + documentation-issue triage during a SIG or community meeting) to keep + labeling, acceptance, and staleness decisions consistent over time. #### New contributor getting started content -- Consolidate and strengthen the "Getting help" section on the user guide landing page so it lists all primary channels in one place: the `#virtualization` and `#kubevirt-dev` Slack channels, the `kubevirt-dev` mailing list, the community page, and the issue tracker. -- Make the "Getting help" information easier to find by linking to it from the contributing page and considering a more prominent placement than the bottom of the index page. -- Keep a small, curated pool of open `good-first-issue` items so that newcomers who follow the "Your first contribution" guidance always have actionable work, rather than reaching an empty backlog. -- Add a direct, filtered link from the contributing page to the current `good-first-issue` list (for example, a saved label query) so first-timers reach real issues in one click. -- Ensure help and community entry points are consistent across the user guide, the contributing page, and the `kubevirt/community` README, since they currently list slightly different channels. -- Consider adding a brief "how to ask a good question" note or expected-response-time guidance near the help channels so new contributors know what to include and where questions are best directed. -- Continue using the community repository's redirect-to-canonical approach for contributor docs, and periodically verify that all "get started" links across repositories still resolve to the single canonical contributing page. -- Optionally surface the New Contributor session recording and the community meeting schedule closer to the "Your first contribution" section so newcomers can quickly find live, synchronous ways to get onboarded. +- Consolidate and strengthen the "Getting help" section on the user guide + landing page so it lists all primary channels in one place: the + `#virtualization` and `#kubevirt-dev` Slack channels, the `kubevirt-dev` + mailing list, the community page, and the issue tracker. +- Make the "Getting help" information easier to find by linking to it from the + contributing page and considering a more prominent placement than the bottom + of the index page. +- Keep a small, curated pool of open `good-first-issue` items so that newcomers + who follow the "Your first contribution" guidance always have actionable work, + rather than reaching an empty backlog. +- Add a direct, filtered link from the contributing page to the current + `good-first-issue` list (for example, a saved label query) so first-timers + reach real issues in one click. +- Ensure help and community entry points are consistent across the user guide, + the contributing page, and the `kubevirt/community` README, since they + currently list slightly different channels. +- Consider adding a brief "how to ask a good question" note or + expected-response-time guidance near the help channels so new contributors + know what to include and where questions are best directed. +- Continue using the community repository's redirect-to-canonical approach for + contributor docs, and periodically verify that all "get started" links across + repositories still resolve to the single canonical contributing page. +- Optionally surface the New Contributor session recording and the community + meeting schedule closer to the "Your first contribution" section so newcomers + can quickly find live, synchronous ways to get onboarded. #### Project governance documentation -- Improve discoverability from the documentation site by adding a short "How KubeVirt is governed" pointer or a dedicated community/governance landing page that links to `GOVERNANCE.md`, the maintainers list, and the membership ladder, rather than relying solely on the contributing page's resource list. -- Surface the governance links in the user guide navigation (for example, under a community or contributing section) so readers can reach them without first knowing to open the contributing page. -- Add a brief, plain-language summary of the governance model and the contributor ladder in the user guide, with a clear link out to the authoritative documents in the community repository, so newcomers get an overview without reading the full policy. -- Continue keeping `MAINTAINERS.md` synchronized with the CNCF project-maintainers list, and note the last-reviewed date on the maintainers and governance documents so readers can gauge currency. -- Ensure the SIG list and its meeting details remain generated from `sigs.yaml`, and link the SIG list from the user guide so contributors can find the right group and meeting to join. -- Cross-link related governance artifacts (code of conduct, membership policy, AI contribution policy, and voting process) from a single place so contributors can navigate the full set without hunting across repositories. +- Improve discoverability from the documentation site by adding a short "How + KubeVirt is governed" pointer or a dedicated community/governance landing page + that links to `GOVERNANCE.md`, the maintainers list, and the membership + ladder, rather than relying solely on the contributing page's resource list. +- Surface the governance links in the user guide navigation (for example, under + a community or contributing section) so readers can reach them without first + knowing to open the contributing page. +- Add a brief, plain-language summary of the governance model and the + contributor ladder in the user guide, with a clear link out to the + authoritative documents in the community repository, so newcomers get an + overview without reading the full policy. +- Continue keeping `MAINTAINERS.md` synchronized with the CNCF + project-maintainers list, and note the last-reviewed date on the maintainers + and governance documents so readers can gauge currency. +- Ensure the SIG list and its meeting details remain generated from `sigs.yaml`, + and link the SIG list from the user guide so contributors can find the right + group and meeting to join. +- Cross-link related governance artifacts (code of conduct, membership policy, + AI contribution policy, and voting process) from a single place so + contributors can navigate the full set without hunting across repositories. ## Website and infrastructure @@ -968,37 +1405,84 @@ be much less effort than retrofitting a desktop-first design. - Is the website usable from mobile? - Yes. The live pages include a responsive viewport meta tag (`width=device-width,initial-scale=1`), and the Material for MkDocs theme is mobile-first and responsive, so the layout adapts to small screens. + Yes. The live pages include a responsive viewport meta tag + (`width=device-width,initial-scale=1`), and the Material for MkDocs theme is + mobile-first and responsive, so the layout adapts to small screens. - Are doc pages readable? - Yes. Pages use the theme's clean Roboto typography, clear heading hierarchy, an in-page table of contents, admonitions, and syntax-highlighted code blocks, all of which support comfortable reading on the documentation site. + Yes. Pages use the theme's clean Roboto typography, clear heading hierarchy, + an in-page table of contents, admonitions, and syntax-highlighted code blocks, + all of which support comfortable reading on the documentation site. -- Are all / most website features accessible from mobile -- such as the top-nav, site search and in-page table of contents? +- Are all / most website features accessible from mobile -- such as the top-nav, + site search and in-page table of contents? - Yes. The primary navigation (rendered as tabs on desktop) collapses into a mobile drawer, site search is present (`md-search`), and the in-page table of contents is available. All are exposed with descriptive ARIA labels (for example, "Header," "Navigation," "Search," "Table of contents," and "Tabs"), so the key features remain reachable on mobile. + Yes. The primary navigation (rendered as tabs on desktop) collapses into a + mobile drawer, site search is present (`md-search`), and the in-page table of + contents is available. All are exposed with descriptive ARIA labels (for + example, "Header," "Navigation," "Search," "Table of contents," and "Tabs"), + so the key features remain reachable on mobile. - Are color contrasts significant enough for color-impaired readers? - Partially, and this is the area's weakest point. The brand teal used as the primary color (`--md-primary-fg-color: #0db2b6`, set in `docs/stylesheets/extra.css`) provides only about a 2.6:1 contrast ratio with the white header text, which is below the WCAG AA threshold of 4.5:1 for normal text and even below the 3:1 threshold for large text. Body links are darkened with `filter: brightness(80%)`, which improves them to roughly 3.96:1 but still falls short of the 4.5:1 AA requirement for normal text. Contrast therefore needs improvement for color-impaired readers. + Partially, and this is the area's weakest point. The brand teal used as the + primary color (`--md-primary-fg-color: #0db2b6`, set in + `docs/stylesheets/extra.css`) provides only about a 2.6:1 contrast ratio with + the white header text, which is below the WCAG AA threshold of 4.5:1 for + normal text and even below the 3:1 threshold for large text. Body links are + darkened with `filter: brightness(80%)`, which improves them to roughly 3.96:1 + but still falls short of the 4.5:1 AA requirement for normal text. Contrast + therefore needs improvement for color-impaired readers. - Are most website features usable using a keyboard only? - Yes. The page includes a "Skip to content" link (`md-skip`), and the Material theme provides full keyboard navigation and search keyboard shortcuts, so the main features can be operated without a mouse. + Yes. The page includes a "Skip to content" link (`md-skip`), and the Material + theme provides full keyboard navigation and search keyboard shortcuts, so the + main features can be operated without a mouse. - Does text-to-speech offer listeners a good experience? - Largely yes. The document declares its language (``), uses semantic landmarks and ARIA labels, provides a skip link, and every image in the documentation carries non-empty alt text (25 markdown images, none with empty alt, and no raw `` tags lacking `alt`). These give screen readers and text-to-speech tools a solid foundation, though the ongoing quality of alt text and heading order depends on authors. + Largely yes. The document declares its language (``), uses + semantic landmarks and ARIA labels, provides a skip link, and every image in + the documentation carries non-empty alt text (25 markdown images, none with + empty alt, and no raw `` tags lacking `alt`). These give screen readers + and text-to-speech tools a solid foundation, though the ongoing quality of alt + text and heading order depends on authors. ##### Comment -The KubeVirt user guide is highly usable and, for the most part, accessible, thanks to its Material for MkDocs foundation. The site is responsive and works well on mobile: it sets a proper viewport, collapses the top navigation into a mobile drawer, and keeps site search and the in-page table of contents reachable on small screens. Pages are readable, with clean typography, clear heading structure, and syntax-highlighted code, so readers can move through technical content comfortably on any device. - -Accessibility support is strong at the structural level. The document declares its language, exposes semantic landmarks and descriptive ARIA labels (Header, Navigation, Search, Table of contents, Tabs), and provides a "Skip to content" link, all of which help keyboard and screen-reader users. Keyboard-only operation is well supported through the theme's navigation and search shortcuts. Text-to-speech users are also well served: every image in the documentation carries non-empty alt text, and there are no raw image tags missing an `alt` attribute. - -The clear weak point is color contrast. The brand teal used as the primary color (`#0db2b6` in `docs/stylesheets/extra.css`) yields only about 2.6:1 against the white header text, which fails the WCAG AA requirement of 4.5:1 for normal text and even the 3:1 threshold for large text. Body links, darkened with `filter: brightness(80%)`, reach roughly 3.96:1 but still fall short of 4.5:1. This affects color-impaired and low-vision readers most, and it is the single most impactful fix in this area. - -Addressing contrast would be straightforward and high value: darken the primary teal (or the text placed on it) until header text and links meet WCAG AA, and verify the result in both the light and dark schemes. To sustain accessibility over time, maintainers could add an automated contrast and accessibility check to the build and keep encouraging descriptive alt text and correct heading order in new pages. +The KubeVirt user guide is highly usable and, for the most part, accessible, +thanks to its Material for MkDocs foundation. The site is responsive and works +well on mobile: it sets a proper viewport, collapses the top navigation into a +mobile drawer, and keeps site search and the in-page table of contents reachable +on small screens. Pages are readable, with clean typography, clear heading +structure, and syntax-highlighted code, so readers can move through technical +content comfortably on any device. + +Accessibility support is strong at the structural level. The document declares +its language, exposes semantic landmarks and descriptive ARIA labels (Header, +Navigation, Search, Table of contents, Tabs), and provides a "Skip to content" +link, all of which help keyboard and screen-reader users. Keyboard-only +operation is well supported through the theme's navigation and search shortcuts. +Text-to-speech users are also well served: every image in the documentation +carries non-empty alt text, and there are no raw image tags missing an `alt` +attribute. + +The clear weak point is color contrast. The brand teal used as the primary color +(`#0db2b6` in `docs/stylesheets/extra.css`) yields only about 2.6:1 against the +white header text, which fails the WCAG AA requirement of 4.5:1 for normal text +and even the 3:1 threshold for large text. Body links, darkened with +`filter: brightness(80%)`, reach roughly 3.96:1 but still fall short of 4.5:1. +This affects color-impaired and low-vision readers most, and it is the single +most impactful fix in this area. + +Addressing contrast would be straightforward and high value: darken the primary +teal (or the text placed on it) until header text and links meet WCAG AA, and +verify the result in both the light and dark schemes. To sustain accessibility +over time, maintainers could add an automated contrast and accessibility check +to the build and keep encouraging descriptive alt text and correct heading order +in new pages. Rating: 4 - Meets or exceeds standards @@ -1009,27 +1493,74 @@ this is branding and marketing. We evaluate on the following: -- Is there an easily recognizable brand for the project (logo + color scheme) clearly identifiable? +- Is there an easily recognizable brand for the project (logo + color scheme) + clearly identifiable? - Yes. The KubeVirt logo, a teal heptagon enclosing a stylized "V," is displayed in the site header and configured through `theme.logo: assets/KubeVirt_icon.png`, with matching favicons (`assets/favicon.ico` and `assets/favicon32x32.png`) in `mkdocs.yml`. The color scheme reinforces the logo: the Material theme uses a teal palette, and `docs/stylesheets/extra.css` pins the exact brand colors (`--md-primary-fg-color: #0db2b6` and `--md-accent-fg-color: #006166`). Together the logo and teal palette make the project brand clearly identifiable on every page. + Yes. The KubeVirt logo, a teal heptagon enclosing a stylized "V," is displayed + in the site header and configured through + `theme.logo: assets/KubeVirt_icon.png`, with matching favicons + (`assets/favicon.ico` and `assets/favicon32x32.png`) in `mkdocs.yml`. The + color scheme reinforces the logo: the Material theme uses a teal palette, and + `docs/stylesheets/extra.css` pins the exact brand colors + (`--md-primary-fg-color: #0db2b6` and `--md-accent-fg-color: #006166`). + Together the logo and teal palette make the project brand clearly identifiable + on every page. - Is the brand used across the website consistently? - Within the user guide, yes. The teal palette is applied globally through the Material theme and `extra.css`, so the primary and accent colors are consistent across all pages and are defined for both the light (`default`) and dark (`slate`) schemes. The logo appears in the header site-wide, and section labels in the navigation are given a coordinated teal tone (`#00797f`). One caveat is that the user guide is a MkDocs Material site, while the main `kubevirt.io` website is a separate property with its own styling, so the two share the logo and general color family but do not share an identical look and feel. + Within the user guide, yes. The teal palette is applied globally through the + Material theme and `extra.css`, so the primary and accent colors are + consistent across all pages and are defined for both the light (`default`) and + dark (`slate`) schemes. The logo appears in the header site-wide, and section + labels in the navigation are given a coordinated teal tone (`#00797f`). One + caveat is that the user guide is a MkDocs Material site, while the main + `kubevirt.io` website is a separate property with its own styling, so the two + share the logo and general color family but do not share an identical look and + feel. - Is the website's typography clean and well-suited for reading? - Yes. The guide does not override the theme fonts, so it inherits the Material theme's default typeface (Roboto for body text and Roboto Mono for code), which is a clean, legible sans-serif well-suited to on-screen reading. Headings, body copy, tables, and code blocks are styled consistently by the theme, code uses monospaced type with syntax highlighting, and tables are set to full width (`min-width: 100%`) for readability. The custom `filter: brightness(80%)` applied to links slightly darkens link text, which is a minor contrast consideration but does not materially harm readability. + Yes. The guide does not override the theme fonts, so it inherits the Material + theme's default typeface (Roboto for body text and Roboto Mono for code), + which is a clean, legible sans-serif well-suited to on-screen reading. + Headings, body copy, tables, and code blocks are styled consistently by the + theme, code uses monospaced type with syntax highlighting, and tables are set + to full width (`min-width: 100%`) for readability. The custom + `filter: brightness(80%)` applied to links slightly darkens link text, which + is a minor contrast consideration but does not materially harm readability. ##### Comment -The KubeVirt user guide presents a clear and recognizable brand. The project's teal heptagon logo appears in the site header, and the Material theme is configured with a teal palette that is anchored to the exact brand colors in `docs/stylesheets/extra.css` (`#0db2b6` primary and `#006166` accent). Because these colors are defined at the theme level, the brand identity carries across every page rather than depending on individual authors, which is the right approach for a documentation site. - -Brand usage is consistent within the guide. The palette is defined for both the light and dark color schemes, the logo and favicons are set globally, and navigation section labels use a coordinated teal tone. The main point of friction is cross-property consistency: the user guide is a MkDocs Material site, while the primary `kubevirt.io` website is a separate property with its own styling. The two share the logo and color family but not an identical look and feel, so a reader moving between them will notice the shift. Documenting a small set of shared brand values (hex colors, logo files, and font choices) would help keep the properties aligned over time. - -Typography is clean and well-suited for reading. By not overriding the theme fonts, the guide inherits Material's default Roboto and Roboto Mono, which are legible on screen and applied consistently to headings, body text, tables, and syntax-highlighted code. One minor design choice worth revisiting is the `filter: brightness(80%)` rule applied to links, which darkens link text and could reduce contrast in some contexts; verifying it against accessibility contrast targets would remove any doubt. - -Overall, the branding and design are in good shape: the brand is identifiable, applied consistently within the guide, and paired with readable typography. The main opportunities are cross-site brand alignment and a quick contrast check of the customized link styling. +The KubeVirt user guide presents a clear and recognizable brand. The project's +teal heptagon logo appears in the site header, and the Material theme is +configured with a teal palette that is anchored to the exact brand colors in +`docs/stylesheets/extra.css` (`#0db2b6` primary and `#006166` accent). Because +these colors are defined at the theme level, the brand identity carries across +every page rather than depending on individual authors, which is the right +approach for a documentation site. + +Brand usage is consistent within the guide. The palette is defined for both the +light and dark color schemes, the logo and favicons are set globally, and +navigation section labels use a coordinated teal tone. The main point of +friction is cross-property consistency: the user guide is a MkDocs Material +site, while the primary `kubevirt.io` website is a separate property with its +own styling. The two share the logo and color family but not an identical look +and feel, so a reader moving between them will notice the shift. Documenting a +small set of shared brand values (hex colors, logo files, and font choices) +would help keep the properties aligned over time. + +Typography is clean and well-suited for reading. By not overriding the theme +fonts, the guide inherits Material's default Roboto and Roboto Mono, which are +legible on screen and applied consistently to headings, body text, tables, and +syntax-highlighted code. One minor design choice worth revisiting is the +`filter: brightness(80%)` rule applied to links, which darkens link text and +could reduce contrast in some contexts; verifying it against accessibility +contrast targets would remove any doubt. + +Overall, the branding and design are in good shape: the brand is identifiable, +applied consistently within the guide, and paired with readable typography. The +main opportunities are cross-site brand alignment and a quick contrast check of +the customized link styling. Rating: 4 - Meets or exceeds standards @@ -1040,33 +1571,66 @@ organizations using it. We evaluate on the following: -fic organizations adopted and benefited from KubeVirt. The user guide itself contains only technical documentation and does not link to any case studies. +fic organizations adopted and benefited from KubeVirt. The user guide itself +contains only technical documentation and does not link to any case studies. - Are there user testimonials available? - Not evident. The website lists adopting organizations by logo, but there are no quoted testimonials from users describing their experience or outcomes. The user guide does not include or reference testimonials. + Not evident. The website lists adopting organizations by logo, but there are + no quoted testimonials from users describing their experience or outcomes. The + user guide does not include or reference testimonials. - Is there an active project blog? - Yes. The `kubevirt.io` site maintains an active blog with regular posts; recent entries are dated 2026 (for example, "Beta Features Enabled by Default in KubeVirt v1.9" and "Announcing the release of KubeVirt v1.8"), covering releases, features, and technical topics. The blog lives on the main site; the user guide links to release notes but does not link directly to the blog. + Yes. The `kubevirt.io` site maintains an active blog with regular posts; + recent entries are dated 2026 (for example, "Beta Features Enabled by Default + in KubeVirt v1.9" and "Announcing the release of KubeVirt v1.8"), covering + releases, features, and technical topics. The blog lives on the main site; the + user guide links to release notes but does not link directly to the blog. - Are there community talks for the project and are they present on the website? - Yes. The `kubevirt.io/videos/` page organizes community talks into curated YouTube playlists, including Talks, Demos, Interviews, and the annual KubeVirt Summit, alongside recorded community meetings. This content is well organized on the main site, but the user guide does not surface or link to it. + Yes. The `kubevirt.io/videos/` page organizes community talks into curated + YouTube playlists, including Talks, Demos, Interviews, and the annual KubeVirt + Summit, alongside recorded community meetings. This content is well organized + on the main site, but the user guide does not surface or link to it. - Is there a logo wall of users/participating organizations? - Yes. The website homepage features a prominent logo wall grouped into End Users (such as Arm, Aussie Broadband, Cloudflare, CoreWeave, and NVIDIA), Vendors (such as Deckhouse, Microsoft, Oracle, Red Hat, and SUSE), and Integrations. The user guide does not display or link to this logo wall. + Yes. The website homepage features a prominent logo wall grouped into End + Users (such as Arm, Aussie Broadband, Cloudflare, CoreWeave, and NVIDIA), + Vendors (such as Deckhouse, Microsoft, Oracle, Red Hat, and SUSE), and + Integrations. The user guide does not display or link to this logo wall. ##### Comment -KubeVirt has a strong base of community and adoption content, though it lives on the main `kubevirt.io` website rather than in the user guide. The website maintains an active blog with recent posts dated 2026, organizes community talks into curated YouTube playlists (Talks, Demos, Interviews, and the annual KubeVirt Summit), and presents an extensive logo wall of adopting organizations grouped into End Users, Vendors, and Integrations. These are clear signals of a healthy, active project and provide good social proof for prospective users. - -The main gaps are dedicated case studies and user testimonials. The adopter logo walls show who uses KubeVirt but do not explain how or why, and there are no quoted testimonials describing real-world outcomes. Narrative case studies, even a small number, would help prospective adopters understand practical use cases, migration paths, and the benefits organizations have realized. These carry particular weight for an infrastructure project where adoption decisions are significant. - -From the user guide's perspective, the more immediate issue is discoverability. The guide is technical documentation and does not link to the blog, community talks, or adopter logo wall at all. A reader who lands in the user guide has no easy path to this adoption and community content, even though it exists one site over. Adding a few targeted links, for example from the landing page or a "Community" or "Adopters" entry, would connect readers to material that builds confidence in the project. - -Overall, the project scores well on blog, talks, and a logo wall, but lacks true case studies and testimonials, and the user guide does not surface the adoption content that already exists. Closing those gaps would round out this area. +KubeVirt has a strong base of community and adoption content, though it lives on +the main `kubevirt.io` website rather than in the user guide. The website +maintains an active blog with recent posts dated 2026, organizes community talks +into curated YouTube playlists (Talks, Demos, Interviews, and the annual +KubeVirt Summit), and presents an extensive logo wall of adopting organizations +grouped into End Users, Vendors, and Integrations. These are clear signals of a +healthy, active project and provide good social proof for prospective users. + +The main gaps are dedicated case studies and user testimonials. The adopter logo +walls show who uses KubeVirt but do not explain how or why, and there are no +quoted testimonials describing real-world outcomes. Narrative case studies, even +a small number, would help prospective adopters understand practical use cases, +migration paths, and the benefits organizations have realized. These carry +particular weight for an infrastructure project where adoption decisions are +significant. + +From the user guide's perspective, the more immediate issue is discoverability. +The guide is technical documentation and does not link to the blog, community +talks, or adopter logo wall at all. A reader who lands in the user guide has no +easy path to this adoption and community content, even though it exists one site +over. Adding a few targeted links, for example from the landing page or a +"Community" or "Adopters" entry, would connect readers to material that builds +confidence in the project. + +Overall, the project scores well on blog, talks, and a logo wall, but lacks true +case studies and testimonials, and the user guide does not surface the adoption +content that already exists. Closing those gaps would round out this area. Rating: 3 - Meets standards @@ -1080,41 +1644,89 @@ We evaluate on the following: - Is analytics enabled for the production server? - No. The user guide's `mkdocs.yml` has no `extra.analytics` configuration, and the live production pages contain no analytics tags (no Google Analytics, Google Tag Manager, or measurement ID). The main `kubevirt.io` homepage likewise shows no analytics tags. This appears consistent with the project's privacy stance, but it means no usage analytics are collected. + No. The user guide's `mkdocs.yml` has no `extra.analytics` configuration, and + the live production pages contain no analytics tags (no Google Analytics, + Google Tag Manager, or measurement ID). The main `kubevirt.io` homepage + likewise shows no analytics tags. This appears consistent with the project's + privacy stance, but it means no usage analytics are collected. - Is analytics disabled for all other deploys? - Not applicable in practice. Because no analytics is configured anywhere, it is inherently absent from pull-request previews and non-default branch builds as well. The intended "production-only analytics" pattern cannot be assessed since there is no analytics to scope. + Not applicable in practice. Because no analytics is configured anywhere, it is + inherently absent from pull-request previews and non-default branch builds as + well. The intended "production-only analytics" pattern cannot be assessed + since there is no analytics to scope. - If project is using Google Analytics, has it migrated to GA4? - Not applicable. The project does not use Google Analytics on the user guide, so there is no Universal Analytics or GA4 property in use to migrate. + Not applicable. The project does not use Google Analytics on the user guide, + so there is no Universal Analytics or GA4 property in use to migrate. - Can Page-not-found (404) reports easily be generated from site analytics? - No. Material for MkDocs generates a `404.html` page, but without any analytics in place there is no mechanism to report on 404 hits or generate not-found reports from site analytics. + No. Material for MkDocs generates a `404.html` page, but without any analytics + in place there is no mechanism to report on 404 hits or generate not-found + reports from site analytics. -- Is site indexing supported for the production server, while disabled for website previews and builds for non-default branches? +- Is site indexing supported for the production server, while disabled for + website previews and builds for non-default branches? - Partially. Production indexing is supported: a site-wide `robots.txt` is served (returning 200) with a `Sitemap` directive and no `Disallow` rules, MkDocs generates a `sitemap.xml`, and pages carry no `noindex` meta tag. Pull-request previews are built on Netlify, whose deploy-preview and branch-deploy subdomains are served with a `noindex` `X-Robots-Tag` by Netlify's default behavior; however, this preview-noindex behavior is not explicitly configured in `netlify.toml`, so it relies on the platform default rather than an intentional project setting. One minor SEO defect is that the `robots.txt` Sitemap URL contains a double slash (`https://kubevirt.io//sitemap.xml`). + Partially. Production indexing is supported: a site-wide `robots.txt` is + served (returning 200) with a `Sitemap` directive and no `Disallow` rules, + MkDocs generates a `sitemap.xml`, and pages carry no `noindex` meta tag. + Pull-request previews are built on Netlify, whose deploy-preview and + branch-deploy subdomains are served with a `noindex` `X-Robots-Tag` by + Netlify's default behavior; however, this preview-noindex behavior is not + explicitly configured in `netlify.toml`, so it relies on the platform default + rather than an intentional project setting. One minor SEO defect is that the + `robots.txt` Sitemap URL contains a double slash + (`https://kubevirt.io//sitemap.xml`). - Is local intra-site search available from the website? - Yes. The MkDocs `search` plugin is enabled in `mkdocs.yml` (with a customized separator), and the Material theme provides the search box and results UI, giving readers client-side, intra-site search across the user guide. + Yes. The MkDocs `search` plugin is enabled in `mkdocs.yml` (with a customized + separator), and the Material theme provides the search box and results UI, + giving readers client-side, intra-site search across the user guide. -- Are the current custodian(s) of the analytics accounts (such as Google CSE) documented? +- Are the current custodian(s) of the analytics accounts (such as Google CSE) + documented? - No. No analytics or search-account custodians are documented in the repository. Since no analytics account currently exists there is nothing to attribute, but there is also no documented owner should analytics be introduced. + No. No analytics or search-account custodians are documented in the + repository. Since no analytics account currently exists there is nothing to + attribute, but there is also no documented owner should analytics be + introduced. ##### Comment -The KubeVirt user guide handles site search and basic SEO well but has no analytics at all. Local intra-site search is enabled through the MkDocs `search` plugin and surfaced by the Material theme, giving readers fast client-side search across the documentation. For discoverability, the production site is indexable: a site-wide `robots.txt` is served with a `Sitemap` directive and no blocking rules, MkDocs generates a `sitemap.xml`, and pages carry no `noindex` tag. Pull-request previews are built on Netlify, whose preview subdomains are `noindex` by default, which keeps previews out of search results. - -The clear gap is analytics. Neither the user guide nor the main site includes any analytics tags, so there is no visibility into traffic, popular pages, search terms, or broken links. In particular, 404 reports cannot be generated from analytics, which makes it harder to find and fix broken inbound links over time. This absence appears consistent with the project's privacy posture, and that is a legitimate trade-off; but if the project wants data to guide documentation improvements, a privacy-respecting analytics option would fill an important blind spot. - -If analytics is introduced, a few practices are worth adopting up front. Use a GA4 property (or a privacy-friendly alternative), enable it only on the production deploy while leaving previews and non-default branches untracked, and document the account custodians so ownership is clear as maintainers change. Configuring these through the theme rather than per page keeps the setup consistent. - -Two smaller items round out the SEO picture: make the preview `noindex` behavior an explicit project setting rather than relying on the Netlify default, and fix the double slash in the `robots.txt` Sitemap URL (`https://kubevirt.io//sitemap.xml`). +The KubeVirt user guide handles site search and basic SEO well but has no +analytics at all. Local intra-site search is enabled through the MkDocs `search` +plugin and surfaced by the Material theme, giving readers fast client-side +search across the documentation. For discoverability, the production site is +indexable: a site-wide `robots.txt` is served with a `Sitemap` directive and no +blocking rules, MkDocs generates a `sitemap.xml`, and pages carry no `noindex` +tag. Pull-request previews are built on Netlify, whose preview subdomains are +`noindex` by default, which keeps previews out of search results. + +The clear gap is analytics. Neither the user guide nor the main site includes +any analytics tags, so there is no visibility into traffic, popular pages, +search terms, or broken links. In particular, 404 reports cannot be generated +from analytics, which makes it harder to find and fix broken inbound links over +time. This absence appears consistent with the project's privacy posture, and +that is a legitimate trade-off; but if the project wants data to guide +documentation improvements, a privacy-respecting analytics option would fill an +important blind spot. + +If analytics is introduced, a few practices are worth adopting up front. Use a +GA4 property (or a privacy-friendly alternative), enable it only on the +production deploy while leaving previews and non-default branches untracked, and +document the account custodians so ownership is clear as maintainers change. +Configuring these through the theme rather than per page keeps the setup +consistent. + +Two smaller items round out the SEO picture: make the preview `noindex` behavior +an explicit project setting rather than relying on the Netlify default, and fix +the double slash in the `robots.txt` Sitemap URL +(`https://kubevirt.io//sitemap.xml`). Rating: 2 - Needs improvement @@ -1125,39 +1737,82 @@ project maintainers aren’t web developers. We evaluate on the following: -- Is the website tooling well supported by the community (i.e., Hugo with the Docsy theme) or commonly used by CNCF projects? +- Is the website tooling well supported by the community (i.e., Hugo with the + Docsy theme) or commonly used by CNCF projects? - Yes. The user guide is built with MkDocs and the Material for MkDocs theme, along with the `awesome-nav`, `redirects`, and `html-proofer` plugins (see `mkdocs.yml`, `Makefile`, and `netlify.toml`). While this is not the Hugo and Docsy stack named in the question, MkDocs Material is a mature, actively maintained, and widely adopted documentation tool used across many CNCF and Kubernetes-ecosystem projects, so the tooling is well supported. Note that the main `kubevirt.io` website is a separate Jekyll site, so the project maintains two different stacks. + Yes. The user guide is built with MkDocs and the Material for MkDocs theme, + along with the `awesome-nav`, `redirects`, and `html-proofer` plugins (see + `mkdocs.yml`, `Makefile`, and `netlify.toml`). While this is not the Hugo and + Docsy stack named in the question, MkDocs Material is a mature, actively + maintained, and widely adopted documentation tool used across many CNCF and + Kubernetes-ecosystem projects, so the tooling is well supported. Note that the + main `kubevirt.io` website is a separate Jekyll site, so the project maintains + two different stacks. - Is there active cultivating website maintainers from within the community? - Yes. The repository has an `OWNERS` file that defines reviewers and approvers roles (via aliases) and lists emeritus approvers, and the project uses the Kubernetes-style OWNERS model for delegating maintenance. Git history shows sustained activity, with roughly 49 distinct authors contributing in the last 12 months and a steady stream of merged pull requests, indicating an active and growing maintainer and contributor base. + Yes. The repository has an `OWNERS` file that defines reviewers and approvers + roles (via aliases) and lists emeritus approvers, and the project uses the + Kubernetes-style OWNERS model for delegating maintenance. Git history shows + sustained activity, with roughly 49 distinct authors contributing in the last + 12 months and a steady stream of merged pull requests, indicating an active + and growing maintainer and contributor base. - Are site build times reasonable? - Yes. MkDocs produces a static site of this size quickly, typically well under a minute, and the build is a straightforward `mkdocs build`. Netlify builds preview deployments for pull requests and the project's Prow-based CI builds the site as well, so build times are reasonable for both previews and production. + Yes. MkDocs produces a static site of this size quickly, typically well under + a minute, and the build is a straightforward `mkdocs build`. Netlify builds + preview deployments for pull requests and the project's Prow-based CI builds + the site as well, so build times are reasonable for both previews and + production. - Do site maintainers have adequate permissions? - Yes. Permissions are managed through the Kubernetes-style OWNERS model, where designated approvers can approve and merge changes and reviewers can review. The `OWNERS` file separates reviewers and approvers and records emeritus approvers, giving maintainers the access they need while keeping the roles documented. + Yes. Permissions are managed through the Kubernetes-style OWNERS model, where + designated approvers can approve and merge changes and reviewers can review. + The `OWNERS` file separates reviewers and approvers and records emeritus + approvers, giving maintainers the access they need while keeping the roles + documented. - Is the website accessible via HTTPS? - Yes. Requesting `https://kubevirt.io/user-guide/` returns HTTP 200 over HTTPS. + Yes. Requesting `https://kubevirt.io/user-guide/` returns HTTP 200 over HTTPS. - Does HTTP access, if any, redirect to HTTPS? - Yes. Requesting `http://kubevirt.io/user-guide/` returns a 301 redirect to the HTTPS URL, and the apex `http://kubevirt.io/` likewise 301-redirects to HTTPS. + Yes. Requesting `http://kubevirt.io/user-guide/` returns a 301 redirect to the + HTTPS URL, and the apex `http://kubevirt.io/` likewise 301-redirects to HTTPS. ##### Comment -The KubeVirt user guide is on a solid maintenance footing. It is built with MkDocs and the Material for MkDocs theme, supplemented by the `awesome-nav`, `redirects`, and `html-proofer` plugins. Although this differs from the Hugo and Docsy stack, MkDocs Material is a mature and widely adopted documentation toolchain used across the CNCF and Kubernetes ecosystems, so maintainers can rely on strong community support and a steady stream of upstream updates. - -Maintenance responsibility is clearly structured and actively exercised. The repository uses the Kubernetes-style OWNERS model, defining reviewers and approvers roles and recording emeritus approvers, which gives maintainers appropriate permissions to review and merge changes. The commit history reflects a healthy, cultivated community, with roughly 49 distinct authors in the last twelve months and a continuous flow of merged pull requests, so the guide is not dependent on a single maintainer. - -The build and hosting setup is dependable. MkDocs builds this static site quickly, Netlify produces per-pull-request previews, and the project's Prow-based CI builds the site as well. The site is served securely: HTTPS returns a 200 response, and HTTP requests are 301-redirected to HTTPS for both the user guide path and the apex domain. These are exactly the properties one wants for low-friction, secure maintenance. - -The main opportunities are around build reproducibility and stack consolidation. The build installs MkDocs and its plugins without pinned versions (in `netlify.toml` and the `Makefile`), which risks non-reproducible builds or breakage when an upstream package changes; pinning versions would harden this. Maintaining two separate stacks (MkDocs for the user guide and Jekyll for the main site) also adds ongoing overhead worth periodically reviewing. +The KubeVirt user guide is on a solid maintenance footing. It is built with +MkDocs and the Material for MkDocs theme, supplemented by the `awesome-nav`, +`redirects`, and `html-proofer` plugins. Although this differs from the Hugo and +Docsy stack, MkDocs Material is a mature and widely adopted documentation +toolchain used across the CNCF and Kubernetes ecosystems, so maintainers can +rely on strong community support and a steady stream of upstream updates. + +Maintenance responsibility is clearly structured and actively exercised. The +repository uses the Kubernetes-style OWNERS model, defining reviewers and +approvers roles and recording emeritus approvers, which gives maintainers +appropriate permissions to review and merge changes. The commit history reflects +a healthy, cultivated community, with roughly 49 distinct authors in the last +twelve months and a continuous flow of merged pull requests, so the guide is not +dependent on a single maintainer. + +The build and hosting setup is dependable. MkDocs builds this static site +quickly, Netlify produces per-pull-request previews, and the project's +Prow-based CI builds the site as well. The site is served securely: HTTPS +returns a 200 response, and HTTP requests are 301-redirected to HTTPS for both +the user guide path and the apex domain. These are exactly the properties one +wants for low-friction, secure maintenance. + +The main opportunities are around build reproducibility and stack consolidation. +The build installs MkDocs and its plugins without pinned versions (in +`netlify.toml` and the `Makefile`), which risks non-reproducible builds or +breakage when an upstream package changes; pinning versions would harden this. +Maintaining two separate stacks (MkDocs for the user guide and Jekyll for the +main site) also adds ongoing overhead worth periodically reviewing. Rating: 4 - Meets or exceeds standards @@ -1172,49 +1827,120 @@ Rating: 4 - Meets or exceeds standards #### Usability, accessibility and devices -- Increase color contrast for the brand teal primary color (`#0db2b6` in `docs/stylesheets/extra.css`) so that white header text meets the WCAG AA contrast ratio of at least 4.5:1 for normal text, either by darkening the teal or by adjusting the text color placed on it. -- Adjust the body link color (currently the primary color darkened with `filter: brightness(80%)`) so that links reach at least 4.5:1 contrast against the page background, rather than the roughly 3.96:1 they achieve today. -- Verify all contrast changes in both the light (`default`) and dark (`slate`) schemes, checking header text, links, navigation section labels, and code blocks. -- Add a-ln automated accessibility and contrast check to the site build (for example, a Lighthouse or axe-based check) so contrast regressions are caught before publishing. -- Continue requiring descriptive, non-empty alt text on all images and maintain correct heading order in new pages, so screen-reader and text-to-speech users keep getting a good experience. -- Preserve the existing strengths, keeping the responsive viewport, mobile drawer navigation, site search, in-page table of contents, skip-to-content link, and ARIA labels intact as the theme is upgraded. +- Increase color contrast for the brand teal primary color (`#0db2b6` in + `docs/stylesheets/extra.css`) so that white header text meets the WCAG AA + contrast ratio of at least 4.5:1 for normal text, either by darkening the teal + or by adjusting the text color placed on it. +- Adjust the body link color (currently the primary color darkened with + `filter: brightness(80%)`) so that links reach at least 4.5:1 contrast against + the page background, rather than the roughly 3.96:1 they achieve today. +- Verify all contrast changes in both the light (`default`) and dark (`slate`) + schemes, checking header text, links, navigation section labels, and code + blocks. +- Add a-ln automated accessibility and contrast check to the site build (for + example, a Lighthouse or axe-based check) so contrast regressions are caught + before publishing. +- Continue requiring descriptive, non-empty alt text on all images and maintain + correct heading order in new pages, so screen-reader and text-to-speech users + keep getting a good experience. +- Preserve the existing strengths, keeping the responsive viewport, mobile + drawer navigation, site search, in-page table of contents, skip-to-content + link, and ARIA labels intact as the theme is upgraded. #### Branding and design -- Document a small set of shared brand values in the repository, such as the brand hex colors (`#0db2b6` and `#006166`), the logo and favicon files, and the chosen fonts, so the branding is defined in one place rather than implied by the theme configuration. -- Align the user guide's look and feel more closely with the main `kubevirt.io` website by agreeing on a shared logo, color family, and typography across both properties, so readers experience a consistent brand as they move between the sites. -- Verify the customized link styling (`filter: brightness(80%)` in `docs/stylesheets/extra.css`) against accessibility contrast targets in both the light and dark schemes, and adjust or remove the filter if it reduces contrast below recommended levels. -- Keep relying on the Material theme's default Roboto and Roboto Mono typography, and if a custom font is ever introduced, apply it through the theme configuration so it remains consistent across all pages. -- Confirm the teal palette renders correctly in the dark (`slate`) scheme, checking that logo, links, code blocks, and navigation labels retain sufficient contrast and remain on-brand. -- Continue defining brand colors through theme-level variables in `extra.css` rather than per-page styling, so the brand stays consistent as new pages are added. +- Document a small set of shared brand values in the repository, such as the + brand hex colors (`#0db2b6` and `#006166`), the logo and favicon files, and + the chosen fonts, so the branding is defined in one place rather than implied + by the theme configuration. +- Align the user guide's look and feel more closely with the main `kubevirt.io` + website by agreeing on a shared logo, color family, and typography across both + properties, so readers experience a consistent brand as they move between the + sites. +- Verify the customized link styling (`filter: brightness(80%)` in + `docs/stylesheets/extra.css`) against accessibility contrast targets in both + the light and dark schemes, and adjust or remove the filter if it reduces + contrast below recommended levels. +- Keep relying on the Material theme's default Roboto and Roboto Mono + typography, and if a custom font is ever introduced, apply it through the + theme configuration so it remains consistent across all pages. +- Confirm the teal palette renders correctly in the dark (`slate`) scheme, + checking that logo, links, code blocks, and navigation labels retain + sufficient contrast and remain on-brand. +- Continue defining brand colors through theme-level variables in `extra.css` + rather than per-page styling, so the brand stays consistent as new pages are + added. #### Case studies/social proof -- Publish a small set of narrative case studies on the project website that describe how specific organizations adopted KubeVirt, the problems they solved, and the outcomes they achieved, going beyond the existing adopter logo walls. -- Gather and display user testimonials, for example short quotes from adopting organizations, to complement the logo walls with real-world perspectives on the project's value. -- Link the user guide to the project's adoption and community content so readers can discover it, for example by adding references to the blog, the community talks and videos page, and the adopters logo wall from the user guide landing page. -- Add a "Community" or "Adopters" entry to the user guide that points to the case studies, testimonials, and logo wall once they exist, giving documentation readers a clear path to social proof. -- Continue maintaining the active blog and the curated talk playlists (Talks, Demos, Interviews, and KubeVirt Summit), and consider surfacing the most relevant posts or talks from within related documentation pages. -- Where a case study or talk illustrates a documented feature, cross-link it from the corresponding user guide page so readers can see the feature applied in practice. +- Publish a small set of narrative case studies on the project website that + describe how specific organizations adopted KubeVirt, the problems they + solved, and the outcomes they achieved, going beyond the existing adopter logo + walls. +- Gather and display user testimonials, for example short quotes from adopting + organizations, to complement the logo walls with real-world perspectives on + the project's value. +- Link the user guide to the project's adoption and community content so readers + can discover it, for example by adding references to the blog, the community + talks and videos page, and the adopters logo wall from the user guide landing + page. +- Add a "Community" or "Adopters" entry to the user guide that points to the + case studies, testimonials, and logo wall once they exist, giving + documentation readers a clear path to social proof. +- Continue maintaining the active blog and the curated talk playlists (Talks, + Demos, Interviews, and KubeVirt Summit), and consider surfacing the most + relevant posts or talks from within related documentation pages. +- Where a case study or talk illustrates a documented feature, cross-link it + from the corresponding user guide page so readers can see the feature applied + in practice. #### SEO, Analytics and site-local search -- Decide whether to adopt analytics for the documentation, and if so, choose either a GA4 property or a privacy-respecting alternative that aligns with the project's privacy policy, so maintainers gain visibility into traffic and popular content. -- If analytics is adopted, enable it only on the production deploy and keep it disabled for pull-request previews and non-default branch builds, configuring it through the Material theme's analytics integration rather than per page. -- If analytics is adopted, ensure Page-not-found (404) reporting is available so broken inbound links can be identified and fixed over time. -- Document the custodians of any analytics or search accounts (for example, who owns the analytics property) in the repository, so ownership remains clear as maintainers change. -- Make the preview `noindex` behavior an explicit project setting (for example, an `X-Robots-Tag` header for Netlify preview and branch deploys) rather than relying solely on the Netlify default, so indexing rules are intentional and documented. -- Fix the double slash in the `robots.txt` Sitemap URL (`https://kubevirt.io//sitemap.xml`) so it points to a single canonical sitemap location. -- Keep the MkDocs `search` plugin enabled and continue to benefit from the Material theme's intra-site search, periodically reviewing the search separator configuration as content grows. +- Decide whether to adopt analytics for the documentation, and if so, choose + either a GA4 property or a privacy-respecting alternative that aligns with the + project's privacy policy, so maintainers gain visibility into traffic and + popular content. +- If analytics is adopted, enable it only on the production deploy and keep it + disabled for pull-request previews and non-default branch builds, configuring + it through the Material theme's analytics integration rather than per page. +- If analytics is adopted, ensure Page-not-found (404) reporting is available so + broken inbound links can be identified and fixed over time. +- Document the custodians of any analytics or search accounts (for example, who + owns the analytics property) in the repository, so ownership remains clear as + maintainers change. +- Make the preview `noindex` behavior an explicit project setting (for example, + an `X-Robots-Tag` header for Netlify preview and branch deploys) rather than + relying solely on the Netlify default, so indexing rules are intentional and + documented. +- Fix the double slash in the `robots.txt` Sitemap URL + (`https://kubevirt.io//sitemap.xml`) so it points to a single canonical + sitemap location. +- Keep the MkDocs `search` plugin enabled and continue to benefit from the + Material theme's intra-site search, periodically reviewing the search + separator configuration as content grows. #### Maintenance planning -- Pin the versions of MkDocs and its plugins (`mkdocs`, `mkdocs-material`, `mkdocs-awesome-nav`, `mkdocs-redirects`, and `mkdocs-html-proofer-plugin`) in the build definitions, for example via a `requirements.txt`, so that Netlify and Prow builds are reproducible and resistant to breaking upstream changes. -- Keep the pinned dependency versions current through a regular update cadence, ideally automated (for example with Dependabot or Renovate), so the guide continues to benefit from the actively maintained MkDocs Material toolchain. -- Continue cultivating maintainers through the OWNERS model, and periodically review the reviewers and approvers lists to confirm they reflect currently active contributors and that coverage is not concentrated in too few people. -- Preserve the existing HTTPS posture, keeping the site accessible over HTTPS and retaining the HTTP-to-HTTPS redirects for both the user guide path and the apex domain. -- Periodically review the overhead of maintaining two separate stacks (MkDocs for the user guide and Jekyll for the main `kubevirt.io` site), and consider whether consolidation or closer alignment would reduce long-term maintenance effort. -- Document the local and CI build process (build commands, dependencies, and preview workflow) in a contributor-facing location so new maintainers can reproduce and troubleshoot builds easily. +- Pin the versions of MkDocs and its plugins (`mkdocs`, `mkdocs-material`, + `mkdocs-awesome-nav`, `mkdocs-redirects`, and `mkdocs-html-proofer-plugin`) in + the build definitions, for example via a `requirements.txt`, so that Netlify + and Prow builds are reproducible and resistant to breaking upstream changes. +- Keep the pinned dependency versions current through a regular update cadence, + ideally automated (for example with Dependabot or Renovate), so the guide + continues to benefit from the actively maintained MkDocs Material toolchain. +- Continue cultivating maintainers through the OWNERS model, and periodically + review the reviewers and approvers lists to confirm they reflect currently + active contributors and that coverage is not concentrated in too few people. +- Preserve the existing HTTPS posture, keeping the site accessible over HTTPS + and retaining the HTTP-to-HTTPS redirects for both the user guide path and the + apex domain. +- Periodically review the overhead of maintaining two separate stacks (MkDocs + for the user guide and Jekyll for the main `kubevirt.io` site), and consider + whether consolidation or closer alignment would reduce long-term maintenance + effort. +- Document the local and CI build process (build commands, dependencies, and + preview workflow) in a contributor-facing location so new maintainers can + reproduce and troubleshoot builds easily. #### Other From 72f180d2613957ab9027eebf6d717b9194bcd820 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Thu, 30 Jul 2026 10:08:13 -0700 Subject: [PATCH 30/49] section comments updates Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/analysis.md | 221 ++++++++++++++++++++++++----- 1 file changed, 183 insertions(+), 38 deletions(-) diff --git a/analyses/2026/kubevirt/analysis.md b/analyses/2026/kubevirt/analysis.md index 0b2fdc1b..ef484372 100644 --- a/analyses/2026/kubevirt/analysis.md +++ b/analyses/2026/kubevirt/analysis.md @@ -118,19 +118,70 @@ KubeVirt is an **incubating** project of CNCF. This means that the project should be developing professional-quality documentation alongside the project code. -| Criterion | Rating (1-5) | -| ---------------------------------------- | ------------ | -| Information architecture | 4 | -| New user content | 3 | -| Content maintainability & site mechanics | 2 | -| Content creation processes | 3 | -| Inclusive language | 3 | +| Criterion | Rating (1-5) | +| -------------------------- | ------------------------------ | +| Information architecture | 4 - Meets or exceeds standards | +| New user content | 3 - Meets standards | +| Content maintainability | 3 - Meets standards | +| Content creation processes | 4 - Meets or exceeds standards | +| Inclusive language | 3 - Meets standards | ### Comments The following sections contain assessments of each element of the Project Documentation rubric. +#### Overall (AI) + +The KubeVirt user guide's project documentation is in good shape, rating between +"meets standards" and "meets or exceeds standards" across the five criteria. Its +structural foundations are strong: content is organized into clear +domains—cluster administration, user workloads, compute, network, and +storage—with explicit navigation ordering, and it layers conceptual, task, and +reference material effectively. The site is built on a maintainable MkDocs and +`mkdocs-material` stack with all content in Markdown, working search, and a +redirects map that prevents link rot. Contribution is well signposted through +`docs/contributing.md` and Kubernetes-style OWNERS files enforced by Prow, and +the guide is already clean on inclusive naming, with no non-recommended terms +coined by the project. No reorganization is required; the recommended +improvements are additive. + +The most significant cross-cutting gap is that documentation is decoupled from +KubeVirt's release cadence. The site publishes a single "latest" build from +`main` with no versioning tooling (such as `mike`) or version selector, so +readers running an older release cannot find documentation that matches their +deployment. This is compounded on the process side, where nothing requires +user-facing feature changes in `kubevirt/kubevirt` to ship with corresponding +user-guide updates, which risks content drift over time. Adopting MkDocs +versioning and establishing an expectation—such as a release checklist item or a +cross-repository issue link—that features land together with their documentation +would be the highest-impact investment for this section. Kubernetes is a good +model of versioned CNCF documentation. + +A second theme is that users lack clear guided paths into and through the +content. New-user material is fragmented across differently named locations—a +top-level "Quickstarts" entry, an "Installation" page buried under "Cluster +Administration," and "Try it out" and "KubeVirt Labs" sections on the +homepage—none of which is labeled "Getting Started," and the guide leans on +external labs rather than a self-contained, first-VM walkthrough. Similarly, +when a task page falls short, help is scattered across individual feature pages +with no consolidated troubleshooting or FAQ entry point. Consolidating a single +"Getting Started" section, adding an in-guide end-to-end tutorial with an +explicit "Next steps" pointer from installation to first use, and creating a +symptom-based troubleshooting hub would give users a predictable path from setup +through to problem resolution. + +Finally, the guide would benefit from light language and consistency polish +backed by automation. Although naming is inclusive, minimizing words such as +"simple" and "easy" appear roughly 80 times and can discourage readers who find +a task harder than described; replacing them with concrete, factual descriptions +would improve tone without losing information. Normalizing the minority of +noun-based task headings into goal-oriented verb phrases would further improve +scanning and consistency. Extending the existing spell checks—or adding a +dedicated inclusive-language linter or a Vale style rule in CI—would keep both +language and future contributions consistent, building on the solid foundation +this section already demonstrates. + #### Overall (Author) The KubeVirt has a well-thought out structure that can accommodate improvements @@ -861,26 +912,64 @@ KubeVirt is an **incubating** project of CNCF. This means that the project should be developing professional-quality documentation alongside the project code. -| Criterion | [Rating (1-5)] | -| ----------------------------------------- | -------------- | -| Communication methods documented | [rating (1-5)] | -| Beginner friendly issue backlog | [rating (1-5)] | -| “New contributor” getting started content | [rating (1-5)] | -| Project governance documentation | [rating (1-5)] | +| Criterion | Rating (1-5) | +| ----------------------------------------- | ------------------------------ | +| Communication methods documented | 3 - Meets standards | +| Beginner friendly issue backlog | 3 - Meets standards | +| "New contributor" getting started content | 4 - Meets or exceeds standards | +| Project governance documentation | 4 - Meets or exceeds standards | ### Comments -> AUTHOR NOTE: make any overall comments about the Contributor Documentation -> here. +KubeVirt's contributor documentation is in good overall shape, rating between +"meets standards" and "meets or exceeds standards" across the four criteria. Its +strongest assets are a well-organized onboarding path and mature governance: the +user guide's Contributing page acts as a single, canonical entry point covering +prerequisites, a clear "Your first contribution" section, and separate tracks +for documentation and code, while the `kubevirt/community` repository provides +comprehensive, CNCF-aligned governance through `GOVERNANCE.md`, a maintained +`MAINTAINERS.md`, and a well-defined contributor ladder. The essential +communication channels—Slack, the kubevirt-dev mailing list, and the issue +tracker—are documented and correctly linked. No structural overhaul is needed; +the recommended improvements are additive. + +The highest-impact gap is that the beginner-friendly issue backlog is +effectively empty, and this weakness undermines the otherwise excellent +onboarding content. Both the beginner-backlog and new-contributor analyses found +that the Contributing page tells newcomers to look for `good-first-issue` items, +yet at review time there were no open beginner issues in either the user-guide +or core repository, so a motivated first-timer who follows the documentation +reaches a dead end. This is compounded by a fixable labeling inconsistency—the +team applies the hyphenated `good-first-issue` label while GitHub's native +"Contribute" experience and discovery tooling key off the standard spaced +`good first issue`, hiding the project's real beginner issues. Curating a small +pool of triaged beginner issues and consolidating on the standard label would +let the strong onboarding path deliver on its promise. + +A second cross-cutting theme is discoverability from within the user guide +itself. Governance is reachable only through a single "Important community +resources" list on the Contributing page, with no dedicated community or +governance entry in the site navigation; project meetings are absent from the +guide entirely and documented only on the external community page; and the +"Getting help" section is a thin, inconsistent list that omits the community +page and the `#kubevirt-dev` Slack channel that appear elsewhere. Because so +much contributor-facing information lives outside the guide or is scattered +within it, a reader who stays on the documentation site can miss where to ask +questions, when meetings happen, or how the project is governed. + +Addressing these two themes together would move the section from good to strong. +Consolidating the communication channels, meeting cadence and calendar, and +governance pointers into a single, clearly labeled community landing area—each +channel given a one-line description of its purpose—would resolve the +discoverability gaps across three of the four areas at once. Pairing that with a +light triage pass that keeps a curated set of beginner issues open would close +the backlog gap. The underlying content is comprehensive and current; the +remaining work is largely about surfacing and maintaining it where contributors +are already reading. The following sections contain brief assessments of each element of the Contributor Documentation rubric. -> AUTHOR NOTE: For each heading below, discuss how well the in-scope items meet -> these criteria. Keep in mind that much of the contributor documentation might -> be contained in the documentation repository. (Criteria are copied from -> criteria.md) - #### Communication methods documented One of the easiest ways to attract new contributors is making sure they know how @@ -1319,21 +1408,24 @@ Rating: 4 - Meets or exceeds standards ## Website and infrastructure -> AUTHOR NOTE: Pick the CNCF maturity level of the project: - KubeVirt is an **incubating** project of CNCF. This means that the project should be developing professional-quality documentation alongside the project code. +| Criterion | Rating (1-5) | +| ------------------------------------- | ------------------------------ | +| Usability, accessibility, and design | 4 - Meets or exceeds standards | +| Branding and design | 4 - Meets or exceeds standards | +| Case studies/social proof | 3 - Meets standards | +| SEO, Analytics, and site-local search | 2 - Needs improvement | +| Maintenance planning | 4 - Meets or exceeds standards | + +Other metrics TBD: + | Criterion | [Rating (1-5)] | | ------------------------------------------- | -------------- | | Single-source for all files | [rating (1-5)] | | Meets min website req. (for maturity level) | [rating (1-5)] | -| Usability, accessibility, and design | [rating (1-5)] | -| Branding and design | [rating (1-5)] | -| Case studies/social proof | [rating (1-5)] | -| SEO, Analytics, and site-local search | [rating (1-5)] | -| Maintenance planning | [rating (1-5)] | | A11y plan & implementation | [rating (1-5)] | | Mobile-first plan & impl. | [rating (1-5)] | | HTTPS access & HTTP redirect | [rating (1-5)] | @@ -1344,19 +1436,62 @@ code. ### Comments -> AUTHOR NOTE: make any overall comments about the Website and documentation -> infrastructure here. +KubeVirt's website and infrastructure are on a strong footing overall, rating +"meets or exceeds standards" in three of the five criteria. The Material for +MkDocs foundation delivers a responsive, mobile-friendly site with clean +typography, semantic landmarks, descriptive ARIA labels, a "Skip to content" +link, and complete image alt text, so usability and accessibility are strong at +the structural level. The brand is clear and consistently applied, with the teal +palette and logo defined at the theme level rather than per author. Maintenance +is dependable and not dependent on a single person: the repository uses the +Kubernetes-style OWNERS model, draws on roughly 49 distinct authors over the +last year, builds quickly through Netlify previews and Prow CI, and serves +securely over HTTPS. The recommended improvements are mostly targeted fixes +rather than structural changes. + +The highest-impact gap—and the section's lowest rating—is the complete absence +of analytics. Neither the user guide nor the main site includes any analytics +tags, so there is no visibility into traffic, popular pages, search terms, or +broken inbound links, and 404 reports cannot be generated to guide maintenance. +This absence is consistent with the project's privacy posture, which is a +legitimate trade-off, but if the project wants data to drive documentation +improvements, adopting a privacy-respecting option (GA4 or an alternative), +enabling it only on the production deploy, and documenting the account +custodians would close an important blind spot. Two smaller SEO fixes accompany +it: make the preview `noindex` behavior an explicit project setting rather than +relying on the Netlify default, and correct the double slash in the `robots.txt` +sitemap URL. + +A cross-cutting accessibility theme surfaces in both the usability and branding +analyses: color contrast on the brand teal. The primary teal (`#0db2b6` in +`docs/stylesheets/extra.css`) yields only about 2.6:1 against white header +text—below the WCAG AA thresholds of 4.5:1 for normal text and 3:1 for large +text—and body links darkened with `filter: brightness(80%)` reach only about +3.96:1. Because this styling is defined once at the theme level, darkening the +primary teal (or the text on it) and re-checking links in both the light and +dark schemes is a small, high-value change that affects color-impaired and +low-vision readers most. Adding an automated contrast and accessibility check to +the build would keep the fix from regressing. + +Two further themes concern connecting the guide to the wider project and +hardening the stack. The strong adoption and community content—an active blog, +curated talk playlists, and an extensive adopter logo wall—lives on +`kubevirt.io` and is not linked from the user guide at all, so readers have no +easy path to this social proof; the guide would also benefit from a few +narrative case studies or testimonials that explain how and why organizations +use KubeVirt. This mirrors a broader cross-property gap, since the MkDocs guide +and the separate main site share a logo and color family but not an identical +look and feel. Documenting a small set of shared brand values and adding +targeted links (for example, a "Community" or "Adopters" entry) would align the +two properties and surface existing content. On the infrastructure side, the +build installs MkDocs and its plugins without pinned versions in `netlify.toml` +and the `Makefile`, which risks non-reproducible builds; pinning versions and +periodically reviewing the overhead of maintaining two separate stacks would +sustain the section's already solid maintenance posture. The following sections contain brief assessments of each element of the Website and documentation infrastructure rubric. -> AUTHOR NOTE: for each heading below, discuss how well the in-scope items meet -> these criteria. Keep in mind that much of the website infrastructure criteria -> depend on the tools (static site generator, website framework and hosting, -> analytics tools, etc.) and processes (project CI, release procedures, -> governance, etc.) used to produce the documentation. (Criteria are copied from -> criteria.md) - #### Single-source requirement Source files for _all website pages_ should reside in a single repo. Among other @@ -1571,8 +1706,18 @@ organizations using it. We evaluate on the following: -fic organizations adopted and benefited from KubeVirt. The user guide itself -contains only technical documentation and does not link to any case studies. +- Are there case studies available for the project and are they documented on + the website? + + There are case studies available for KubeVirt, but they are not documented on + the project website. The kubevirt.io navigation includes Blogs, Videos, + Gallery, Docs, Labs, and Community, but it has no dedicated case studies + section. + + Case studies live on external sites instead, such as the CNCF Swisscom case + study and third-party write-ups like Puzzle ITC's continuous integration + story. Because these are not linked from or hosted on kubevirt.io, a visitor + cannot find them from the project website. - Are there user testimonials available? From 5fadbc8c706193a63c48c1dce61fd8a353dc59c9 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Fri, 31 Jul 2026 10:34:30 -0700 Subject: [PATCH 31/49] minor edit to build Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/analysis.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/analyses/2026/kubevirt/analysis.md b/analyses/2026/kubevirt/analysis.md index ef484372..bac3dd79 100644 --- a/analyses/2026/kubevirt/analysis.md +++ b/analyses/2026/kubevirt/analysis.md @@ -131,7 +131,7 @@ code. The following sections contain assessments of each element of the Project Documentation rubric. -#### Overall (AI) +#### Overall The KubeVirt user guide's project documentation is in good shape, rating between "meets standards" and "meets or exceeds standards" across the five criteria. Its @@ -767,7 +767,7 @@ Rating: 3 - Meets standards ### Recommendations -#### Overall - Author +#### Overall (Author) The AI results capture my recommendations except for the following pressing needs I see as a novice user: From 1ff2e3980d759931a0b2b3f04d8e127fd4e2c234 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Mon, 21 Sep 2026 10:44:05 -0700 Subject: [PATCH 32/49] Update using Claude Fable 5.1 Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/analysis.md | 545 ++++++++++++----------------- 1 file changed, 227 insertions(+), 318 deletions(-) diff --git a/analyses/2026/kubevirt/analysis.md b/analyses/2026/kubevirt/analysis.md index bac3dd79..e8c73536 100644 --- a/analyses/2026/kubevirt/analysis.md +++ b/analyses/2026/kubevirt/analysis.md @@ -290,160 +290,201 @@ Virtualization Debugging: The overall structure (pages/subpages/sections/subsections) of your project documentation. We evaluate on the following: -- Is there high level conceptual/"About" content? Is the documentation feature - complete? (i.e., each product feature is documented) - - Yes. The guide provides high-level conceptual content. The - [Architecture](https://kubevirt.io/user-guide/architecture/) page gives a - technical and conceptual overview of the KubeVirt components, the - service-oriented design, and the layered virtualization stack, and the Welcome - page introduces each major section of the guide. - - The documentation is broadly feature complete. Major product areas each have - dedicated sections: cluster administration, user workloads, compute, network, - and storage. Individual features such as live migration, CPU and memory - hotplug, hugepages, NUMA, instance types and preferences, snapshots, volume - export, and network binding plugins each have their own pages. Coverage is - wide enough that most shipped features have at least a conceptual description. - -- Are there step-by-step instructions (tasks, tutorials) documented for - features? - - Yes. Most feature pages include step-by-step instructions with copy-paste - capable shell and YAML examples. For example, the - [live migration](https://kubevirt.io/user-guide/compute/live_migration/) page - walks through enabling the feature, initiating and canceling a migration, and - configuring a dedicated migration network, and the - [creating VirtualMachines](https://kubevirt.io/user-guide/user_workloads/creating_vms/) - page shows how to build manifests with `virtctl`. - - For tutorials, the guide links out to external interactive labs and - quickstarts (Killercoda, minikube, kind, and cloud providers) from both the - Welcome and Quickstarts pages rather than hosting long-form tutorials inline. - This keeps hands-on learning paths available, though they live outside the - user guide itself. - -- Are there any key features which are documented but missing task - documentation? - - Some pages lean conceptual or reference-oriented and would benefit from added - task steps, but there are no major features that are described without any - actionable guidance. A few areas mix concept and procedure heavily (for - example, migration strategies and some networking topics), where a reader must - extract the steps from surrounding explanation. - - The most common gap is depth rather than absence: certain advanced features - document the "what" and configuration fields well but provide fewer - end-to-end, goal-oriented walkthroughs. Reviewers should confirm that newer - features listed in recent release notes each have a corresponding task page. - -- Is the "happy path"/most common use case documented? Does task and tutorial - content demonstrate atomicity and isolation of concerns? (Are tasks clearly - named according to user goals?) - - Yes. The happy path is documented. A new user can follow installation, then - create and access a virtual machine, which covers the most common use case. - The quickstarts and labs reinforce this path for first-time users. - - Task content generally demonstrates atomicity and isolation of concerns, and - headings are largely named according to user goals using verb or gerund - phrases, such as "Creating VirtualMachines on a cluster", "Enabling the - live-migration support", "Initiate live migration", and "Configuring a - migration network on a cluster". This makes individual tasks easy to scan and - follow. A minority of headings are noun-based topic labels rather than goal - phrases, so naming is strong but not fully consistent. - -- If the documentation does not suffice, is there a clear escalation path for +- Is there high level conceptual content? + + Yes. The Architecture page explains the KubeVirt stack, the choreography + pattern between the API server, controllers, and node daemons, and the roles + of virt-api, virt-controller, virt-handler, and virt-launcher. The Welcome + page introduces each top-level section with a one-line summary, and the Basic + use page frames KubeVirt as an extension of the Kubernetes API. + + Conceptual content thins out beyond the top level. Most feature pages, such as + Filesystems, Disks and Volumes or Interfaces and Networks, open directly with + configuration options rather than a short explanation of when and why to use + the feature. New users get the big picture but must infer the purpose of + individual features from their YAML examples. + +- Is the documentation feature complete? + + Largely yes. The guide has 97 pages covering installation, VM lifecycle, + instance types, virtctl, startup scripts, monitoring, storage (CDI, snapshots, + clone, export, hotplug, volume migration), networking (bindings, hotplug, + Istio, network policy), compute (CPU and memory hotplug, hugepages, NUMA, + dedicated CPUs, host devices, DRA GPUs), and cluster administration (feature + gates, RBAC, node maintenance, migration policies, Arm64 support). New v1.8 + features such as container path volumes, decentralized live migration, and CSI + overlay already have pages. + + A few gaps remain. Changed Block Tracking (CBT) backups, the rebootPolicy + field, and the virt-template commands introduced in v1.8 appear in the release + notes but not yet as documentation pages. There is also no page dedicated to + backup and restore workflows, even though snapshots, exports, and hooks are + individually documented. + +- Are there step-by-step instructions documented for features in tasks and + tutorials? + + Yes, most feature pages include copy-and-paste `kubectl` and `virtctl` + commands with YAML manifests. Pages such as Live Migration, Creating + VirtualMachines by using virtctl, Installation, and Hotplug Volumes walk + through enable, apply, verify, and cancel steps in order. The Welcome page + also links to external Killercoda scenarios, minikube and kind quickstarts, + and hands-on labs hosted on kubevirt.io. + + The instructions are presented as reference-style sections rather than + numbered procedures, so the boundary between "what this option means" and "do + this next" is often unclear. There are no true tutorials in the guide itself; + the tutorial role is delegated to the external quickstarts and labs. + +- Are there any key features that are documented but missing task documentation? + + Yes. Filesystems, Disks and Volumes describes every disk and volume type at + length (over 2,000 lines) but does not provide a task for the common goal of + "attach persistent storage to a VM and boot from it." Interfaces and Networks + similarly explains each binding and network type without a task for "connect a + VM to a secondary network." The Debug page covers log verbosity and profiling + but does not offer a task-oriented "my VM will not start" walkthrough. + + The Windows content is another example. Windows virtio drivers, legacy + Windows, and sysprep are documented as options, but there is no end-to-end + task for creating a Windows VM. + +- Is the "happy path" (most common use case) documented? + + Partially. The Installation page gets a cluster to a running KubeVirt, and the + Lifecycle and Creating VirtualMachines pages show how to create, start, stop, + and access a VM. The Creating VirtualMachines by using virtctl page is a + strong example because it shows the fastest route from nothing to a running VM + with a cloud image and SSH access. + + However, the happy path is split across several pages in different sections, + and the in-guide entry point is a Quickstarts page that only contains external + links. A reader who lands on the user guide without going through kubevirt.io + first has no single page that strings install, create, access, and delete + together. + +- Are tasks clearly named according to user goals? + + Mixed. Some page titles are goal-oriented, such as Creating VirtualMachines by + using virtctl, Download and Install the virtctl Command Line Interface, and + Activating and deactivating feature gates. Section headings inside pages are + also often action-oriented, for example "Initiate live migration" and + "Canceling a live migration." + + Most page titles are named after the feature or API object rather than the + user goal: Filesystems, Disks and Volumes; Presets; Pool; ReplicaSet; VSOCK; + KSM; Clone API; Export API. A user who wants to "copy a VM" or "back up a VM" + must already know that the relevant feature is called the Clone API or Export + API. + +- If the documentation doesn't suffice, is there a clear escalation path for users needing more help? (FAQ, Troubleshooting) - Yes. The Welcome page provides a "Getting help" section that links to filing - bugs on GitHub, the kubevirt-dev mailing list, and the community Slack - channel, giving users a clear escalation path. + Partially. The Welcome page lists how to file a bug, the mailing list, and the + Slack channel. The Virtualization Debugging section provides deep-dive guides + for logs, privileged node debugging, virsh commands, and attaching strace or + gdb to QEMU. - There is also a dedicated Virtualization Debugging section covering log - verbosity, privileged node debugging, virsh commands, and running QEMU under - strace or gdb, and several feature pages include debugging notes. However, - there is no single, consolidated FAQ or troubleshooting landing page, so - common problems and their fixes are spread across individual pages rather than - centralized. + There is no FAQ and no troubleshooting page organized by symptom. Existing + troubleshooting content is scattered in "Limitations and known issues" + subsections on individual feature pages. The Debugging section is written for + developers debugging the virtualization stack rather than for users whose VM + failed to schedule, boot, or migrate. -- If the product exposes an API, is there a complete reference? +- If the product exposes an API, is there a complete reference that includes + documented CLIs as applicable? - Yes. KubeVirt exposes a Kubernetes-style API, and the Welcome page links to - the generated API reference at kubevirt.io/api-reference, which provides a - complete, versioned reference for the custom resources and fields. + Yes for the API, no for the CLI. The Welcome page and many feature pages link + to the generated API reference at kubevirt.io/api-reference, which documents + every field of the KubeVirt custom resources. Several links point to the + `master` version rather than a release-specific version, and one page links to + the very old `v0.13.2` reference. - Because the reference is generated from source and hosted separately from the - user guide, it stays current with releases but is one click removed from the - task content. Cross-linking specific fields from task pages to the reference - would tighten the connection between instructions and reference material. + The `virtctl` CLI has no reference page. The virtctl page only covers download + and installation, and individual subcommands are documented piecemeal on the + feature pages that use them (create, migrate, ssh, vnc, and so on). There is + no single list of virtctl commands and flags. - Is content up to date and accurate? - Yes. The content is current. The release notes document releases through - v1.8.0 (released March 2026, built for Kubernetes v1.35), and feature pages - reference current resources, feature gates, and `virtctl` subcommands - consistent with recent releases. - - Accuracy appears high overall, with concrete command output and manifests - shown inline. As with any fast-moving project, reviewers should periodically - verify that examples and feature-gate names match the latest release, since - some pages describe features that graduate through alpha, beta, and GA over - time. - -- Restructure needed? - - False. A restructure of the content is not needed. The information - architecture is sound: content is organized into clear conceptual, task, and - reference layers, navigation order is deliberately controlled per section, and - features are grouped logically by domain (cluster administration, user - workloads, compute, network, storage). Improvements should focus on - incremental additions — a consolidated troubleshooting/FAQ entry point, - tighter cross-linking to the API reference, and more consistent goal-oriented - headings — rather than reorganizing the existing structure. + Mostly. Release notes are current through v1.8.0, feature pages record the + KubeVirt version in which a feature became alpha, beta, or generally + available, and new features such as DRA GPUs and decentralized live migration + are documented. The Presets page clearly flags that the feature has been + deprecated since v0.57.0. + + Some stale content remains. The Installation page still documents installing + on OKD from the Service Catalog as an APB and on k3OS, both of which are + long-unmaintained paths. Many API reference links point to `master` rather + than the current release. Because feature gate status is tracked per page, + some pages likely describe features as alpha or beta after they have + graduated. + +- Does the documentation need restructuring? + + No major restructuring is needed; the current top-level split into Cluster + Administration, User Workloads, Compute, Network, Storage, and Virtualization + Debugging is sound and was itself the result of a recent reorganization, as + the extensive redirect map in `mkdocs.yml` shows. Navigation order within each + section is deliberately curated through `.nav.yml` files. + + Targeted improvements would help. The User Workloads section mixes + getting-started content (Lifecycle, Basic use, Creating VMs) with advanced + workload controllers (Pool, ReplicaSet, hook sidecars), and would benefit from + a separate Getting Started grouping that contains an in-guide happy-path + tutorial. A user-facing Troubleshooting or FAQ page, a virtctl command + reference, and task-oriented page titles would improve findability without + moving existing content. ##### Comment -The KubeVirt user guide has a solid information architecture. Content is -organized into clear domains — cluster administration, user workloads, compute, -network, and storage — and each section uses an explicit navigation order rather -than alphabetical sorting, so related tasks sit together in a logical reading -sequence. The guide also layers the three information types well: conceptual -material (the Architecture page and per-section overviews), task material -(step-by-step pages with copy-paste capable shell and YAML examples), and -reference material (release notes and the generated API reference). Most task -headings are named after user goals using verb or gerund phrases, such as -"Creating VirtualMachines on a cluster" and "Enabling the live-migration -support," which makes pages easy to scan. - -The most valuable improvement would be a single, consolidated troubleshooting -and FAQ entry point. Today, help is available through the "Getting help" links -and a capable Virtualization Debugging section, but common problems and their -fixes are scattered across individual feature pages. A dedicated troubleshooting -landing page — organized by symptom and linking out to the relevant debugging -topics — would give users a predictable escalation path when a task page alone -does not resolve their issue. The Prometheus documentation -(https://prometheus.io/docs) is a good model here: it keeps concepts, tasks, and -reference clearly separated while still offering obvious paths to deeper help. - -Two smaller refinements would tighten the architecture further. First, tutorials -currently live outside the guide as external labs and quickstarts; surfacing an -explicit, in-guide learning path (or at least a clearly labeled "Tutorials" -grouping that frames those external resources) would help new users find -hands-on content without leaving the site. Second, the API reference is complete -but hosted separately and only reachable from the Welcome page — cross-linking -specific custom resources and fields from the task pages that use them would -connect instructions to reference material more directly. Normalizing the -minority of noun-based headings into goal-oriented verb phrases would also -improve scanning and consistency. - -Restructure needed: False. The existing structure is sound and does not require -reorganization. The recommended changes are incremental additions — a -troubleshooting/FAQ hub, clearer tutorial signposting, tighter cross-linking to -the API reference, and more consistent heading phrasing — that build on the -current architecture rather than replace it. +The KubeVirt user guide is a broad, well-maintained reference for a mature +project. Its top-level structure separates cluster administration, user +workloads, compute, network, storage, and debugging in a way that maps to real +roles and concerns, and the content within each section is deliberately ordered +rather than alphabetized. A reader who already knows the name of a KubeVirt +feature can almost always find a page for it, and that page will typically +include working YAML and command examples. + +The guide is less effective for readers who arrive with a goal rather than a +feature name. It is organized as a catalog of features and API objects, with few +pages that lead a user from a goal ("run my first VM," "give my VM persistent +storage," "figure out why my VM will not start") to the sequence of features +that accomplishes it. Adding a small task and troubleshooting layer on top of +the existing reference content, in the spirit of the Prometheus documentation's +separation of concepts, guides, and reference, would make the guide considerably +more useful without disturbing what already works. + +**Strengths** + +- Coverage is nearly complete, with pages for new v1.8 features already present + and release notes current. +- The Architecture page gives a clear conceptual model of the KubeVirt + components and their choreography. +- Top-level sections and curated `.nav.yml` ordering reflect user roles and a + sensible progression. +- Feature pages record the release in which a feature became alpha, beta, or + generally available, and deprecated features such as Presets are clearly + flagged. +- Recent reorganization was handled carefully, with a comprehensive redirect map + preserving old links. + +**Weaknesses** + +- Page titles are feature names rather than user goals (Clone API, Export API, + Pool, VSOCK), so users must already know the feature to find the task. +- The happy path from install to an accessible VM is spread across multiple + sections, and the in-guide Quickstarts page contains only external links. +- Large reference pages such as Filesystems, Disks and Volumes and Interfaces + and Networks lack a task for their most common use. +- There is no user-facing Troubleshooting or FAQ page; the debugging section + targets stack developers, and known issues are scattered across feature pages. +- The `virtctl` CLI has no consolidated command reference. +- Some content is stale, including the OKD Service Catalog and k3OS installation + paths and API reference links that point to `master` rather than the current + release. -Rating: 4 - Meets or exceeds standards +Rating: 3 - Meets standards #### New user content @@ -802,38 +843,51 @@ needs I see as a novice user: The following recommendations for improving the information architecture of the KubVirt User Guide: -- Add a single, consolidated troubleshooting and FAQ entry point, organized by - symptom, that links out to the relevant pages in the Virtualization Debugging - section and to the scattered debugging notes on individual feature pages. This - gives users a predictable escalation path when a task page alone does not - resolve their issue. -- Preserve the current overall structure rather than reorganizing it. The - domain-based sections (cluster administration, user workloads, compute, - network, storage) and explicit per-section navigation order are sound; focus - effort on incremental additions instead of a restructure. -- Surface an explicit, in-guide learning path for new users. Add a clearly - labeled "Tutorials" grouping that frames the existing external labs and - quickstarts (Killercoda, minikube, kind, cloud providers) so hands-on content - is discoverable without leaving the guide. -- Cross-link the API reference from the task pages that use each resource. Link - specific custom resources and fields (for example, from live migration, - instance types, and storage pages) to their entries at - kubevirt.io/api-reference so instructions connect directly to reference - material. -- Normalize the minority of noun-based topic headings into goal-oriented verb or - gerund phrases, matching the existing style of headings such as "Creating - VirtualMachines on a cluster" and "Enabling the live-migration support." This - improves scanning and consistency across pages. -- Audit task coverage depth against recent release notes. Confirm that each - newer feature (for example, those introduced through v1.8.0) has a - corresponding end-to-end, goal-oriented task page, not just a conceptual or - configuration-field description. -- Separate concept from procedure on pages that currently interleave them, such - as the migration strategies and some networking topics, so readers can extract - the steps without reading through surrounding explanation. -- Periodically verify that inline examples, command output, and feature-gate - names match the latest release, since features graduate through alpha, beta, - and GA over time and can drift from the documented behavior. +- Add a Getting Started grouping at the top of the User Workloads section that + contains a single end-to-end tutorial: install KubeVirt, install `virtctl`, + create a VM from a cloud image, connect over SSH or console, and stop and + delete the VM. Move Basic use, Lifecycle, Creating VirtualMachines by using + virtctl, and the virtctl installation page into this grouping so the happy + path is in one place. +- Replace the external-links-only Quickstarts page with a short in-guide + quickstart, and keep the Killercoda, minikube, kind, and cloud-provider links + as a "Try it in a sandbox" list at the bottom. +- Add a user-facing Troubleshooting page, organized by symptom (VM stuck in + Scheduling, VM fails to boot, migration does not complete, cannot reach the VM + over the network), that points to the relevant feature page and to the deeper + Virtualization Debugging guides. Consolidate the scattered "Limitations and + known issues" subsections into it or link to them from it. +- Add a short FAQ page or FAQ section on the Welcome page covering the most + common questions, such as the difference between VM and VMI, whether a UI is + provided, and which Kubernetes versions are supported. +- Add a `virtctl` command reference page that lists every subcommand with a + one-line description and a link to the feature page where it is explained in + depth. Generate it from `virtctl --help` output where possible to keep it + current. +- Add task-oriented "How to" sections at the top of large reference pages. For + example, Filesystems, Disks and Volumes should open with "Attach a persistent + volume to a VM" and "Boot from a PVC," and Interfaces and Networks should open + with "Connect a VM to a secondary network." +- Add an end-to-end task for creating a Windows VM that ties together the virtio + drivers, sysprep, and legacy Windows pages. +- Rename pages toward user goals where practical, for example "Clone a VM" + instead of "Clone API," "Export a VM disk" instead of "Export API," and "Run a + group of identical VMs" for Pool and ReplicaSet. Add redirects in `mkdocs.yml` + for any renamed paths. +- Add a one- or two-sentence "When to use this" introduction to feature pages + that currently open directly with configuration options, so readers can + quickly decide whether the page is relevant. +- Add pages for v1.8 features that appear in the release notes but not in the + guide, including Changed Block Tracking backups, the `rebootPolicy` field, and + the `virtctl` virt-template commands. Consider a single Backup and Restore + page that ties together snapshots, exports, CBT, and hooks. +- Remove or clearly mark as unmaintained the OKD Service Catalog/APB and k3OS + installation paths on the Installation page. +- Update API reference links to point to the current release version rather than + `master`, and fix the outdated `v0.13.2` link on the Windows virtio drivers + page. +- Audit feature pages that record alpha or beta status against the current + feature gate list and update any that have graduated to general availability. #### New user content @@ -2108,148 +2162,3 @@ The numeric rating values used in this document are as follows [Rating (1-5)]: #rating-values [rfc-spec]: https://www.rfc-editor.org/rfc/rfc2119 [website guidelines]: ../../website-guidelines-checklist.md --> - -## Appendices - -### Appendix A - Technical Debt & Content Accuracy - AI - -This Technical Debt & Content Accuracy section is a proposed template change and -was generated by AI. - -> These tasks described for Technical Debt & Content Accuracy are sourced -> directly from kubevirt-analysis.csv. The 266 tasks in that file are intended -> for SME triage and GitHub issue creation. The recommendations below describe -> the patterns and priorities at a level useful for project planning; individual -> task details (node IDs, file paths, specific fixes) are in the CSV. - -This is the most immediately actionable area. No structural change is required — -each item is a concrete, bounded fix in a known file. Taken together, they -represent a systematic erosion of reader trust: a reader who hits a broken link, -an image that won't pull, or a typo in a field name they're about to paste into -production has reason to distrust the entire page. - -#### 1. Replace unofficial and internal dev images in examples - -> Priority: High — 17 occurrences across 11+ files - -Multiple pages embed container image references from internal development -registries or personal/unofficial namespaces that readers cannot pull: - -- `kubevirt/fedora-cloud-container-disk-demo` (user_workloads, network, storage - pages). -- Internal registry paths (confidential_computing.md, host-devices.md, debug - strace pages). -- Unofficial CirrOS images (run_strategies.md, dns.md, service_objects.md). -- Dev sidecar/shim images (launch-qemu-strace.md). - -**Recommendation:** Establish a canonical set of public, stable container images -for documentation examples (e.g., `quay.io/kubevirt/cirros-container-disk-demo`, -official Fedora Cloud images). Run a single sweep replacing all unofficial -references in one PR, then add a CI linting rule (e.g., a grep check on -`registry.k8s.io` or known internal registry host names in Markdown code blocks) -to prevent regressions. - -#### 2. Fix broken and stale links - -> Priority: High — 15 occurrences across 10+ files - -Broken links identified include: - -- Bridge interface link in `compute/live_migration.md` (A05-B06-T01) -- Cross-link to live migration prerequisites from - `cluster_admin/tekton_tasks.md` (A03-B14-T01) -- Stale OKD 3.9 documentation link in `compute/hugepages.md` (A05-B05-T02) -- Feature-gate links using absolute paths in `network/hotplug/interfaces.md` - (A06-B07-T01) and `network/hotplug/nad_reference.md` (A06-B08-T02) -- Stale golang tour URL in `contributing.md` (A09-B01-T01) -- `master`-branch API reference links in `network/interfaces_and_networks.md`, - `storage/disks_and_volumes.md`, and `debug_virt_stack/debug.md` -- Stale cross-link using old `operations/` path in `debug_virt_stack/logging.md` - (A10-B02-T01) -- DNS resolver spec link in `network/dns.md` (A06-B01-T01) - -**Recommendation:** Run `make check_links` on a CI schedule (not just on PR) and -treat link failures as blocking. For the `master`-branch API reference links, -this is the same fix as the broader API link scheme recommendation (see -Information Architecture §2) — a single pass replaces all of them. - -#### 3. Remove or update deprecated API references - -> Priority: High — 6 occurrences across 5 files - -- `spec.running` field references throughout `architecture.md` (A01-T02) — - deprecated in favor of `spec.runStrategy` -- `rbac.authorization.k8s.io/v1beta1` API version in - `user_workloads/accessing_virtual_machines.md` (A04-B06-T01) — removed in - Kubernetes 1.25 -- `--admission-control` flag (replaced by `--enable-admission-plugins`) in - `cluster_admin/api_validation.md` (A03-B05-T01) -- OKD `openshift-ansible` references in `cluster_admin/api_validation.md` - (A03-B05-T02) -- `instancetype.kubevirt.io` API stability status note in - `user_workloads/instancetypes.md` (A04-B15-T01) — may have been promoted to - stable -- Missing deprecation notice on `user_workloads/presets.md` (A04-B18-T01) — - Presets are deprecated in favor of Instancetypes - -**Recommendation:** Each of these is a high-confidence fix that does not require -SME judgment — they are factually wrong or out of date. Batch into a single -"deprecated API cleanup" PR. Add the Presets deprecation admonition immediately -as it actively misleads users into using a feature that is being removed. - -#### 4. Fix user-visible typos in code and API field names - -> Priority: High — 6 occurrences, some in copy-pasteable code - -(see CSV file) - -**Recommendation:** Fix all in a single PR — these are unambiguous one-line -changes. The field name typos are especially damaging because users copy them -verbatim and then debug why their manifest doesn't work. - -#### 5. Remove or archive outdated historical content - -> Priority: High/Medium — 11 occurrences - -Sections describing behavior specific to unsupported releases confuse readers on -current versions and signal that the docs are not maintained: - -- Pre-v0.20.0 and pre-v0.34.2 version-specific notes in - `cluster_admin/installation.md` (A03-B01-T02) -- Pre-v0.34 taint note in `cluster_admin/node_maintenance.md` (A03-B12-T03) -- Pre-v0.56 feature gate enablement note in `compute/live_migration.md` - (A05-B06-T03) -- "Future release" language in `cluster_admin/installation.md` AppArmor section - (A03-B01-T01) — the referenced issue may already be resolved -- "Future release" language in (A05-B14-T01) -- `--delete-local-data` flag (deprecated in kubectl 1.20, removed in 1.27) in - `cluster_admin/node_maintenance.md` (A03-B12-T01) -- OKD Service Catalog APB section in `cluster_admin/installation.md` - (A03-B01-T03) — the Service Catalog was removed from OKD years ago -- Outdated OKD `openshift-ansible` section in `cluster_admin/api_validation.md` - (A03-B05-T02) - -**Recommendation:** SME review required for some (e.g., whether the AppArmor -issue is resolved). Others (pre-v0.20 notes, `--delete-local-data`, OKD APB) can -be deleted without verification — they describe behavior removed in Kubernetes -or OKD versions that are no longer in the support matrix. - -#### 6. Fix the JSON syntax error in the registration example - -> Priority: High — 1 occurrence - -(A06-B04-T01) See sheet for a JSON syntax error in the plugin registration -example. A reader following this example will get an error with no indication -the source is the doc. Fix immediately. - -#### 7. Complete truncated and placeholder release notes entries - -> Priority: High/Medium — 2 occurrences - -- The `KubeVirtVMGuestMemoryPressure` entry in `release_notes.md` is truncated - mid-sentence (A08-B01-T05) -- A placeholder appears in place of a real release note (A08-B01-T06) - -**Recommendation:** These are the most visible credibility issues in the release -notes. Retrieve the complete text from the corresponding GitHub PR or release -tag and complete both entries. From 0884af85e962cbb42f7ea4b7f9262e9d63790c52 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Mon, 21 Sep 2026 10:49:50 -0700 Subject: [PATCH 33/49] removed bolding Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/analysis.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/analyses/2026/kubevirt/analysis.md b/analyses/2026/kubevirt/analysis.md index e8c73536..11f20e04 100644 --- a/analyses/2026/kubevirt/analysis.md +++ b/analyses/2026/kubevirt/analysis.md @@ -455,7 +455,7 @@ the existing reference content, in the spirit of the Prometheus documentation's separation of concepts, guides, and reference, would make the guide considerably more useful without disturbing what already works. -**Strengths** +Strengths - Coverage is nearly complete, with pages for new v1.8 features already present and release notes current. @@ -469,7 +469,7 @@ more useful without disturbing what already works. - Recent reorganization was handled carefully, with a comprehensive redirect map preserving old links. -**Weaknesses** +Weaknesses - Page titles are feature names rather than user goals (Clone API, Export API, Pool, VSOCK), so users must already know the feature to find the task. From 94808584c6d7dd0e39f055e2da47c2849fd36d06 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Thu, 24 Sep 2026 13:43:22 -0700 Subject: [PATCH 34/49] model refining Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/analysis.md | 417 +++++++++++++++-------------- 1 file changed, 221 insertions(+), 196 deletions(-) diff --git a/analyses/2026/kubevirt/analysis.md b/analyses/2026/kubevirt/analysis.md index 11f20e04..013df8a8 100644 --- a/analyses/2026/kubevirt/analysis.md +++ b/analyses/2026/kubevirt/analysis.md @@ -292,197 +292,218 @@ documentation. We evaluate on the following: - Is there high level conceptual content? - Yes. The Architecture page explains the KubeVirt stack, the choreography - pattern between the API server, controllers, and node daemons, and the roles - of virt-api, virt-controller, virt-handler, and virt-launcher. The Welcome - page introduces each top-level section with a one-line summary, and the Basic - use page frames KubeVirt as an extension of the Kubernetes API. - - Conceptual content thins out beyond the top level. Most feature pages, such as - Filesystems, Disks and Volumes or Interfaces and Networks, open directly with - configuration options rather than a short explanation of when and why to use - the feature. New users get the big picture but must infer the purpose of - individual features from their YAML examples. + Yes. The `architecture.md` page explains the stack, the controller and daemon + model, and the relationship between VirtualMachine, VirtualMachineInstance, + and VirtualMachineInstanceReplicaSet resources. The landing page (`index.md`) + describes each top-level section in one line, and pages such as + `user_workloads/lifecycle.md`, `network/interfaces_and_networks.md`, and + `storage/disks_and_volumes.md` open with short conceptual introductions before + describing configuration. + + Conceptual content is concentrated in the architecture page and is thin + elsewhere. The `architecture.md` page relies on an ASCII stack diagram and two + images, and it does not explain the virt-launcher Pod, the virt-api component, + or how a VMI maps onto a Pod, which are concepts that most later pages assume. + The `user_workloads/basic_use.md` page is a twenty-line stub with four + `kubectl` commands and a note that KubeVirt has no UI. - Is the documentation feature complete? - Largely yes. The guide has 97 pages covering installation, VM lifecycle, - instance types, virtctl, startup scripts, monitoring, storage (CDI, snapshots, - clone, export, hotplug, volume migration), networking (bindings, hotplug, - Istio, network policy), compute (CPU and memory hotplug, hugepages, NUMA, - dedicated CPUs, host devices, DRA GPUs), and cluster administration (feature - gates, RBAC, node maintenance, migration policies, Arm64 support). New v1.8 - features such as container path volumes, decentralized live migration, and CSI - overlay already have pages. - - A few gaps remain. Changed Block Tracking (CBT) backups, the rebootPolicy - field, and the virt-template commands introduced in v1.8 appear in the release - notes but not yet as documentation pages. There is also no page dedicated to - backup and restore workflows, even though snapshots, exports, and hooks are - individually documented. + Largely yes. The guide has 97 pages covering installation, feature gates, + RBAC, VM creation, instancetypes and preferences, live migration, CPU and + memory hotplug, NUMA, hugepages, host device and GPU passthrough, network + binding plugins, hotplug interfaces, CDI, snapshots, cloning, export, volume + migration, and a debugging section. Features shipped in v1.9, such as + VirtualMachineTemplate v1beta1, decentralized live migration, and the Plugins + framework, already have pages. + + There are gaps in the coverage. The `cluster_admin/plugins.md` page exists but + is absent from `cluster_admin/.nav.yml` and is not linked from any other page, + so it does not appear in the site navigation. VirtualMachineBackup, referenced + several times in the v1.9 release notes, has no page. There is no section that + describes the KubeVirt custom resource (`kubevirt.io/v1 KubeVirt`) + configuration fields as a whole; configuration knobs are scattered across + feature pages. - Are there step-by-step instructions documented for features in tasks and tutorials? - Yes, most feature pages include copy-and-paste `kubectl` and `virtctl` - commands with YAML manifests. Pages such as Live Migration, Creating - VirtualMachines by using virtctl, Installation, and Hotplug Volumes walk - through enable, apply, verify, and cancel steps in order. The Welcome page - also links to external Killercoda scenarios, minikube and kind quickstarts, - and hands-on labs hosted on kubevirt.io. + Yes, for most features. Feature pages consistently follow a pattern of + prerequisites, a feature-gate enablement pointer, YAML examples, and + verification commands. Pages such as + `user_workloads/accessing_virtual_machines.md`, `storage/hotplug_volumes.md`, + `compute/live_migration.md`, and `network/istio_service_mesh.md` include full + working manifests and the exact commands to run. - The instructions are presented as reference-style sections rather than - numbered procedures, so the boundary between "what this option means" and "do - this next" is often unclear. There are no true tutorials in the guide itself; - the tutorial role is delegated to the external quickstarts and labs. + The instructions are closer to annotated reference examples than to numbered + task procedures. Few pages use ordered steps, and most pages mix conceptual + explanation, configuration options, and procedure in the same section. + Interactive tutorials are delegated to external sites: Killercoda scenarios + and the quickstart and lab pages on `kubevirt.io`. - Are there any key features that are documented but missing task documentation? - Yes. Filesystems, Disks and Volumes describes every disk and volume type at - length (over 2,000 lines) but does not provide a task for the common goal of - "attach persistent storage to a VM and boot from it." Interfaces and Networks - similarly explains each binding and network type without a task for "connect a - VM to a secondary network." The Debug page covers log verbosity and profiling - but does not offer a task-oriented "my VM will not start" walkthrough. - - The Windows content is another example. Windows virtio drivers, legacy - Windows, and sysprep are documented as options, but there is no end-to-end - task for creating a Windows VM. + Yes. The `architecture.md` page describes VirtualMachineInstanceReplicaSet as + a primary high-level resource, but `user_workloads/replica_set.md` and + `user_workloads/pool.md` are reference-style pages. The + `user_workloads/virtctl_client_tool.md` page covers only downloading and + installing `virtctl`, while the individual subcommands are documented, if at + all, inside the pages of the features they support. + + The guide also has no end-to-end procedure that takes a user from a freshly + installed cluster to a running, reachable VM. `user_workloads/lifecycle.md` + assumes a `vmi.yaml` exists without showing one; + `user_workloads/creating_vms.md` is a 488-line page dedicated to + `virtctl create vm`; and `user_workloads/accessing_virtual_machines.md` is a + separate 400-line page. The Welcome page links to `kubevirt.io/labs` for the + connected walkthrough. - Is the "happy path" (most common use case) documented? - Partially. The Installation page gets a cluster to a running KubeVirt, and the - Lifecycle and Creating VirtualMachines pages show how to create, start, stop, - and access a VM. The Creating VirtualMachines by using virtctl page is a - strong example because it shows the fastest route from nothing to a running VM - with a cloud image and SSH access. + Partly. The pieces of the happy path exist: install KubeVirt + (`cluster_admin/installation.md`), install `virtctl`, create a VM, start it, + and connect to it. Each page is individually solid. - However, the happy path is split across several pages in different sections, - and the in-guide entry point is a Quickstarts page that only contains external - links. A reader who lands on the user guide without going through kubevirt.io - first has no single page that strings install, create, access, and delete - together. + The pieces are not arranged as a path. The "User Workloads" section opens with + `lifecycle.md`, which is a VMI-centric page using + `kubectl create -f vmi.yaml`, followed by `basic_use.md`, and then + `creating_vms.md`, which is `virtctl`-centric. A new user encounters three + different entry points to the same task before reaching + `accessing_virtual_machines.md`. The Quickstarts page in the top-level nav is + a link list to external pages rather than a walkthrough in the guide. - Are tasks clearly named according to user goals? - Mixed. Some page titles are goal-oriented, such as Creating VirtualMachines by - using virtctl, Download and Install the virtctl Command Line Interface, and - Activating and deactivating feature gates. Section headings inside pages are - also often action-oriented, for example "Initiate live migration" and - "Canceling a live migration." + Mostly. Many titles state a user goal: "Accessing Virtual Machines", "Creating + VirtualMachines by using virtctl", "Boot from external source", "Activating + and deactivating feature gates", "Hotplug Volumes". - Most page titles are named after the feature or API object rather than the - user goal: Filesystems, Disks and Volumes; Presets; Pool; ReplicaSet; VSOCK; - KSM; Clone API; Export API. A user who wants to "copy a VM" or "back up a VM" - must already know that the relevant feature is called the Clone API or Export - API. + Other titles are feature or component names that do not communicate the task: + "Lifecycle", "Basic use", "Virtual hardware", "Run strategies", "Client + passthrough", "CSI overlay", "Container_path volumes", "Guest_fs", "Migration + controller". Two nav labels are ambiguous side by side: "VirtualMachine + Templates" (`vm_templates.md`) and "Templates" (`templates.md`). The + `.nav.yml` files use filenames rather than titles, so ordering choices are + intentional but the labels are whatever the page H1 provides. - If the documentation doesn't suffice, is there a clear escalation path for users needing more help? (FAQ, Troubleshooting) - Partially. The Welcome page lists how to file a bug, the mailing list, and the - Slack channel. The Virtualization Debugging section provides deep-dive guides - for logs, privileged node debugging, virsh commands, and attaching strace or - gdb to QEMU. + An escalation path to people exists: the Welcome page lists the issue tracker, + the kubevirt-dev mailing list, and the `#virtualization` Kubernetes Slack + channel. The "Virtualization Debugging" section provides deep-dive pages on + log verbosity, privileged node debugging, `virsh`, and attaching `strace` or + `gdb` to QEMU. - There is no FAQ and no troubleshooting page organized by symptom. Existing - troubleshooting content is scattered in "Limitations and known issues" - subsections on individual feature pages. The Debugging section is written for - developers debugging the virtualization stack rather than for users whose VM - failed to schedule, boot, or migrate. + There is no FAQ and no troubleshooting hub. A search for "Troubleshooting" + finds only sub-sections on three pages (`storage/container_path_volumes.md`, + `network/istio_service_mesh.md`, and `debug_virt_stack/launch-qemu-gdb.md`). + The debugging section is aimed at developers and cluster administrators + debugging the virtualization stack; it does not cover the common user-level + questions such as a VMI stuck in `Scheduling` or `ErrImagePull`, a + `DataVolume` import that never completes, or a migration that is `Pending`. - If the product exposes an API, is there a complete reference that includes documented CLIs as applicable? - Yes for the API, no for the CLI. The Welcome page and many feature pages link - to the generated API reference at kubevirt.io/api-reference, which documents - every field of the KubeVirt custom resources. Several links point to the - `master` version rather than a release-specific version, and one page links to - the very old `v0.13.2` reference. + Yes for the API. The Welcome page links to the generated API reference at + `kubevirt.io/api-reference/`, and pages such as + `cluster_admin/annotations_and_labels.md`, `cluster_admin/authorization.md`, + and `network/hotplug/nad_reference.md` supply reference-style tables. The + release notes carry a per-release "API change" list. - The `virtctl` CLI has no reference page. The virtctl page only covers download - and installation, and individual subcommands are documented piecemeal on the - feature pages that use them (create, migrate, ssh, vnc, and so on). There is - no single list of virtctl commands and flags. + No for the CLI. `virtctl` is mentioned on 28 pages, but there is no page that + lists its subcommands and flags. `user_workloads/virtctl_client_tool.md` stops + after installation. The `virtctl create vm` page is thorough for that one + subcommand, but a user looking for `virtctl vm_export` or `virtctl guest_fs` + must know which feature page to search. - Is content up to date and accurate? - Mostly. Release notes are current through v1.8.0, feature pages record the - KubeVirt version in which a feature became alpha, beta, or generally - available, and new features such as DRA GPUs and decentralized live migration - are documented. The Presets page clearly flags that the feature has been - deprecated since v0.57.0. - - Some stale content remains. The Installation page still documents installing - on OKD from the Service Catalog as an APB and on k3OS, both of which are - long-unmaintained paths. Many API reference links point to `master` rather - than the current release. Because feature gate status is tracked per page, - some pages likely describe features as alpha or beta after they have - graduated. + The guide is actively maintained. Release notes for v1.9.0 (July 2026) are + present, and pages for v1.9 features already carry FEATURE STATE banners with + version references. Feature gate pages point to the current activation + procedure. + + Stale content remains in the older pages. `cluster_admin/installation.md` + still documents installing from the OKD Service Catalog as an Ansible Playbook + Bundle, a mechanism that has been retired from OKD for several releases, and + links throughout the guide point to OpenShift 4.10 documentation. + `cluster_admin/api_validation.md` notes that a flag "was deprecated in 1.10", + referring to Kubernetes 1.10. `compute/windows_virtio_drivers.md` is a + byte-for-byte duplicate of `user_workloads/windows_virtio_drivers.md` and is + reachable only through the redirect map in `mkdocs.yml`. + `user_workloads/templates.md` and `user_workloads/hook-sidecar.md` describe + superseded mechanisms; both carry notes pointing to their replacements, which + is good practice. - Does the documentation need restructuring? - No major restructuring is needed; the current top-level split into Cluster - Administration, User Workloads, Compute, Network, Storage, and Virtualization - Debugging is sound and was itself the result of a recent reorganization, as - the extensive redirect map in `mkdocs.yml` shows. Navigation order within each - section is deliberately curated through `.nav.yml` files. + A moderate restructuring, not a rewrite. The six top-level sections (Cluster + Administration, User Workloads, Compute, Network, Storage, Virtualization + Debugging) map well to how users think about the product and to the KubeVirt + SIG structure. Explicit `.nav.yml` ordering shows care in sequencing pages + within sections. - Targeted improvements would help. The User Workloads section mixes - getting-started content (Lifecycle, Basic use, Creating VMs) with advanced - workload controllers (Pool, ReplicaSet, hook sidecars), and would benefit from - a separate Getting Started grouping that contains an in-guide happy-path - tutorial. A user-facing Troubleshooting or FAQ page, a virtctl command - reference, and task-oriented page titles would improve findability without - moving existing content. + The weak points are the entry sequence in User Workloads, the lack of a + distinct "Reference" or "Troubleshooting" grouping, and a Compute section that + mixes user-facing tasks (CPU hotplug, run strategies) with + cluster-administrator tuning (KSM, node over-commit, NUMA, mediated devices). + The distinction between what a cluster administrator does once and what a VM + owner does per workload is not reflected consistently in the section + boundaries. ##### Comment -The KubeVirt user guide is a broad, well-maintained reference for a mature -project. Its top-level structure separates cluster administration, user -workloads, compute, network, storage, and debugging in a way that maps to real -roles and concerns, and the content within each section is deliberately ordered -rather than alphabetized. A reader who already knows the name of a KubeVirt -feature can almost always find a page for it, and that page will typically -include working YAML and command examples. - -The guide is less effective for readers who arrive with a goal rather than a -feature name. It is organized as a catalog of features and API objects, with few -pages that lead a user from a goal ("run my first VM," "give my VM persistent -storage," "figure out why my VM will not start") to the sequence of features -that accomplishes it. Adding a small task and troubleshooting layer on top of -the existing reference content, in the spirit of the Prometheus documentation's -separation of concepts, guides, and reference, would make the guide considerably -more useful without disturbing what already works. - -Strengths - -- Coverage is nearly complete, with pages for new v1.8 features already present - and release notes current. -- The Architecture page gives a clear conceptual model of the KubeVirt - components and their choreography. -- Top-level sections and curated `.nav.yml` ordering reflect user roles and a - sensible progression. -- Feature pages record the release in which a feature became alpha, beta, or - generally available, and deprecated features such as Presets are clearly - flagged. -- Recent reorganization was handled carefully, with a comprehensive redirect map - preserving old links. - -Weaknesses - -- Page titles are feature names rather than user goals (Clone API, Export API, - Pool, VSOCK), so users must already know the feature to find the task. -- The happy path from install to an accessible VM is spread across multiple - sections, and the in-guide Quickstarts page contains only external links. -- Large reference pages such as Filesystems, Disks and Volumes and Interfaces - and Networks lack a task for their most common use. -- There is no user-facing Troubleshooting or FAQ page; the debugging section - targets stack developers, and known issues are scattered across feature pages. -- The `virtctl` CLI has no consolidated command reference. -- Some content is stale, including the OKD Service Catalog and k3OS installation - paths and API reference links that point to `master` rather than the current - release. +The KubeVirt user guide is a mature, feature-complete reference organized into +sensible top-level sections that mirror the product's compute, network, and +storage layers. Coverage keeps pace with releases: v1.9 features have pages, +feature-state banners cite versions, and deprecated mechanisms point to their +replacements. Explicit navigation ordering in every directory shows deliberate +curation rather than alphabetical defaults. + +The guide's main weakness is that it reads as an encyclopedia of features rather +than as a set of paths through them. The new-user entry sequence is fragmented +across three pages with different tooling, there is no in-guide end-to-end +walkthrough from install to a reachable VM, and troubleshooting is limited to a +developer-oriented debugging section with no user-facing FAQ or symptom-based +guide. Reference material is uneven: the Kubernetes API is covered by a +generated reference, but the `virtctl` CLI, which appears on more than a quarter +of the pages, has no consolidated command reference. + +Compared with the Prometheus documentation, which separates Introduction, +Concepts, Guides, and Reference at the top level, the KubeVirt guide blends +these content types within each feature page. The underlying material is good +enough that the improvements are largely a matter of adding connective pages and +a small number of reorganizations rather than writing new feature content. + +Strengths: + +- Broad and current feature coverage, including v1.9 features, with consistent + FEATURE STATE banners. +- Feature pages follow a recognizable pattern: prerequisites, feature-gate + pointer, working manifests, verification commands. +- Top-level sections and explicit `.nav.yml` ordering give the guide a clear, + intentional shape. +- Superseded pages (OpenShift Templates, hook sidecars) carry notes redirecting + readers to replacements. +- Escalation to humans is easy to find: issue tracker, mailing list, and Slack + are on the landing page. + +Weaknesses: + +- No end-to-end happy-path tutorial inside the guide; the User Workloads section + opens with three overlapping entry pages. +- No troubleshooting hub or FAQ; the debugging section targets stack developers + rather than VM owners. +- No `virtctl` command reference; subcommands are documented only inside the + feature pages that use them. +- Some pages are orphaned or duplicated (`cluster_admin/plugins.md` missing from + nav; two identical `windows_virtio_drivers.md` files). +- Stale content in older administration pages, including OKD Service Catalog + installation and Kubernetes 1.10 references. +- Several page titles name components rather than user goals, and the Compute + section mixes per-VM tasks with cluster tuning. Rating: 3 - Meets standards @@ -843,51 +864,55 @@ needs I see as a novice user: The following recommendations for improving the information architecture of the KubVirt User Guide: -- Add a Getting Started grouping at the top of the User Workloads section that - contains a single end-to-end tutorial: install KubeVirt, install `virtctl`, - create a VM from a cloud image, connect over SSH or console, and stop and - delete the VM. Move Basic use, Lifecycle, Creating VirtualMachines by using - virtctl, and the virtctl installation page into this grouping so the happy - path is in one place. -- Replace the external-links-only Quickstarts page with a short in-guide - quickstart, and keep the Killercoda, minikube, kind, and cloud-provider links - as a "Try it in a sandbox" list at the bottom. -- Add a user-facing Troubleshooting page, organized by symptom (VM stuck in - Scheduling, VM fails to boot, migration does not complete, cannot reach the VM - over the network), that points to the relevant feature page and to the deeper - Virtualization Debugging guides. Consolidate the scattered "Limitations and - known issues" subsections into it or link to them from it. -- Add a short FAQ page or FAQ section on the Welcome page covering the most - common questions, such as the difference between VM and VMI, whether a UI is - provided, and which Kubernetes versions are supported. -- Add a `virtctl` command reference page that lists every subcommand with a - one-line description and a link to the feature page where it is explained in - depth. Generate it from `virtctl --help` output where possible to keep it - current. -- Add task-oriented "How to" sections at the top of large reference pages. For - example, Filesystems, Disks and Volumes should open with "Attach a persistent - volume to a VM" and "Boot from a PVC," and Interfaces and Networks should open - with "Connect a VM to a secondary network." -- Add an end-to-end task for creating a Windows VM that ties together the virtio - drivers, sysprep, and legacy Windows pages. -- Rename pages toward user goals where practical, for example "Clone a VM" - instead of "Clone API," "Export a VM disk" instead of "Export API," and "Run a - group of identical VMs" for Pool and ReplicaSet. Add redirects in `mkdocs.yml` - for any renamed paths. -- Add a one- or two-sentence "When to use this" introduction to feature pages - that currently open directly with configuration options, so readers can - quickly decide whether the page is relevant. -- Add pages for v1.8 features that appear in the release notes but not in the - guide, including Changed Block Tracking backups, the `rebootPolicy` field, and - the `virtctl` virt-template commands. Consider a single Backup and Restore - page that ties together snapshots, exports, CBT, and hooks. -- Remove or clearly mark as unmaintained the OKD Service Catalog/APB and k3OS - installation paths on the Installation page. -- Update API reference links to point to the current release version rather than - `master`, and fix the outdated `v0.13.2` link on the Windows virtio drivers +- Add a "Getting started" tutorial to the User Workloads section that walks a + new user from a working KubeVirt installation through installing `virtctl`, + creating a VM, starting it, and connecting over console and SSH. Make it the + first page in `user_workloads/.nav.yml` and link to it from the Welcome and + Quickstarts pages. +- Consolidate `user_workloads/lifecycle.md` and `user_workloads/basic_use.md` + into a single page that explains the VirtualMachine and VirtualMachineInstance + relationship and the start, stop, pause, and delete operations with both + `kubectl` and `virtctl`. Move the remaining `basic_use.md` note about the + absence of a UI to the architecture page. +- Create a `virtctl` command reference page that lists every subcommand with a + one-line purpose, its most-used flags, and a link to the feature page that + covers it in depth. Rename `user_workloads/virtctl_client_tool.md` to reflect + that it covers installation only, or fold installation into the new reference page. -- Audit feature pages that record alpha or beta status against the current - feature gate list and update any that have graduated to general availability. +- Add a "Troubleshooting" page, placed either at the top of the Virtualization + Debugging section or as a new top-level entry, organized by symptom: VMI stuck + in `Scheduling` or `Pending`, `ErrImagePull` on the virt-launcher Pod, + `DataVolume` import not progressing, live migration stuck, and console or VNC + connection failures. Link each symptom to the relevant deep-dive page. +- Add `plugins.md` to `cluster_admin/.nav.yml` so the Plugins page appears in + the navigation, and link to it from `user_workloads/hook-sidecar.md` where the + legacy mechanism is described. +- Delete `docs/compute/windows_virtio_drivers.md` and update the `mkdocs.yml` + redirect map so `virtual_machines/windows_virtio_drivers.md` points only at + the `user_workloads/` copy. +- Remove the "From Service Catalog as an APB" subsection from + `cluster_admin/installation.md`, and audit the guide for links to OpenShift + 4.10 documentation and for version references such as "deprecated in 1.10" in + `cluster_admin/api_validation.md`, updating or removing each. +- Add a page for VirtualMachineBackup, which is referenced in the v1.9 release + notes but has no page in the Storage section. +- Retitle pages whose names describe a component rather than a task or concept, + for example "Run strategies" to "Controlling when a VM runs", "Guest_fs" to + "Inspecting and modifying VM disks with lib_guest_fs", and "Migration + controller" to a title that states what the user accomplishes. Rename the nav + label for `templates.md` to "OpenShift Templates (legacy)" to distinguish it + from "VirtualMachine Templates". +- Split the Compute section into user-facing VM configuration (CPU and memory + hotplug, dedicated CPUs, virtual hardware, run strategies, memory dump) and + cluster-level tuning (KSM, node over-commit, NUMA, hugepages, mediated + devices, host devices), either as two sub-groups in `compute/.nav.yml` or by + moving the tuning pages to Cluster Administration. +- Expand `architecture.md` with short descriptions of virt-api, virt-controller, + virt-handler, and virt-launcher, and a diagram or paragraph showing how a VMI + maps to a virt-launcher Pod, so later pages can assume these concepts. +- Add a "KubeVirt configuration" reference page in Cluster Administration that + lists the `spec.configuration` fields of the KubeVirt custom resource and + links each field to the feature page that explains it. #### New user content From fd9ed028370167824bcd5abfd7e5e5873198b1d3 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Thu, 24 Sep 2026 13:54:42 -0700 Subject: [PATCH 35/49] added istio to cspell Signed-off-by: Bruce Hamilton --- .cspell.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.cspell.yml b/.cspell.yml index 03845d35..d62d7915 100644 --- a/.cspell.yml +++ b/.cspell.yml @@ -80,3 +80,6 @@ words: - inclusivity - passt - WCAG + - istio + - Istio + From 669818af7956c05684c846ed7076e573b9a3810e Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Thu, 24 Sep 2026 13:59:29 -0700 Subject: [PATCH 36/49] format fix Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/analysis.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/analyses/2026/kubevirt/analysis.md b/analyses/2026/kubevirt/analysis.md index 013df8a8..49b1f675 100644 --- a/analyses/2026/kubevirt/analysis.md +++ b/analyses/2026/kubevirt/analysis.md @@ -309,10 +309,10 @@ documentation. We evaluate on the following: - Is the documentation feature complete? - Largely yes. The guide has 97 pages covering installation, feature gates, - RBAC, VM creation, instancetypes and preferences, live migration, CPU and - memory hotplug, NUMA, hugepages, host device and GPU passthrough, network - binding plugins, hotplug interfaces, CDI, snapshots, cloning, export, volume + Mostly yes. The guide has 97 pages covering installation, feature gates, RBAC, + VM creation, instancetypes and preferences, live migration, CPU and memory + hotplug, NUMA, hugepages, host device and GPU passthrough, network binding + plugins, hotplug interfaces, CDI, snapshots, cloning, export, volume migration, and a debugging section. Features shipped in v1.9, such as VirtualMachineTemplate v1beta1, decentralized live migration, and the Plugins framework, already have pages. From 21ea0ca02d968c219c61ebc56b5e51ca415d0004 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Thu, 24 Sep 2026 15:17:44 -0700 Subject: [PATCH 37/49] ran prettier Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/analysis.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/analyses/2026/kubevirt/analysis.md b/analyses/2026/kubevirt/analysis.md index 49b1f675..d781e47b 100644 --- a/analyses/2026/kubevirt/analysis.md +++ b/analyses/2026/kubevirt/analysis.md @@ -330,10 +330,9 @@ documentation. We evaluate on the following: Yes, for most features. Feature pages consistently follow a pattern of prerequisites, a feature-gate enablement pointer, YAML examples, and - verification commands. Pages such as - `user_workloads/accessing_virtual_machines.md`, `storage/hotplug_volumes.md`, - `compute/live_migration.md`, and `network/istio_service_mesh.md` include full - working manifests and the exact commands to run. + verification commands. Pages such as `accessing_virtual_machines.md`, + `hotplug_volumes.md`, `live_migration.md`, and `istio_service_mesh.md` include + full working manifests and the exact commands to run. The instructions are closer to annotated reference examples than to numbered task procedures. Few pages use ordered steps, and most pages mix conceptual From 2245e8570a04a4cdc04de87bc922c1fc55664668 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Thu, 24 Sep 2026 15:24:18 -0700 Subject: [PATCH 38/49] ran prettier on cspell Signed-off-by: Bruce Hamilton --- .cspell.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/.cspell.yml b/.cspell.yml index d62d7915..af63bc5c 100644 --- a/.cspell.yml +++ b/.cspell.yml @@ -82,4 +82,3 @@ words: - WCAG - istio - Istio - From e5ad83d8d2960901dc8b5a9bb309930ae49d3075 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Thu, 24 Sep 2026 17:19:52 -0700 Subject: [PATCH 39/49] info arch milestone Signed-off-by: Bruce Hamilton --- .cspell.yml | 2 +- analyses/2026/kubevirt/analysis.md | 297 +++++++---------------------- 2 files changed, 65 insertions(+), 234 deletions(-) diff --git a/.cspell.yml b/.cspell.yml index af63bc5c..96daf328 100644 --- a/.cspell.yml +++ b/.cspell.yml @@ -81,4 +81,4 @@ words: - passt - WCAG - istio - - Istio + - addvolume diff --git a/analyses/2026/kubevirt/analysis.md b/analyses/2026/kubevirt/analysis.md index d781e47b..db4be12e 100644 --- a/analyses/2026/kubevirt/analysis.md +++ b/analyses/2026/kubevirt/analysis.md @@ -292,217 +292,80 @@ documentation. We evaluate on the following: - Is there high level conceptual content? - Yes. The `architecture.md` page explains the stack, the controller and daemon - model, and the relationship between VirtualMachine, VirtualMachineInstance, - and VirtualMachineInstanceReplicaSet resources. The landing page (`index.md`) - describes each top-level section in one line, and pages such as - `user_workloads/lifecycle.md`, `network/interfaces_and_networks.md`, and - `storage/disks_and_volumes.md` open with short conceptual introductions before - describing configuration. - - Conceptual content is concentrated in the architecture page and is thin - elsewhere. The `architecture.md` page relies on an ASCII stack diagram and two - images, and it does not explain the virt-launcher Pod, the virt-api component, - or how a VMI maps onto a Pod, which are concepts that most later pages assume. - The `user_workloads/basic_use.md` page is a twenty-line stub with four - `kubectl` commands and a note that KubeVirt has no UI. + Yes. The Architecture page gives a conceptual overview of the KubeVirt stack, explains how CRDs, controllers, and node daemons extend Kubernetes, and describes each component (`virt-api`, `virt-controller`, `virt-handler`, `virt-launcher`). Several feature pages open with a short overview before the procedure, for example Live Migration, Run Strategies, and VirtualMachine Templates. + + Conceptual content is thin at the section level. The Welcome page describes each top-level section in one line, but the Compute, Network, and Storage sections have no landing or overview page that explains how their pages relate or which one a reader needs first. The User Workloads section relies on the two-paragraph Basic Use page and the Lifecycle page for its conceptual framing. - Is the documentation feature complete? - Mostly yes. The guide has 97 pages covering installation, feature gates, RBAC, - VM creation, instancetypes and preferences, live migration, CPU and memory - hotplug, NUMA, hugepages, host device and GPU passthrough, network binding - plugins, hotplug interfaces, CDI, snapshots, cloning, export, volume - migration, and a debugging section. Features shipped in v1.9, such as - VirtualMachineTemplate v1beta1, decentralized live migration, and the Plugins - framework, already have pages. - - There are gaps in the coverage. The `cluster_admin/plugins.md` page exists but - is absent from `cluster_admin/.nav.yml` and is not linked from any other page, - so it does not appear in the site navigation. VirtualMachineBackup, referenced - several times in the v1.9 release notes, has no page. There is no section that - describes the KubeVirt custom resource (`kubevirt.io/v1 KubeVirt`) - configuration fields as a whole; configuration knobs are scattered across - feature pages. - -- Are there step-by-step instructions documented for features in tasks and - tutorials? - - Yes, for most features. Feature pages consistently follow a pattern of - prerequisites, a feature-gate enablement pointer, YAML examples, and - verification commands. Pages such as `accessing_virtual_machines.md`, - `hotplug_volumes.md`, `live_migration.md`, and `istio_service_mesh.md` include - full working manifests and the exact commands to run. - - The instructions are closer to annotated reference examples than to numbered - task procedures. Few pages use ordered steps, and most pages mix conceptual - explanation, configuration options, and procedure in the same section. - Interactive tutorials are delegated to external sites: Killercoda scenarios - and the quickstart and lab pages on `kubevirt.io`. + Mostly. The guide covers the core VirtualMachine and VirtualMachineInstance lifecycle, instance types and preferences, pools, replica sets, templates, live migration, hotplug of CPU, memory, volumes, and interfaces, snapshots and restore, clone, export, network binding plugins, feature gates, node maintenance, confidential computing, and debugging. The Arm64 pages document per-architecture device and feature-gate status. + + Some recently released features have no page. The v1.9.0 release notes describe the `VirtualMachineBackup` API, the `CrossArchitectureVirtualization` feature gate, masquerade `PortRanges`, and MigrationPolicy compression, but none of these terms appears outside the release notes. The new Plugins page exists in `cluster_admin/` but is absent from the section `.nav.yml`, so it is reachable only from a link on the deprecated Hook Sidecar page. + +- Are there step-by-step instructions documented for features in tasks and tutorials? + + Yes, for most features. Pages such as Accessing Virtual Machines, Creating VirtualMachines by using virtctl, Live Migration, Hotplug Volumes, and Snapshot and Restore API pair a short explanation with manifests and commands the reader can run. The Debug page and the Virtualization Debugging section walk through log verbosity, privileged node debugging, and launching QEMU under `strace` and `gdb`. + + The guide does not contain a tutorial of its own. The Quickstarts page and Welcome page link out to Killercoda scenarios, kubevirt.io quickstarts, and kubevirt.io labs for the guided "install, create a VM, connect to it" experience. - Are there any key features that are documented but missing task documentation? - Yes. The `architecture.md` page describes VirtualMachineInstanceReplicaSet as - a primary high-level resource, but `user_workloads/replica_set.md` and - `user_workloads/pool.md` are reference-style pages. The - `user_workloads/virtctl_client_tool.md` page covers only downloading and - installing `virtctl`, while the individual subcommands are documented, if at - all, inside the pages of the features they support. - - The guide also has no end-to-end procedure that takes a user from a freshly - installed cluster to a running, reachable VM. `user_workloads/lifecycle.md` - assumes a `vmi.yaml` exists without showing one; - `user_workloads/creating_vms.md` is a 488-line page dedicated to - `virtctl create vm`; and `user_workloads/accessing_virtual_machines.md` is a - separate 400-line page. The Welcome page links to `kubevirt.io/labs` for the - connected walkthrough. + Yes. Basic Use lists four `kubectl` commands and states that the following pages describe how to use the API, but it does not include a sample `vmi.yaml` or link to a page that does. Lifecycle shows `kubectl create -f vmi.yaml` without a manifest. The Architecture page describes components without linking to the operational pages that configure them. The Plugins page describes domain hooks and node hooks at Alpha but is not integrated into the navigation. - Is the "happy path" (most common use case) documented? - Partly. The pieces of the happy path exist: install KubeVirt - (`cluster_admin/installation.md`), install `virtctl`, create a VM, start it, - and connect to it. Each page is individually solid. - - The pieces are not arranged as a path. The "User Workloads" section opens with - `lifecycle.md`, which is a VMI-centric page using - `kubectl create -f vmi.yaml`, followed by `basic_use.md`, and then - `creating_vms.md`, which is `virtctl`-centric. A new user encounters three - different entry points to the same task before reaching - `accessing_virtual_machines.md`. The Quickstarts page in the top-level nav is - a link list to external pages rather than a walkthrough in the guide. + Partially. Installation, `virtctl` installation, creating a VirtualMachine with `virtctl create vm`, starting and stopping it, and connecting over console, VNC, or SSH are all documented. However, these steps sit on five different pages across two sections, and no single page strings them together for a first-time reader. The Welcome page delegates that path to external labs. - Are tasks clearly named according to user goals? - Mostly. Many titles state a user goal: "Accessing Virtual Machines", "Creating - VirtualMachines by using virtctl", "Boot from external source", "Activating - and deactivating feature gates", "Hotplug Volumes". - - Other titles are feature or component names that do not communicate the task: - "Lifecycle", "Basic use", "Virtual hardware", "Run strategies", "Client - passthrough", "CSI overlay", "Container_path volumes", "Guest_fs", "Migration - controller". Two nav labels are ambiguous side by side: "VirtualMachine - Templates" (`vm_templates.md`) and "Templates" (`templates.md`). The - `.nav.yml` files use filenames rather than titles, so ordering choices are - intentional but the labels are whatever the page H1 provides. - -- If the documentation doesn't suffice, is there a clear escalation path for - users needing more help? (FAQ, Troubleshooting) - - An escalation path to people exists: the Welcome page lists the issue tracker, - the kubevirt-dev mailing list, and the `#virtualization` Kubernetes Slack - channel. The "Virtualization Debugging" section provides deep-dive pages on - log verbosity, privileged node debugging, `virsh`, and attaching `strace` or - `gdb` to QEMU. - - There is no FAQ and no troubleshooting hub. A search for "Troubleshooting" - finds only sub-sections on three pages (`storage/container_path_volumes.md`, - `network/istio_service_mesh.md`, and `debug_virt_stack/launch-qemu-gdb.md`). - The debugging section is aimed at developers and cluster administrators - debugging the virtualization stack; it does not cover the common user-level - questions such as a VMI stuck in `Scheduling` or `ErrImagePull`, a - `DataVolume` import that never completes, or a migration that is `Pending`. - -- If the product exposes an API, is there a complete reference that includes - documented CLIs as applicable? - - Yes for the API. The Welcome page links to the generated API reference at - `kubevirt.io/api-reference/`, and pages such as - `cluster_admin/annotations_and_labels.md`, `cluster_admin/authorization.md`, - and `network/hotplug/nad_reference.md` supply reference-style tables. The - release notes carry a per-release "API change" list. - - No for the CLI. `virtctl` is mentioned on 28 pages, but there is no page that - lists its subcommands and flags. `user_workloads/virtctl_client_tool.md` stops - after installation. The `virtctl create vm` page is thorough for that one - subcommand, but a user looking for `virtctl vm_export` or `virtctl guest_fs` - must know which feature page to search. + Mixed. User Workloads pages use goal-oriented names such as "Creating VirtualMachines by using virtctl", "Accessing Virtual Machines", and "Boot from external source". Many Compute, Network, and Storage pages are named for the feature or API rather than the task, for example "Clone API", "Export API", "Snapshot Restore API", "Migration Controller", "CSI Overlay", and "Virtual Hardware". Cluster Administration mixes both styles ("Activating and deactivating feature gates" next to "KSM" and "Scheduler"). + +- If the documentation doesn't suffice, is there a clear escalation path for users needing more help? (FAQ, Troubleshooting) + + Partially. The Welcome page has a Getting Help section that links to the GitHub issue tracker, the kubevirt-dev mailing list, and the Kubernetes Slack channel. The Virtualization Debugging section is the closest thing to troubleshooting content and is aimed at developers and advanced users. + + There is no FAQ and no user-facing troubleshooting page that lists common symptoms (VMI stuck in `Scheduling`, migration failures, console access errors) with causes and fixes. Troubleshooting notes exist but are scattered inside individual feature pages such as Accessing Virtual Machines ("Debugging console access") and Memory Dump. + +- If the product exposes an API, is there a complete reference that includes documented CLIs as applicable? + + Partially. The Welcome page links to the generated API reference at kubevirt.io/api-reference, and individual pages deep-link into it where relevant. There is no `virtctl` command reference in the guide. The `virtctl` page covers only download and installation, and command usage is distributed across feature pages (`create vm`, `start`, `stop`, `pause`, `migrate`, `addvolume`, `vnc`, `ssh`, `port-forward`). Feature gates are documented by procedure but the guide does not maintain a list of gates and their stages; the release notes are the only place that records graduations. - Is content up to date and accurate? - The guide is actively maintained. Release notes for v1.9.0 (July 2026) are - present, and pages for v1.9 features already carry FEATURE STATE banners with - version references. Feature gate pages point to the current activation - procedure. - - Stale content remains in the older pages. `cluster_admin/installation.md` - still documents installing from the OKD Service Catalog as an Ansible Playbook - Bundle, a mechanism that has been retired from OKD for several releases, and - links throughout the guide point to OpenShift 4.10 documentation. - `cluster_admin/api_validation.md` notes that a flag "was deprecated in 1.10", - referring to Kubernetes 1.10. `compute/windows_virtio_drivers.md` is a - byte-for-byte duplicate of `user_workloads/windows_virtio_drivers.md` and is - reachable only through the redirect map in `mkdocs.yml`. - `user_workloads/templates.md` and `user_workloads/hook-sidecar.md` describe - superseded mechanisms; both carry notes pointing to their replacements, which - is good practice. + Largely, with visible legacy pockets. Recently updated pages carry version-stamped feature-state banners (VirtualMachine Templates, Hook Sidecar, Hotplug Volumes), and deprecated mechanisms such as presets, the OpenShift-based Templates page, and the Hook Sidecar are labeled and point to replacements. Release notes extend to v1.9.0. -- Does the documentation need restructuring? + Older content shows its age. Installation still documents installing from the OKD Service Catalog as an Ansible Playbook Bundle and installing on k3OS, and links to OpenShift 4.10 documentation. Basic Use and Lifecycle were last touched in May 2024 and still frame VirtualMachineInstance as the primary object, while the rest of the guide and `virtctl create vm` center on VirtualMachine. `compute/windows_virtio_drivers.md` is a byte-identical, unlisted duplicate of `user_workloads/windows_virtio_drivers.md`. - A moderate restructuring, not a rewrite. The six top-level sections (Cluster - Administration, User Workloads, Compute, Network, Storage, Virtualization - Debugging) map well to how users think about the product and to the KubeVirt - SIG structure. Explicit `.nav.yml` ordering shows care in sequencing pages - within sections. +- Does the documentation need restructuring? - The weak points are the entry sequence in User Workloads, the lack of a - distinct "Reference" or "Troubleshooting" grouping, and a Compute section that - mixes user-facing tasks (CPU hotplug, run strategies) with - cluster-administrator tuning (KSM, node over-commit, NUMA, mediated devices). - The distinction between what a cluster administrator does once and what a VM - owner does per workload is not reflected consistently in the section - boundaries. + Not a full restructure. The 2024 move from a flat `operations/` and `virtual_machines/` layout into audience- and layer-based sections (Cluster Administration, User Workloads, Compute, Network, Storage) with explicit `.nav.yml` ordering and redirects is sound. The remaining problems are within sections rather than between them: the User Workloads section mixes lifecycle basics, Windows guidance, monitoring, and a "Workloads" sub-group of nine pages that includes deprecated presets and both template mechanisms; long Compute and Storage lists have no internal grouping or landing page; and five pages exist outside the navigation. Release Notes, a 3,000-line page, sits in the main navigation between Storage and Contributing. ##### Comment -The KubeVirt user guide is a mature, feature-complete reference organized into -sensible top-level sections that mirror the product's compute, network, and -storage layers. Coverage keeps pace with releases: v1.9 features have pages, -feature-state banners cite versions, and deprecated mechanisms point to their -replacements. Explicit navigation ordering in every directory shows deliberate -curation rather than alphabetical defaults. - -The guide's main weakness is that it reads as an encyclopedia of features rather -than as a set of paths through them. The new-user entry sequence is fragmented -across three pages with different tooling, there is no in-guide end-to-end -walkthrough from install to a reachable VM, and troubleshooting is limited to a -developer-oriented debugging section with no user-facing FAQ or symptom-based -guide. Reference material is uneven: the Kubernetes API is covered by a -generated reference, but the `virtctl` CLI, which appears on more than a quarter -of the pages, has no consolidated command reference. - -Compared with the Prometheus documentation, which separates Introduction, -Concepts, Guides, and Reference at the top level, the KubeVirt guide blends -these content types within each feature page. The underlying material is good -enough that the improvements are largely a matter of adding connective pages and -a small number of reorganizations rather than writing new feature content. +The KubeVirt user guide has a sound top-level information architecture. Content is grouped by audience and layer (Cluster Administration, User Workloads, Compute, Network, Storage, Virtualization Debugging), ordering is controlled deliberately through `.nav.yml` files, and the redirects map shows the project maintained old URLs when it reorganized. Most feature pages follow a consistent pattern of a short concept, a feature-state banner where relevant, and runnable manifests or `virtctl` commands. Deprecated mechanisms are labeled and point to their replacements. Compared with the Prometheus documentation, which the CNCF criteria cite as a good example, the KubeVirt guide has comparable feature coverage but lacks Prometheus's clear "Getting started" spine and its consolidated reference material. + +The main weakness is that the guide is a well-organized encyclopedia rather than a guided path. A new user must assemble the happy path from Installation, the `virtctl` install page, Creating VirtualMachines, Lifecycle, and Accessing Virtual Machines, and the guide points to external Killercoda and kubevirt.io labs to fill that gap. The oldest foundational pages (Basic Use, Lifecycle) still present VirtualMachineInstance as the primary object, which is out of step with the VirtualMachine-centric approach used everywhere else. Reference material for `virtctl` and for feature gates is not consolidated, and there is no user-facing troubleshooting or FAQ page, so the escalation path jumps straight from feature pages to Slack and GitHub issues. + +Currency is uneven. New v1.9 features are documented where a page exists (VirtualMachine Templates, Plugins), but the Plugins page is not in the navigation, several v1.9 APIs and feature gates appear only in release notes, and Installation still carries legacy OKD Service Catalog and k3OS content. Section-internal organization is the other systemic issue: Compute and Storage are long flat lists named after APIs rather than user goals, and the User Workloads "Workloads" sub-group mixes current, legacy, and deprecated mechanisms without signaling which one a reader wants. Strengths: -- Broad and current feature coverage, including v1.9 features, with consistent - FEATURE STATE banners. -- Feature pages follow a recognizable pattern: prerequisites, feature-gate - pointer, working manifests, verification commands. -- Top-level sections and explicit `.nav.yml` ordering give the guide a clear, - intentional shape. -- Superseded pages (OpenShift Templates, hook sidecars) carry notes redirecting - readers to replacements. -- Escalation to humans is easy to find: issue tracker, mailing list, and Slack - are on the landing page. +- Audience- and layer-based top-level sections with explicit, intentional page ordering. +- Redirects preserve old `operations/` and `virtual_machines/` URLs after the reorganization. +- Consistent feature-page pattern: concept, feature-state banner, then manifests and commands. +- Deprecated features (presets, OpenShift templates, Hook Sidecar) are labeled and link to replacements. +- Per-architecture (Arm64) device and feature-gate status pages. +- Deep, multi-level debugging content for advanced users. Weaknesses: -- No end-to-end happy-path tutorial inside the guide; the User Workloads section - opens with three overlapping entry pages. -- No troubleshooting hub or FAQ; the debugging section targets stack developers - rather than VM owners. -- No `virtctl` command reference; subcommands are documented only inside the - feature pages that use them. -- Some pages are orphaned or duplicated (`cluster_admin/plugins.md` missing from - nav; two identical `windows_virtio_drivers.md` files). -- Stale content in older administration pages, including OKD Service Catalog - installation and Kubernetes 1.10 references. -- Several page titles name components rather than user goals, and the Compute - section mixes per-VM tasks with cluster tuning. +- No end-to-end getting-started path inside the guide; the happy path is spread across five pages and external labs. +- Basic Use and Lifecycle are dated and VMI-centric, contradicting the VirtualMachine-first guidance elsewhere. +- No consolidated `virtctl` command reference or feature-gate table. +- No FAQ or user-facing troubleshooting page. +- Several v1.9 features (VirtualMachineBackup, CrossArchitectureVirtualization, PortRanges, migration compression) appear only in release notes; the Plugins page is orphaned from navigation. +- Compute and Storage sections are flat lists with API-style names and no landing page. +- Legacy installation content (OKD Service Catalog APB, k3OS, OpenShift 4.10 links) and a duplicate Windows virtio drivers page remain. Rating: 3 - Meets standards @@ -863,55 +726,23 @@ needs I see as a novice user: The following recommendations for improving the information architecture of the KubVirt User Guide: -- Add a "Getting started" tutorial to the User Workloads section that walks a - new user from a working KubeVirt installation through installing `virtctl`, - creating a VM, starting it, and connecting over console and SSH. Make it the - first page in `user_workloads/.nav.yml` and link to it from the Welcome and - Quickstarts pages. -- Consolidate `user_workloads/lifecycle.md` and `user_workloads/basic_use.md` - into a single page that explains the VirtualMachine and VirtualMachineInstance - relationship and the start, stop, pause, and delete operations with both - `kubectl` and `virtctl`. Move the remaining `basic_use.md` note about the - absence of a UI to the architecture page. -- Create a `virtctl` command reference page that lists every subcommand with a - one-line purpose, its most-used flags, and a link to the feature page that - covers it in depth. Rename `user_workloads/virtctl_client_tool.md` to reflect - that it covers installation only, or fold installation into the new reference - page. -- Add a "Troubleshooting" page, placed either at the top of the Virtualization - Debugging section or as a new top-level entry, organized by symptom: VMI stuck - in `Scheduling` or `Pending`, `ErrImagePull` on the virt-launcher Pod, - `DataVolume` import not progressing, live migration stuck, and console or VNC - connection failures. Link each symptom to the relevant deep-dive page. -- Add `plugins.md` to `cluster_admin/.nav.yml` so the Plugins page appears in - the navigation, and link to it from `user_workloads/hook-sidecar.md` where the - legacy mechanism is described. -- Delete `docs/compute/windows_virtio_drivers.md` and update the `mkdocs.yml` - redirect map so `virtual_machines/windows_virtio_drivers.md` points only at - the `user_workloads/` copy. -- Remove the "From Service Catalog as an APB" subsection from - `cluster_admin/installation.md`, and audit the guide for links to OpenShift - 4.10 documentation and for version references such as "deprecated in 1.10" in - `cluster_admin/api_validation.md`, updating or removing each. -- Add a page for VirtualMachineBackup, which is referenced in the v1.9 release - notes but has no page in the Storage section. -- Retitle pages whose names describe a component rather than a task or concept, - for example "Run strategies" to "Controlling when a VM runs", "Guest_fs" to - "Inspecting and modifying VM disks with lib_guest_fs", and "Migration - controller" to a title that states what the user accomplishes. Rename the nav - label for `templates.md` to "OpenShift Templates (legacy)" to distinguish it - from "VirtualMachine Templates". -- Split the Compute section into user-facing VM configuration (CPU and memory - hotplug, dedicated CPUs, virtual hardware, run strategies, memory dump) and - cluster-level tuning (KSM, node over-commit, NUMA, hugepages, mediated - devices, host devices), either as two sub-groups in `compute/.nav.yml` or by - moving the tuning pages to Cluster Administration. -- Expand `architecture.md` with short descriptions of virt-api, virt-controller, - virt-handler, and virt-launcher, and a diagram or paragraph showing how a VMI - maps to a virt-launcher Pod, so later pages can assume these concepts. -- Add a "KubeVirt configuration" reference page in Cluster Administration that - lists the `spec.configuration` fields of the KubeVirt custom resource and - links each field to the feature page that explains it. +# KubeVirt information architecture: recommendations + +The following recommendations address the information architecture of the KubeVirt user guide. + +- Add a "Getting started" page to the User Workloads section (or expand Basic Use into one) that walks through the happy path on a single page: install KubeVirt, install `virtctl`, create a VirtualMachine with `virtctl create vm` or a sample manifest, start it, connect over console or SSH, and stop it. Link to the existing detailed pages at each step rather than duplicating them. +- Rewrite Basic Use and Lifecycle to present VirtualMachine as the primary object and VirtualMachineInstance as the running instance it manages. Include a complete minimal `vm.yaml`, since both pages currently reference `vmi.yaml` without providing it. +- Add `cluster_admin/plugins.md` to `docs/cluster_admin/.nav.yml` so the Plugins page is discoverable from somewhere other than the deprecated Hook Sidecar page. +- Write pages, or add sections to existing pages, for v1.9 features that currently appear only in the release notes: the `VirtualMachineBackup` API (Storage), the `CrossArchitectureVirtualization` feature gate (Compute or Cluster Administration), masquerade `PortRanges` (Network, in Interfaces and Networks), and MigrationPolicy compression (Cluster Administration, in Migration Policies). +- Create a `virtctl` command reference page, or expand the existing `virtctl` page beyond installation, that lists each subcommand with a one-line description and a link to the feature page that explains it in context. +- Add a feature-gate table to the Activating and Deactivating Feature Gates page that lists each gate, its stage (Alpha, Beta, GA, Deprecated), the version it was introduced or graduated, and a link to its documentation. Ask the maintainers whether this table can be generated from the kubevirt/kubevirt source to avoid drift. +- Add a user-facing Troubleshooting page (separate from the developer-oriented Virtualization Debugging section) that lists common symptoms such as a VMI stuck in `Scheduling` or `Pending`, failed live migration, console or VNC connection errors, and missing `qemu-guest-agent` data, each with likely causes and links to the relevant fix. Consolidate the troubleshooting notes now embedded in Accessing Virtual Machines and Memory Dump there or link to them. +- Add a brief landing page to each of the Compute, Network, and Storage sections that explains what the section covers and groups its pages by task (for example, Storage: provisioning disks, importing images, snapshots and backup, moving data between clusters). +- Rename API-centric page titles to user goals where practical, for example "Clone API" to "Cloning VirtualMachines", "Export API" to "Exporting VirtualMachines and volumes", "Snapshot Restore API" to "Snapshotting and restoring VirtualMachines", and "Migration Controller" to a title that states what the reader accomplishes with it. Add redirects in `mkdocs.yml` if file names change. +- Reorganize the User Workloads "Workloads" sub-group so current mechanisms (instance types, VirtualMachine Templates, pools) come first and legacy or deprecated pages (presets, OpenShift Templates, Hook Sidecar) are grouped under a clearly labeled "Legacy" heading or moved to the end. +- Remove or archive legacy installation content: verify with the maintainers whether the OKD Service Catalog APB and k3OS paths are still supported, and update the OpenShift 4.10 documentation links to a current version or a version-independent URL. +- Delete `docs/compute/windows_virtio_drivers.md`, which is a byte-identical unlisted duplicate of `docs/user_workloads/windows_virtio_drivers.md`, and add a redirect if the old URL was ever published. +- Move Release Notes out of the middle of the main navigation, either to the end of the list or into a top-bar link, so the section list reads as a progression from concepts through administration, workloads, and infrastructure layers. #### New user content From 7d13f28a4dc080c96ef5a2a2c0d02e4ec3fe2b9c Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Thu, 24 Sep 2026 17:25:13 -0700 Subject: [PATCH 40/49] formatting Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/analysis.md | 276 +++++++++++++++++++++++------ 1 file changed, 219 insertions(+), 57 deletions(-) diff --git a/analyses/2026/kubevirt/analysis.md b/analyses/2026/kubevirt/analysis.md index db4be12e..d8d33d6c 100644 --- a/analyses/2026/kubevirt/analysis.md +++ b/analyses/2026/kubevirt/analysis.md @@ -292,80 +292,197 @@ documentation. We evaluate on the following: - Is there high level conceptual content? - Yes. The Architecture page gives a conceptual overview of the KubeVirt stack, explains how CRDs, controllers, and node daemons extend Kubernetes, and describes each component (`virt-api`, `virt-controller`, `virt-handler`, `virt-launcher`). Several feature pages open with a short overview before the procedure, for example Live Migration, Run Strategies, and VirtualMachine Templates. - - Conceptual content is thin at the section level. The Welcome page describes each top-level section in one line, but the Compute, Network, and Storage sections have no landing or overview page that explains how their pages relate or which one a reader needs first. The User Workloads section relies on the two-paragraph Basic Use page and the Lifecycle page for its conceptual framing. + Yes. The Architecture page gives a conceptual overview of the KubeVirt stack, + explains how CRDs, controllers, and node daemons extend Kubernetes, and + describes each component (`virt-api`, `virt-controller`, `virt-handler`, + `virt-launcher`). Several feature pages open with a short overview before the + procedure, for example Live Migration, Run Strategies, and VirtualMachine + Templates. + + Conceptual content is thin at the section level. The Welcome page describes + each top-level section in one line, but the Compute, Network, and Storage + sections have no landing or overview page that explains how their pages relate + or which one a reader needs first. The User Workloads section relies on the + two-paragraph Basic Use page and the Lifecycle page for its conceptual + framing. - Is the documentation feature complete? - Mostly. The guide covers the core VirtualMachine and VirtualMachineInstance lifecycle, instance types and preferences, pools, replica sets, templates, live migration, hotplug of CPU, memory, volumes, and interfaces, snapshots and restore, clone, export, network binding plugins, feature gates, node maintenance, confidential computing, and debugging. The Arm64 pages document per-architecture device and feature-gate status. - - Some recently released features have no page. The v1.9.0 release notes describe the `VirtualMachineBackup` API, the `CrossArchitectureVirtualization` feature gate, masquerade `PortRanges`, and MigrationPolicy compression, but none of these terms appears outside the release notes. The new Plugins page exists in `cluster_admin/` but is absent from the section `.nav.yml`, so it is reachable only from a link on the deprecated Hook Sidecar page. - -- Are there step-by-step instructions documented for features in tasks and tutorials? - - Yes, for most features. Pages such as Accessing Virtual Machines, Creating VirtualMachines by using virtctl, Live Migration, Hotplug Volumes, and Snapshot and Restore API pair a short explanation with manifests and commands the reader can run. The Debug page and the Virtualization Debugging section walk through log verbosity, privileged node debugging, and launching QEMU under `strace` and `gdb`. - - The guide does not contain a tutorial of its own. The Quickstarts page and Welcome page link out to Killercoda scenarios, kubevirt.io quickstarts, and kubevirt.io labs for the guided "install, create a VM, connect to it" experience. + Mostly. The guide covers the core VirtualMachine and VirtualMachineInstance + lifecycle, instance types and preferences, pools, replica sets, templates, + live migration, hotplug of CPU, memory, volumes, and interfaces, snapshots and + restore, clone, export, network binding plugins, feature gates, node + maintenance, confidential computing, and debugging. The Arm64 pages document + per-architecture device and feature-gate status. + + Some recently released features have no page. The v1.9.0 release notes + describe the `VirtualMachineBackup` API, the `CrossArchitectureVirtualization` + feature gate, masquerade `PortRanges`, and MigrationPolicy compression, but + none of these terms appears outside the release notes. The new Plugins page + exists in `cluster_admin/` but is absent from the section `.nav.yml`, so it is + reachable only from a link on the deprecated Hook Sidecar page. + +- Are there step-by-step instructions documented for features in tasks and + tutorials? + + Yes, for most features. Pages such as Accessing Virtual Machines, Creating + VirtualMachines by using virtctl, Live Migration, Hotplug Volumes, and + Snapshot and Restore API pair a short explanation with manifests and commands + the reader can run. The Debug page and the Virtualization Debugging section + walk through log verbosity, privileged node debugging, and launching QEMU + under `strace` and `gdb`. + + The guide does not contain a tutorial of its own. The Quickstarts page and + Welcome page link out to Killercoda scenarios, kubevirt.io quickstarts, and + kubevirt.io labs for the guided "install, create a VM, connect to it" + experience. - Are there any key features that are documented but missing task documentation? - Yes. Basic Use lists four `kubectl` commands and states that the following pages describe how to use the API, but it does not include a sample `vmi.yaml` or link to a page that does. Lifecycle shows `kubectl create -f vmi.yaml` without a manifest. The Architecture page describes components without linking to the operational pages that configure them. The Plugins page describes domain hooks and node hooks at Alpha but is not integrated into the navigation. + Yes. Basic Use lists four `kubectl` commands and states that the following + pages describe how to use the API, but it does not include a sample `vmi.yaml` + or link to a page that does. Lifecycle shows `kubectl create -f vmi.yaml` + without a manifest. The Architecture page describes components without linking + to the operational pages that configure them. The Plugins page describes + domain hooks and node hooks at Alpha but is not integrated into the + navigation. - Is the "happy path" (most common use case) documented? - Partially. Installation, `virtctl` installation, creating a VirtualMachine with `virtctl create vm`, starting and stopping it, and connecting over console, VNC, or SSH are all documented. However, these steps sit on five different pages across two sections, and no single page strings them together for a first-time reader. The Welcome page delegates that path to external labs. + Partially. Installation, `virtctl` installation, creating a VirtualMachine + with `virtctl create vm`, starting and stopping it, and connecting over + console, VNC, or SSH are all documented. However, these steps sit on five + different pages across two sections, and no single page strings them together + for a first-time reader. The Welcome page delegates that path to external + labs. - Are tasks clearly named according to user goals? - Mixed. User Workloads pages use goal-oriented names such as "Creating VirtualMachines by using virtctl", "Accessing Virtual Machines", and "Boot from external source". Many Compute, Network, and Storage pages are named for the feature or API rather than the task, for example "Clone API", "Export API", "Snapshot Restore API", "Migration Controller", "CSI Overlay", and "Virtual Hardware". Cluster Administration mixes both styles ("Activating and deactivating feature gates" next to "KSM" and "Scheduler"). - -- If the documentation doesn't suffice, is there a clear escalation path for users needing more help? (FAQ, Troubleshooting) - - Partially. The Welcome page has a Getting Help section that links to the GitHub issue tracker, the kubevirt-dev mailing list, and the Kubernetes Slack channel. The Virtualization Debugging section is the closest thing to troubleshooting content and is aimed at developers and advanced users. - - There is no FAQ and no user-facing troubleshooting page that lists common symptoms (VMI stuck in `Scheduling`, migration failures, console access errors) with causes and fixes. Troubleshooting notes exist but are scattered inside individual feature pages such as Accessing Virtual Machines ("Debugging console access") and Memory Dump. - -- If the product exposes an API, is there a complete reference that includes documented CLIs as applicable? - - Partially. The Welcome page links to the generated API reference at kubevirt.io/api-reference, and individual pages deep-link into it where relevant. There is no `virtctl` command reference in the guide. The `virtctl` page covers only download and installation, and command usage is distributed across feature pages (`create vm`, `start`, `stop`, `pause`, `migrate`, `addvolume`, `vnc`, `ssh`, `port-forward`). Feature gates are documented by procedure but the guide does not maintain a list of gates and their stages; the release notes are the only place that records graduations. + Mixed. User Workloads pages use goal-oriented names such as "Creating + VirtualMachines by using virtctl", "Accessing Virtual Machines", and "Boot + from external source". Many Compute, Network, and Storage pages are named for + the feature or API rather than the task, for example "Clone API", "Export + API", "Snapshot Restore API", "Migration Controller", "CSI Overlay", and + "Virtual Hardware". Cluster Administration mixes both styles ("Activating and + deactivating feature gates" next to "KSM" and "Scheduler"). + +- If the documentation doesn't suffice, is there a clear escalation path for + users needing more help? (FAQ, Troubleshooting) + + Partially. The Welcome page has a Getting Help section that links to the + GitHub issue tracker, the kubevirt-dev mailing list, and the Kubernetes Slack + channel. The Virtualization Debugging section is the closest thing to + troubleshooting content and is aimed at developers and advanced users. + + There is no FAQ and no user-facing troubleshooting page that lists common + symptoms (VMI stuck in `Scheduling`, migration failures, console access + errors) with causes and fixes. Troubleshooting notes exist but are scattered + inside individual feature pages such as Accessing Virtual Machines ("Debugging + console access") and Memory Dump. + +- If the product exposes an API, is there a complete reference that includes + documented CLIs as applicable? + + Partially. The Welcome page links to the generated API reference at + kubevirt.io/api-reference, and individual pages deep-link into it where + relevant. There is no `virtctl` command reference in the guide. The `virtctl` + page covers only download and installation, and command usage is distributed + across feature pages (`create vm`, `start`, `stop`, `pause`, `migrate`, + `addvolume`, `vnc`, `ssh`, `port-forward`). Feature gates are documented by + procedure but the guide does not maintain a list of gates and their stages; + the release notes are the only place that records graduations. - Is content up to date and accurate? - Largely, with visible legacy pockets. Recently updated pages carry version-stamped feature-state banners (VirtualMachine Templates, Hook Sidecar, Hotplug Volumes), and deprecated mechanisms such as presets, the OpenShift-based Templates page, and the Hook Sidecar are labeled and point to replacements. Release notes extend to v1.9.0. + Largely, with visible legacy pockets. Recently updated pages carry + version-stamped feature-state banners (VirtualMachine Templates, Hook Sidecar, + Hotplug Volumes), and deprecated mechanisms such as presets, the + OpenShift-based Templates page, and the Hook Sidecar are labeled and point to + replacements. Release notes extend to v1.9.0. - Older content shows its age. Installation still documents installing from the OKD Service Catalog as an Ansible Playbook Bundle and installing on k3OS, and links to OpenShift 4.10 documentation. Basic Use and Lifecycle were last touched in May 2024 and still frame VirtualMachineInstance as the primary object, while the rest of the guide and `virtctl create vm` center on VirtualMachine. `compute/windows_virtio_drivers.md` is a byte-identical, unlisted duplicate of `user_workloads/windows_virtio_drivers.md`. + Older content shows its age. Installation still documents installing from the + OKD Service Catalog as an Ansible Playbook Bundle and installing on k3OS, and + links to OpenShift 4.10 documentation. Basic Use and Lifecycle were last + touched in May 2024 and still frame VirtualMachineInstance as the primary + object, while the rest of the guide and `virtctl create vm` center on + VirtualMachine. `compute/windows_virtio_drivers.md` is a byte-identical, + unlisted duplicate of `user_workloads/windows_virtio_drivers.md`. - Does the documentation need restructuring? - Not a full restructure. The 2024 move from a flat `operations/` and `virtual_machines/` layout into audience- and layer-based sections (Cluster Administration, User Workloads, Compute, Network, Storage) with explicit `.nav.yml` ordering and redirects is sound. The remaining problems are within sections rather than between them: the User Workloads section mixes lifecycle basics, Windows guidance, monitoring, and a "Workloads" sub-group of nine pages that includes deprecated presets and both template mechanisms; long Compute and Storage lists have no internal grouping or landing page; and five pages exist outside the navigation. Release Notes, a 3,000-line page, sits in the main navigation between Storage and Contributing. + Not a full restructure. The 2024 move from a flat `operations/` and + `virtual_machines/` layout into audience- and layer-based sections (Cluster + Administration, User Workloads, Compute, Network, Storage) with explicit + `.nav.yml` ordering and redirects is sound. The remaining problems are within + sections rather than between them: the User Workloads section mixes lifecycle + basics, Windows guidance, monitoring, and a "Workloads" sub-group of nine + pages that includes deprecated presets and both template mechanisms; long + Compute and Storage lists have no internal grouping or landing page; and five + pages exist outside the navigation. Release Notes, a 3,000-line page, sits in + the main navigation between Storage and Contributing. ##### Comment -The KubeVirt user guide has a sound top-level information architecture. Content is grouped by audience and layer (Cluster Administration, User Workloads, Compute, Network, Storage, Virtualization Debugging), ordering is controlled deliberately through `.nav.yml` files, and the redirects map shows the project maintained old URLs when it reorganized. Most feature pages follow a consistent pattern of a short concept, a feature-state banner where relevant, and runnable manifests or `virtctl` commands. Deprecated mechanisms are labeled and point to their replacements. Compared with the Prometheus documentation, which the CNCF criteria cite as a good example, the KubeVirt guide has comparable feature coverage but lacks Prometheus's clear "Getting started" spine and its consolidated reference material. - -The main weakness is that the guide is a well-organized encyclopedia rather than a guided path. A new user must assemble the happy path from Installation, the `virtctl` install page, Creating VirtualMachines, Lifecycle, and Accessing Virtual Machines, and the guide points to external Killercoda and kubevirt.io labs to fill that gap. The oldest foundational pages (Basic Use, Lifecycle) still present VirtualMachineInstance as the primary object, which is out of step with the VirtualMachine-centric approach used everywhere else. Reference material for `virtctl` and for feature gates is not consolidated, and there is no user-facing troubleshooting or FAQ page, so the escalation path jumps straight from feature pages to Slack and GitHub issues. - -Currency is uneven. New v1.9 features are documented where a page exists (VirtualMachine Templates, Plugins), but the Plugins page is not in the navigation, several v1.9 APIs and feature gates appear only in release notes, and Installation still carries legacy OKD Service Catalog and k3OS content. Section-internal organization is the other systemic issue: Compute and Storage are long flat lists named after APIs rather than user goals, and the User Workloads "Workloads" sub-group mixes current, legacy, and deprecated mechanisms without signaling which one a reader wants. +The KubeVirt user guide has a sound top-level information architecture. Content +is grouped by audience and layer (Cluster Administration, User Workloads, +Compute, Network, Storage, Virtualization Debugging), ordering is controlled +deliberately through `.nav.yml` files, and the redirects map shows the project +maintained old URLs when it reorganized. Most feature pages follow a consistent +pattern of a short concept, a feature-state banner where relevant, and runnable +manifests or `virtctl` commands. Deprecated mechanisms are labeled and point to +their replacements. Compared with the Prometheus documentation, which the CNCF +criteria cite as a good example, the KubeVirt guide has comparable feature +coverage but lacks Prometheus's clear "Getting started" spine and its +consolidated reference material. + +The main weakness is that the guide is a well-organized encyclopedia rather than +a guided path. A new user must assemble the happy path from Installation, the +`virtctl` install page, Creating VirtualMachines, Lifecycle, and Accessing +Virtual Machines, and the guide points to external Killercoda and kubevirt.io +labs to fill that gap. The oldest foundational pages (Basic Use, Lifecycle) +still present VirtualMachineInstance as the primary object, which is out of step +with the VirtualMachine-centric approach used everywhere else. Reference +material for `virtctl` and for feature gates is not consolidated, and there is +no user-facing troubleshooting or FAQ page, so the escalation path jumps +straight from feature pages to Slack and GitHub issues. + +Currency is uneven. New v1.9 features are documented where a page exists +(VirtualMachine Templates, Plugins), but the Plugins page is not in the +navigation, several v1.9 APIs and feature gates appear only in release notes, +and Installation still carries legacy OKD Service Catalog and k3OS content. +Section-internal organization is the other systemic issue: Compute and Storage +are long flat lists named after APIs rather than user goals, and the User +Workloads "Workloads" sub-group mixes current, legacy, and deprecated mechanisms +without signaling which one a reader wants. Strengths: -- Audience- and layer-based top-level sections with explicit, intentional page ordering. -- Redirects preserve old `operations/` and `virtual_machines/` URLs after the reorganization. -- Consistent feature-page pattern: concept, feature-state banner, then manifests and commands. -- Deprecated features (presets, OpenShift templates, Hook Sidecar) are labeled and link to replacements. +- Audience- and layer-based top-level sections with explicit, intentional page + ordering. +- Redirects preserve old `operations/` and `virtual_machines/` URLs after the + reorganization. +- Consistent feature-page pattern: concept, feature-state banner, then manifests + and commands. +- Deprecated features (presets, OpenShift templates, Hook Sidecar) are labeled + and link to replacements. - Per-architecture (Arm64) device and feature-gate status pages. - Deep, multi-level debugging content for advanced users. Weaknesses: -- No end-to-end getting-started path inside the guide; the happy path is spread across five pages and external labs. -- Basic Use and Lifecycle are dated and VMI-centric, contradicting the VirtualMachine-first guidance elsewhere. +- No end-to-end getting-started path inside the guide; the happy path is spread + across five pages and external labs. +- Basic Use and Lifecycle are dated and VMI-centric, contradicting the + VirtualMachine-first guidance elsewhere. - No consolidated `virtctl` command reference or feature-gate table. - No FAQ or user-facing troubleshooting page. -- Several v1.9 features (VirtualMachineBackup, CrossArchitectureVirtualization, PortRanges, migration compression) appear only in release notes; the Plugins page is orphaned from navigation. -- Compute and Storage sections are flat lists with API-style names and no landing page. -- Legacy installation content (OKD Service Catalog APB, k3OS, OpenShift 4.10 links) and a duplicate Windows virtio drivers page remain. +- Several v1.9 features (VirtualMachineBackup, CrossArchitectureVirtualization, + PortRanges, migration compression) appear only in release notes; the Plugins + page is orphaned from navigation. +- Compute and Storage sections are flat lists with API-style names and no + landing page. +- Legacy installation content (OKD Service Catalog APB, k3OS, OpenShift 4.10 + links) and a duplicate Windows virtio drivers page remain. Rating: 3 - Meets standards @@ -728,21 +845,66 @@ KubVirt User Guide: # KubeVirt information architecture: recommendations -The following recommendations address the information architecture of the KubeVirt user guide. - -- Add a "Getting started" page to the User Workloads section (or expand Basic Use into one) that walks through the happy path on a single page: install KubeVirt, install `virtctl`, create a VirtualMachine with `virtctl create vm` or a sample manifest, start it, connect over console or SSH, and stop it. Link to the existing detailed pages at each step rather than duplicating them. -- Rewrite Basic Use and Lifecycle to present VirtualMachine as the primary object and VirtualMachineInstance as the running instance it manages. Include a complete minimal `vm.yaml`, since both pages currently reference `vmi.yaml` without providing it. -- Add `cluster_admin/plugins.md` to `docs/cluster_admin/.nav.yml` so the Plugins page is discoverable from somewhere other than the deprecated Hook Sidecar page. -- Write pages, or add sections to existing pages, for v1.9 features that currently appear only in the release notes: the `VirtualMachineBackup` API (Storage), the `CrossArchitectureVirtualization` feature gate (Compute or Cluster Administration), masquerade `PortRanges` (Network, in Interfaces and Networks), and MigrationPolicy compression (Cluster Administration, in Migration Policies). -- Create a `virtctl` command reference page, or expand the existing `virtctl` page beyond installation, that lists each subcommand with a one-line description and a link to the feature page that explains it in context. -- Add a feature-gate table to the Activating and Deactivating Feature Gates page that lists each gate, its stage (Alpha, Beta, GA, Deprecated), the version it was introduced or graduated, and a link to its documentation. Ask the maintainers whether this table can be generated from the kubevirt/kubevirt source to avoid drift. -- Add a user-facing Troubleshooting page (separate from the developer-oriented Virtualization Debugging section) that lists common symptoms such as a VMI stuck in `Scheduling` or `Pending`, failed live migration, console or VNC connection errors, and missing `qemu-guest-agent` data, each with likely causes and links to the relevant fix. Consolidate the troubleshooting notes now embedded in Accessing Virtual Machines and Memory Dump there or link to them. -- Add a brief landing page to each of the Compute, Network, and Storage sections that explains what the section covers and groups its pages by task (for example, Storage: provisioning disks, importing images, snapshots and backup, moving data between clusters). -- Rename API-centric page titles to user goals where practical, for example "Clone API" to "Cloning VirtualMachines", "Export API" to "Exporting VirtualMachines and volumes", "Snapshot Restore API" to "Snapshotting and restoring VirtualMachines", and "Migration Controller" to a title that states what the reader accomplishes with it. Add redirects in `mkdocs.yml` if file names change. -- Reorganize the User Workloads "Workloads" sub-group so current mechanisms (instance types, VirtualMachine Templates, pools) come first and legacy or deprecated pages (presets, OpenShift Templates, Hook Sidecar) are grouped under a clearly labeled "Legacy" heading or moved to the end. -- Remove or archive legacy installation content: verify with the maintainers whether the OKD Service Catalog APB and k3OS paths are still supported, and update the OpenShift 4.10 documentation links to a current version or a version-independent URL. -- Delete `docs/compute/windows_virtio_drivers.md`, which is a byte-identical unlisted duplicate of `docs/user_workloads/windows_virtio_drivers.md`, and add a redirect if the old URL was ever published. -- Move Release Notes out of the middle of the main navigation, either to the end of the list or into a top-bar link, so the section list reads as a progression from concepts through administration, workloads, and infrastructure layers. +The following recommendations address the information architecture of the +KubeVirt user guide. + +- Add a "Getting started" page to the User Workloads section (or expand Basic + Use into one) that walks through the happy path on a single page: install + KubeVirt, install `virtctl`, create a VirtualMachine with `virtctl create vm` + or a sample manifest, start it, connect over console or SSH, and stop it. Link + to the existing detailed pages at each step rather than duplicating them. +- Rewrite Basic Use and Lifecycle to present VirtualMachine as the primary + object and VirtualMachineInstance as the running instance it manages. Include + a complete minimal `vm.yaml`, since both pages currently reference `vmi.yaml` + without providing it. +- Add `cluster_admin/plugins.md` to `docs/cluster_admin/.nav.yml` so the Plugins + page is discoverable from somewhere other than the deprecated Hook Sidecar + page. +- Write pages, or add sections to existing pages, for v1.9 features that + currently appear only in the release notes: the `VirtualMachineBackup` API + (Storage), the `CrossArchitectureVirtualization` feature gate (Compute or + Cluster Administration), masquerade `PortRanges` (Network, in Interfaces and + Networks), and MigrationPolicy compression (Cluster Administration, in + Migration Policies). +- Create a `virtctl` command reference page, or expand the existing `virtctl` + page beyond installation, that lists each subcommand with a one-line + description and a link to the feature page that explains it in context. +- Add a feature-gate table to the Activating and Deactivating Feature Gates page + that lists each gate, its stage (Alpha, Beta, GA, Deprecated), the version it + was introduced or graduated, and a link to its documentation. Ask the + maintainers whether this table can be generated from the kubevirt/kubevirt + source to avoid drift. +- Add a user-facing Troubleshooting page (separate from the developer-oriented + Virtualization Debugging section) that lists common symptoms such as a VMI + stuck in `Scheduling` or `Pending`, failed live migration, console or VNC + connection errors, and missing `qemu-guest-agent` data, each with likely + causes and links to the relevant fix. Consolidate the troubleshooting notes + now embedded in Accessing Virtual Machines and Memory Dump there or link to + them. +- Add a brief landing page to each of the Compute, Network, and Storage sections + that explains what the section covers and groups its pages by task (for + example, Storage: provisioning disks, importing images, snapshots and backup, + moving data between clusters). +- Rename API-centric page titles to user goals where practical, for example + "Clone API" to "Cloning VirtualMachines", "Export API" to "Exporting + VirtualMachines and volumes", "Snapshot Restore API" to "Snapshotting and + restoring VirtualMachines", and "Migration Controller" to a title that states + what the reader accomplishes with it. Add redirects in `mkdocs.yml` if file + names change. +- Reorganize the User Workloads "Workloads" sub-group so current mechanisms + (instance types, VirtualMachine Templates, pools) come first and legacy or + deprecated pages (presets, OpenShift Templates, Hook Sidecar) are grouped + under a clearly labeled "Legacy" heading or moved to the end. +- Remove or archive legacy installation content: verify with the maintainers + whether the OKD Service Catalog APB and k3OS paths are still supported, and + update the OpenShift 4.10 documentation links to a current version or a + version-independent URL. +- Delete `docs/compute/windows_virtio_drivers.md`, which is a byte-identical + unlisted duplicate of `docs/user_workloads/windows_virtio_drivers.md`, and add + a redirect if the old URL was ever published. +- Move Release Notes out of the middle of the main navigation, either to the end + of the list or into a top-bar link, so the section list reads as a progression + from concepts through administration, workloads, and infrastructure layers. #### New user content From f2f023d8f88ffbf95ee3c4b04db99c42ec8dbcb4 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Thu, 24 Sep 2026 19:35:45 -0700 Subject: [PATCH 41/49] added more updated areas Signed-off-by: Bruce Hamilton --- .cspell.yml | 1 + analyses/2026/kubevirt/analysis.md | 283 +++++++++++++++++++---------- 2 files changed, 183 insertions(+), 101 deletions(-) diff --git a/.cspell.yml b/.cspell.yml index 96daf328..74cd8e01 100644 --- a/.cspell.yml +++ b/.cspell.yml @@ -82,3 +82,4 @@ words: - WCAG - istio - addvolume + - linux diff --git a/analyses/2026/kubevirt/analysis.md b/analyses/2026/kubevirt/analysis.md index d8d33d6c..7427e3fe 100644 --- a/analyses/2026/kubevirt/analysis.md +++ b/analyses/2026/kubevirt/analysis.md @@ -584,80 +584,117 @@ Rating: 3 - Meets standards #### Content maintainability & site mechanics As a project scales, concerns like localized (translated) content and versioning -become large maintenance burdens, particularly if you don’t plan for them. - -We evaluate on the following: +become large maintenance burdens, particularly if you don’t plan for them. We +evaluate on the following: - Is the documentation searchable? - Yes. The `search` plugin is enabled in `mkdocs.yml` (with a custom tokenizer - separator), and the `mkdocs-material` theme provides a built-in client-side - search box across the site. Users can search all pages from the header search - field. + Yes. The site uses the built-in MkDocs search plugin with the mkdocs-material + theme, so a search box appears in the header on every page and results are + served from a client-side index built at deploy time. `mkdocs.yml` sets a + custom separator that splits on punctuation such as hyphens, colons, and + slashes while preserving version numbers like `v1.9.0`, which helps with + Kubernetes-style identifiers such as `kubevirt.io/libvirt-log-filters` and + `virt-handler`. + + Search is confined to the user guide. The API reference at + kubevirt.io/api-reference, the quickstarts and labs on kubevirt.io, and the + release notes in the kubevirt/kubevirt repository are separate sites with + their own or no search, so a user cannot search across the KubeVirt + documentation set from one box. The theme's search enhancements + (`search.suggest`, `search.highlight`, `search.share`) are not enabled. - Are there plans for localization/internationalization with regards to site directory structure? Is a localization framework present? - No. There is no localization framework configured. The `docs/` tree is - organized by topic (for example `cluster_admin`, `compute`, `network`, - `storage`) with no per-language subdirectories such as `en/` or `zh/`, and no - i18n plugin (for example `mkdocs-static-i18n`) is present in `mkdocs.yml` or - installed by the Netlify build. The theme does not set a language/locale - switcher, and no localization plans are documented in the README or - CONTRIBUTING files. + No. All content is English and lives directly under `docs/`, with no + language-code directory such as `docs/en/`. `mkdocs.yml` does not configure + the mkdocs-material `alternate` language selector or the `i18n` plugin, and + neither README nor CONTRIBUTING mentions translation. No open plans for + localization are documented in the repository. + + The directory layout does not block a future effort. Content is plain Markdown + organized by section, ordering is controlled by `.nav.yml` files, and + redirects are centralized in `mkdocs.yml`, so a language-prefixed tree could + be introduced later. The absence of a root language directory means that step + would require moving every file and updating every redirect. - Is there a clearly documented method for versioning of content? - No. The documentation site publishes a single "latest" version built from the - `main` branch to kubevirt.io/user-guide, and there is no content-versioning - tooling configured. The standard MkDocs Material versioning tool (`mike`) is - not enabled, the theme defines no version provider or version selector, and - neither the README nor CONTRIBUTING describes a method for versioning - documentation. The `release_notes.md` page tracks the KubeVirt product's - release notes rather than versioned snapshots of the docs. + No. The published site at kubevirt.io/user-guide is built from the `main` + branch by Netlify and has no version selector; the only version indicators are + a v1.9.0 release notes page and in-text "as of vX.Y" feature-state banners on + about ten pages. `mkdocs.yml` has no `extra.version` configuration and the + `mike` versioning tool is not used. + + The repository does contain release branches (`release-v1.7-stable`, + `release-v1.8-stable`, `release-v1.9-stable`, and matching `-devel` branches + for 1.7 and 1.8), and they have received commits, so a branching convention + exists in practice. However, no document in the repository explains what those + branches are for, whether they are published anywhere, how or when they are + cut, or how contributors should decide whether a change needs a cherry-pick. + README, CONTRIBUTING, and the Contributing page all describe the fork-and-PR + flow against `main` only. Release notes are maintained by a script + (`update_changelog.sh`) that regenerates the page from kubevirt/kubevirt tags, + but that process is also undocumented outside the script itself. ##### Comment -The KubeVirt User Guide is built on a maintainable foundation. It uses MkDocs -with the `mkdocs-material` theme, keeps all content as Markdown under `docs/`, -and enforces ordering explicitly through per-directory `.nav.yml` files rather -than relying on alphabetical sorting. Search is enabled out of the box via the -`search` plugin, and the contribution workflow is well documented: the README -describes forking, signing commits, and local validation through `make` targets -that check spelling and links (HTMLProofer). Page moves are handled gracefully -through an extensive `redirects` map in `mkdocs.yml`, which preserves old URLs -and reduces link rot. These are strong maintainability practices. - -The most significant gap is content versioning. The site publishes a single -"latest" build from the `main` branch, with no versioning tooling such as `mike` -and no version selector in the theme. Because KubeVirt's API and features evolve -across releases, readers on an older KubeVirt version have no way to view -documentation matching their deployment, and maintainers cannot preserve -historical snapshots. Adopting `mike` (the standard versioning tool for MkDocs -Material) and surfacing a version dropdown would let the project align -documentation with product releases and is the highest-impact maintainability -improvement to pursue. Kubernetes (https://kubernetes.io/docs/) is a good model -of versioned CNCF documentation. - -Localization is a secondary consideration. There is currently no -internationalization framework, no per-language directory structure (for example -`en/` or `zh/`), and no documented plans for translation. While localization may -not be an immediate priority, the current flat, topic-based layout would require -restructuring to support it later. If translation is a future goal, the project -should decide early on a directory convention and evaluate an i18n plugin (such -as `mkdocs-static-i18n`) so the structure can accommodate multiple languages -without a disruptive reorganization. In the near term, documenting the intended -approach—even if implementation is deferred—would help contributors plan content -accordingly. +The KubeVirt user guide is maintainable as a single-version, single-language +site. Its toolchain is simple and well suited to a documentation-only +repository: plain Markdown under `docs/`, mkdocs-material with built-in search, +explicit `.nav.yml` ordering, centralized redirects, and a Makefile that runs +spelling and link checks in a container. The redirects map shows the maintainers +preserved URLs through a major reorganization, which is the kind of discipline +that keeps a site maintainable over time. + +The gap is that the project has outgrown the single-version model without +documenting the alternative. KubeVirt ships minor releases with feature-gate +graduations and API changes, and the repository already has per-release +branches, yet the published site tracks only `main`, offers no version selector, +and no document explains what the release branches are for or how contributors +should use them. Users of an older KubeVirt cannot tell which features on a page +apply to them except where an individual author added an "as of vX.Y" banner. +Compared with the Kubernetes documentation that the CNCF criteria cite as a good +example, which publishes each supported minor version with a selector and +documents its branching and localization processes, KubeVirt's approach is +informal and depends on maintainer memory. + +Localization is absent but not blocked. There is no demand documented, no +framework configured, and no language directory, so this is a low priority; the +main cost of the current layout is that adding a first translation later would +require moving every file. + +Strengths: + +- Simple, low-dependency MkDocs toolchain with search enabled on every page. +- Custom search separator tuned for hyphenated and dotted Kubernetes + identifiers. +- Explicit `.nav.yml` ordering and a centralized redirects map preserve URLs + across reorganizations. +- Makefile targets for local build, spell check, and link check. +- Release branches exist for recent minors, providing a foundation for versioned + publishing. + +Weaknesses: + +- No published version selector; the live site tracks `main` only. +- No document describes the purpose, lifecycle, or publication status of the + `release-vX.Y-*` branches, or when to cherry-pick. +- Version applicability is signaled inconsistently through ad hoc "as of vX.Y" + banners on a minority of pages. +- No localization framework, language directory, or stated position on + translation. +- Search does not span the API reference, quickstarts, or labs hosted elsewhere + on kubevirt.io. Rating: 3 - Meets standards #### Content creation processes Documentation is only as useful as it is accurate and well-maintained, and -requires the same kind of review and approval processes as code. - -We evaluate on the following: +requires the same kind of review and approval processes as code. We evaluate on +the following: - Is there a clearly documented (ongoing) contribution process for documentation? @@ -737,9 +774,8 @@ Rating: 4 - Meets or exceeds standards #### Inclusive language -Creating inclusive project communities is a key goal for all CNCF projects. - -We evaluate on the following: +Creating inclusive project communities is a key goal for all CNCF projects. We +evaluate on the following: - Are there any customer-facing utilities, endpoints, class names, or feature names that use non-recommended words as documented by the @@ -840,11 +876,6 @@ needs I see as a novice user: #### Information architecture -The following recommendations for improving the information architecture of the -KubVirt User Guide: - -# KubeVirt information architecture: recommendations - The following recommendations address the information architecture of the KubeVirt user guide. @@ -908,28 +939,90 @@ KubeVirt user guide. #### New user content +The following recommendations address the new user content of the KubeVirt user +guide. + +- Add a "Getting started" page, placed immediately after Architecture in the + top-level navigation, that walks a new user from a working cluster to a + running VM on one page: install KubeVirt, install `virtctl`, create a + VirtualMachine from a provided manifest or `virtctl create vm`, start it, + connect with `virtctl console`, and stop it. Link to the detailed pages at + each step. Consider folding the current Quickstarts page into it as a "Try it + in a sandbox" section. +- Restructure the Installation page so the core procedure comes first: + Requirements, the four-command operator install, verification, and the + emulation fallback. Move AppArmor, kernel and user-land compatibility, + SELinux, OKD, k3OS, daily developer builds, deploying from source, network + plugins, and node placement below a "Platform-specific and advanced + installation" heading or onto separate pages. +- End the Installation page with a "Next steps" section linking to `virtctl` + installation, Creating VirtualMachines by using virtctl, and Accessing Virtual + Machines. +- Remove or move to a footnote the historical notes about behavior before + v0.20.0 and v0.34.2 on the Installation page; ask the maintainers whether any + supported upgrade path still requires them. +- Expand the `virtctl` page to cover all published client binaries. Use + mkdocs-material content tabs for Linux, macOS, and Windows on both amd64 and + arm64, and include the `chmod +x` and `PATH` steps. Rename the page to + "Installing virtctl" and move it to sit next to Installation, or link to it + from Installation's Next steps. +- Rewrite Basic Use into a short "Your first VirtualMachine" page that includes + a complete minimal `vm.yaml` using a public containerDisk image, the + `kubectl apply`, `virtctl start`, `virtctl console`, and `virtctl stop` + commands, and explicit links to the next pages. Update Lifecycle to reference + that manifest instead of the undefined `vmi.yaml`. +- Enable `content.code.copy` under `theme.features` in `mkdocs.yml` to add a + copy button to every code block. +- Convert `$`-prefixed indented code blocks on the new-user path (Installation, + `virtctl`, Basic Use, Lifecycle) to fenced `shell` blocks without prompt + characters, and place example output in a separate block or a `title="Output"` + annotation so commands paste cleanly. Extend the same treatment to Disks and + Volumes and Export API over time. +- Give the Quickstarts page a one-paragraph introduction that states + prerequisites (a laptop with virtualization enabled, or a browser for + Killercoda), the expected time, and what the reader will have at the end, and + add a closing link to the in-guide Getting started page. +- On the Welcome page, add a one-line "New to KubeVirt? Start here" link at the + top that points to the Getting started page, so the first-run path is + discoverable without reading the section list. + #### Content maintainability & site mechanics The following recommendations address the content maintainability of the KubeVirt user guide. -- Adopt `mike`, the standard versioning tool for MkDocs Material, to publish - documentation versions that align with KubeVirt product releases so readers - can view docs matching their deployment. -- Add a version selector (dropdown) to the theme configuration so users can - switch between the latest and historical documentation snapshots. -- Document the content-versioning method in the README or CONTRIBUTING files, - including how and when new versions are cut relative to KubeVirt releases. -- Decide early on a localization directory convention (for example, per-language - subdirectories such as `en/` or `zh/`) so the current flat, topic-based layout - can accommodate translations without a disruptive future reorganization. -- Evaluate an internationalization plugin such as `mkdocs-static-i18n` and - document the intended localization approach, even if implementation is - deferred, so contributors can plan content accordingly. -- Preserve the existing maintainability strengths—client-side search, explicit - `.nav.yml` ordering, and the `redirects` map in `mkdocs.yml`—and continue - adding redirect entries whenever pages are moved or renamed to prevent link - rot. +- Document the content versioning model in CONTRIBUTING.md (and summarize it on + the Contributing page). State what the `release-vX.Y-stable` and + `release-vX.Y-devel` branches are for, when they are cut relative to a + KubeVirt release, which one Netlify publishes, and how a contributor decides + whether a change on `main` needs a cherry-pick. Ask the maintainers to confirm + the intended workflow first, since the `-devel` branches exist for 1.7 and 1.8 + but not 1.9. +- Publish versioned documentation with a version selector, using either `mike` + with mkdocs-material's `extra.version.provider: mike` or a Netlify build per + release branch under a `/vX.Y/` path. Publish at least the supported N, N-1, + and N-2 minors alongside `latest`. +- Until versioned publishing exists, adopt a standard feature-state admonition + and apply it consistently to every feature page, stating the version + introduced and the current stage (Alpha, Beta, GA, Deprecated). Nine pages use + a `FEATURE STATE:` block today; formalize its format in CONTRIBUTING.md so new + pages follow it. +- Document the release-notes update process: when `update_changelog.sh` is run, + by whom, and how the result is reviewed, so the page continues to be + regenerated after maintainer turnover. +- Enable the mkdocs-material search features `search.suggest`, + `search.highlight`, and `search.share` under `theme.features` in `mkdocs.yml`; + this is a one-line change that improves search usability. +- Add a short "Localization" statement to CONTRIBUTING.md that records the + project's current position (English only, translations not currently accepted, + or translations welcome via a stated process). If translations are anticipated + within the next few releases, move content to `docs/en/` now and configure the + `mkdocs-static-i18n` plugin, so the redirects and `.nav.yml` files only need + to change once. +- Ask the KubeVirt website maintainers whether the API reference and quickstarts + can be indexed by the same search as the user guide, for example by moving the + user guide search to a site-wide index, so users can search the full + documentation set from one place. #### Content creation processes @@ -1044,9 +1137,7 @@ Contributor Documentation rubric. #### Communication methods documented One of the easiest ways to attract new contributors is making sure they know how -to reach you. - -We evaluate on the following: +to reach you. We evaluate on the following: - Is there a Slack/Discord/Discourse/etc. community and is it prominently linked from your website? @@ -1218,9 +1309,7 @@ Rating: 3 - Meets standards Open source is complex and projects have many processes to manage that. Are processes easy to understand and written down so that new contributors can jump -in easily? - -We evaluate on the following: +in easily? We evaluate on the following: - Do you have a community repository or section on your website? @@ -1296,9 +1385,8 @@ Rating: 4 - Meets or exceeds standards #### Project governance documentation -One of the CNCF’s core project values is open governance. - -We evaluate on the following: +One of the CNCF’s core project values is open governance. We evaluate on the +following: - Is project governance clearly documented? @@ -1695,9 +1783,7 @@ Rating: 4 - Meets or exceeds standards #### Branding and design CNCF seeks to support enterprise-ready open source software. A key aspect of -this is branding and marketing. - -We evaluate on the following: +this is branding and marketing. We evaluate on the following: - Is there an easily recognizable brand for the project (logo + color scheme) clearly identifiable? @@ -1773,9 +1859,7 @@ Rating: 4 - Meets or exceeds standards #### Case studies/social proof One of the best ways to advertise an open source project is to show other -organizations using it. - -We evaluate on the following: +organizations using it. We evaluate on the following: - Are there case studies available for the project and are they documented on the website? @@ -1854,9 +1938,8 @@ Rating: 3 - Meets standards SEO helps users find your project and it's documentation, and analytics helps you monitor site traffic and diagnose issues like page 404s. Intra-site search, -while optional, can offer your readers a site-focused search results. - -We evaluate on the following: +while optional, can offer your readers a site-focused search results. We +evaluate on the following: - Is analytics enabled for the production server? @@ -1949,9 +2032,7 @@ Rating: 2 - Needs improvement #### Maintenance planning Website maintenance is an important part of project success, especially when -project maintainers aren’t web developers. - -We evaluate on the following: +project maintainers aren’t web developers. We evaluate on the following: - Is the website tooling well supported by the community (i.e., Hugo with the Docsy theme) or commonly used by CNCF projects? From 112a28ac930e00701d513c97b2c294440c1940e8 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Thu, 24 Sep 2026 20:41:45 -0700 Subject: [PATCH 42/49] proj doc section milestone Signed-off-by: Bruce Hamilton --- .cspell.yml | 1 + analyses/2026/kubevirt/analysis.md | 500 +++++++++++++++++------------ 2 files changed, 301 insertions(+), 200 deletions(-) diff --git a/.cspell.yml b/.cspell.yml index 74cd8e01..bf46ef37 100644 --- a/.cspell.yml +++ b/.cspell.yml @@ -83,3 +83,4 @@ words: - istio - addvolume - linux + - kubelet diff --git a/analyses/2026/kubevirt/analysis.md b/analyses/2026/kubevirt/analysis.md index 7427e3fe..bafc662f 100644 --- a/analyses/2026/kubevirt/analysis.md +++ b/analyses/2026/kubevirt/analysis.md @@ -120,11 +120,11 @@ code. | Criterion | Rating (1-5) | | -------------------------- | ------------------------------ | -| Information architecture | 4 - Meets or exceeds standards | +| Information architecture | 3 - Meets standards | | New user content | 3 - Meets standards | | Content maintainability | 3 - Meets standards | -| Content creation processes | 4 - Meets or exceeds standards | -| Inclusive language | 3 - Meets standards | +| Content creation processes | 3 - Meets standards | +| Inclusive language | 4 - Meets or exceeds standards | ### Comments @@ -133,54 +133,57 @@ Documentation rubric. #### Overall -The KubeVirt user guide's project documentation is in good shape, rating between -"meets standards" and "meets or exceeds standards" across the five criteria. Its -structural foundations are strong: content is organized into clear -domains—cluster administration, user workloads, compute, network, and -storage—with explicit navigation ordering, and it layers conceptual, task, and -reference material effectively. The site is built on a maintainable MkDocs and -`mkdocs-material` stack with all content in Markdown, working search, and a -redirects map that prevents link rot. Contribution is well signposted through -`docs/contributing.md` and Kubernetes-style OWNERS files enforced by Prow, and -the guide is already clean on inclusive naming, with no non-recommended terms -coined by the project. No reorganization is required; the recommended -improvements are additive. - -The most significant cross-cutting gap is that documentation is decoupled from -KubeVirt's release cadence. The site publishes a single "latest" build from -`main` with no versioning tooling (such as `mike`) or version selector, so -readers running an older release cannot find documentation that matches their -deployment. This is compounded on the process side, where nothing requires -user-facing feature changes in `kubevirt/kubevirt` to ship with corresponding -user-guide updates, which risks content drift over time. Adopting MkDocs -versioning and establishing an expectation—such as a release checklist item or a -cross-repository issue link—that features land together with their documentation -would be the highest-impact investment for this section. Kubernetes is a good -model of versioned CNCF documentation. - -A second theme is that users lack clear guided paths into and through the -content. New-user material is fragmented across differently named locations—a -top-level "Quickstarts" entry, an "Installation" page buried under "Cluster -Administration," and "Try it out" and "KubeVirt Labs" sections on the -homepage—none of which is labeled "Getting Started," and the guide leans on -external labs rather than a self-contained, first-VM walkthrough. Similarly, -when a task page falls short, help is scattered across individual feature pages -with no consolidated troubleshooting or FAQ entry point. Consolidating a single -"Getting Started" section, adding an in-guide end-to-end tutorial with an -explicit "Next steps" pointer from installation to first use, and creating a -symptom-based troubleshooting hub would give users a predictable path from setup -through to problem resolution. - -Finally, the guide would benefit from light language and consistency polish -backed by automation. Although naming is inclusive, minimizing words such as -"simple" and "easy" appear roughly 80 times and can discourage readers who find -a task harder than described; replacing them with concrete, factual descriptions -would improve tone without losing information. Normalizing the minority of -noun-based task headings into goal-oriented verb phrases would further improve -scanning and consistency. Extending the existing spell checks—or adding a -dedicated inclusive-language linter or a Vale style rule in CI—would keep both -language and future contributions consistent, building on the solid foundation -this section already demonstrates. +# Project Documentation - Overall Comment + +The KubeVirt user guide meets CNCF standards for project documentation. Its +foundations are sound: content is organized by audience and layer with +deliberate ordering and preserved URLs, feature coverage is broad and kept +current by the developers who ship the features, the toolchain is simple and +searchable, documentation is a required checklist item in both the +kubevirt/kubevirt pull request template and the VEP release process, and +KubeVirt-controlled names avoid non-recommended terminology. Where pages have +been written or revised recently they follow a consistent, pasteable pattern. +The guide is a reliable reference for someone who already knows what they are +looking for. + +The most important cross-cutting gap is the absence of a guided path for new +users. Information architecture and new user content both find that the happy +path from install to a running, reachable VM is spread across five pages in two +sections and delegated to external Killercoda scenarios and kubevirt.io labs. +Installation buries its four-command procedure under advanced and legacy content +and ends without a next step, the foundational Basic Use and Lifecycle pages are +dated, VMI-centric, and reference a manifest that is never shown, and `virtctl` +install covers only Linux amd64. A single "Getting started" page that strings +the existing content together, plus a restructured Installation page with a +"Next steps" section, would address findings in two of the five areas at once. + +The second theme is that the project's processes are real but undocumented, +which puts maintainability at risk as the project grows. Release branches exist +for v1.7 through v1.9, yet the site publishes `main` only, has no version +selector, and no document explains the branching or cherry-pick workflow. +Ownership is clear from `OWNERS` files but there is no MAINTAINERS file, no +named documentation lead, and no record of who runs the Netlify deployment or +the release-notes script. The per-SIG reviewer aliases are defined but never +routed to directories, and a backlog of twelve open pull requests suggests +review capacity is limited to core maintainers. A documentation contributor +guide covering review flow, versioning, and ownership would close most of these +gaps in one document. + +The third theme is inconsistency between older and newer content, which surfaces +in every area. Older pages use `$`-prefixed code blocks mixed with output while +newer ones use clean fenced blocks; feature-state banners appear on a minority +of pages; minimizing words such as "simply" and "easily" appear on 40 percent of +pages; and legacy content (OKD Service Catalog, k3OS, a duplicate Windows +drivers page, an orphaned Plugins page, 14 links to the legacy +`/api-reference/master/` path) remains alongside current material. A short style +guide, a standard feature-state admonition, enabling the theme's copy button, +and a lint check for minimizing language are low-effort changes that would raise +consistency across the whole guide and prevent regression. + +Inclusive language is the section's strongest area and can serve as an example: +the project's own APIs, CLI, and feature gates are clean, "allowlist" is used +consistently, and the remaining issues are mechanical link updates and prose +tightening rather than naming changes. #### Overall (Author) @@ -699,78 +702,126 @@ the following: - Is there a clearly documented (ongoing) contribution process for documentation? - Yes. `docs/contributing.md` explains the ongoing GitHub workflow (fork, - branch, commit, open pull request, review, merge), explicitly lists the - user-guide repository as a low-barrier target for first contributions, and - links to community resources such as the Code of Conduct, membership policy, - and governance. The repository README complements this with the local - authoring workflow: where content lives (`./docs`), how to sign commits, and - how to validate changes with `make` targets for spelling and link checking - (HTMLProofer) before opening a PR. + Partially. The repository README documents the mechanics: fork, edit Markdown + under `docs/`, keep `.nav.yml` ordering current, sign commits with `-s`, run + `make build_img`, `make check_spelling`, `make check_links`, and `make run` in + a container, then open a pull request. The root CONTRIBUTING.md is a two-line + pointer to the Contributing page on the published site, and that page covers + community-wide onboarding (prerequisites, where to find good-first-issues, the + Code of Conduct, membership policy, governance, and the AI contribution + policy) with the user guide listed as a low-barrier repository. + + The process stops at "open a PR". Nothing in the repository describes what + happens next: which labels are applied, who is expected to review, what the + approval flow is, how long a contributor should expect to wait, or when to use + the release branches. There is no documentation style guide, page template, or + guidance on when a change needs a redirect entry in `mkdocs.yml`. The + repository has no pull request or issue templates under `.github/`. Twelve + pull requests are open, the oldest from March 2026. - Does the code release process account for documentation creation & updates? - Not explicitly. The user guide lives in a separate repository - (`kubevirt/user-guide`) and is published continuously from the `main` branch - to kubevirt.io/user-guide rather than being cut alongside KubeVirt code - releases. While a `release_notes.md` page tracks product releases, there is no - documented mechanism in this repository that requires documentation to be - created or updated as part of the core code release process, so docs updates - are decoupled from the release cadence. + Yes. The kubevirt/kubevirt pull request template includes a checklist item + that a user-guide update "was considered and is present (link) or not + required" for any user-facing feature or API change, and approvers are asked + to review the list. The Virtualization Enhancement Proposal (VEP) process in + kubevirt/enhancements requires SIGs, after code freeze, to confirm that the + "Docs PR is merged (plan review ahead of release if only placeholder is + opened)" as part of the release tracking checklist. + + The process is visible in practice. Recent merged pull requests include VEP + 190 plugins documentation, GPU DRA, Migration Stall Detector alpha docs, + PersistentReservation GA graduation, Template Beta graduation, and the v1.9.0 + release notes, most authored by the feature developers themselves. Release + notes are regenerated from kubevirt/kubevirt tags with `update_changelog.sh`. + Neither the PR checklist item nor the VEP requirement is enforced by tooling, + and the user guide repository itself does not document how its + `release-vX.Y-*` branches relate to the KubeVirt release cycle. - Who reviews and approves documentation pull requests? - Reviews and approvals are governed by Kubernetes-style OWNERS files enforced - through Prow. The root `OWNERS` delegates to `reviewers` and `approvers` - aliases defined in `OWNERS_ALIASES`. Subdirectories under `docs/` delegate to - the relevant SIG teams—for example `docs/storage/OWNERS` routes to sig-storage - reviewers and approvers. Documentation PRs are automatically labeled - `kind/documentation`, and merges require an approver's `/approve` plus - reviewer `/lgtm`. + Prow, using the `OWNERS` and `OWNERS_ALIASES` files. The root `OWNERS` file + assigns every path to the `reviewers` alias (seven people) and the `approvers` + alias (ten people), and automatically labels changes under `docs/` with + `kind/documentation`. `OWNERS_ALIASES` also defines per-SIG reviewer and + approver groups for network, storage, compute, observability, release, test, + scale, and buildsystem, but the `OWNERS` file does not route any directory to + them, so SIG experts are not auto-assigned to pages in their area. Pre-submit + and post-submit Prow jobs for the repository are defined in + kubevirt/project-infra. + + The reviewer and approver lists are made up of KubeVirt core maintainers + rather than documentation specialists, and one contributor is the most + frequent committer over the last six months and authored the v1.9.0 release + notes and site fixes. The process is discoverable only by reading the `OWNERS` + files; no human-readable page names the documentation approvers or explains + the Prow `/lgtm` and `/approve` flow to a first-time contributor. - Does the website have a clear owner/maintainer? - Yes. Ownership is clearly defined through the repository's `OWNERS` and - `OWNERS_ALIASES` files, which name active reviewers and approvers (and list - emeritus approvers for historical context). Per-section `OWNERS` files under - `docs/` further assign responsibility to the appropriate KubeVirt SIGs, giving - the site both overall and area-specific maintainers. + Partially. The user guide is owned collectively by the `approvers` alias in + `OWNERS_ALIASES`, the site builds on Netlify from `main` (badge in the README, + configuration in `netlify.toml`), and the `OWNERS` file labels changes under + `site/` with `kind/website`. Seven emeritus approvers are listed, showing the + list is curated over time. The main website, kubevirt.io, is a separate + repository (kubevirt/kubevirt.github.io) with its own ownership. + + There is no MAINTAINERS file, no named documentation lead or SIG Docs, and no + statement on the Contributing page or README of who is responsible for the + user guide's infrastructure, the Netlify account, or the release-notes + process. Ownership is inferable from Git history and OWNERS files but is not + documented. ##### Comment -The KubeVirt User Guide has a clear and welcoming content creation process. The -`docs/contributing.md` page lays out the standard GitHub workflow (fork, branch, -commit, pull request, review, merge), explicitly flags the user guide as a good -target for first-time contributors, and links to essential community documents -such as the Code of Conduct, membership policy, and governance. The README -reinforces this with practical authoring guidance: where content lives, how to -sign commits, and how to validate changes locally with `make` targets that run -spelling and link (HTMLProofer) checks. Together these give new and returning -contributors a well-signposted, repeatable path to landing changes. - -Ownership and review are handled robustly through Kubernetes-style OWNERS files -enforced by Prow. The root `OWNERS` and `OWNERS_ALIASES` define active reviewers -and approvers, while per-section `OWNERS` files under `docs/` delegate to the -appropriate KubeVirt SIGs (for example, `docs/storage` routes to the storage -SIG). This gives the site both overall and area-specific maintainers, and -automatic `kind/documentation` labeling keeps documentation PRs easy to triage. -The one caveat worth surfacing to contributors is that this OWNERS/Prow approval -model is not described in the user guide's own contribution docs; a short note -in `contributing.md` explaining how `/lgtm` and `/approve` work, and who to -expect review from, would make the approval path more transparent to newcomers. - -The most actionable gap is the relationship between the code release process and -documentation. Because the user guide is a separate repository published -continuously from `main`, documentation updates are decoupled from KubeVirt's -release cadence, and nothing in the process requires feature changes to ship -with corresponding docs. This risks documentation drift as the API and features -evolve. The project should consider documenting an expectation that user-facing -changes in `kubevirt/kubevirt` include or track a companion user-guide -update—for example, a release checklist item or a cross-repository issue link—so -that documentation creation is an accountable part of shipping features rather -than an afterthought. +KubeVirt's strongest asset in this area is that documentation is wired into the +engineering process rather than left to chance. The kubevirt/kubevirt pull +request checklist asks every author whether a user-guide update is needed, and +the VEP process requires SIGs to confirm the docs PR is merged before release. +Recent history shows this works: feature developers routinely land the user +guide page for their VEP in the same release cycle, and the release notes are +regenerated on each release. Reviews and approvals are automated through Prow +OWNERS files with a curated approver list. Compared with the Thanos "How to +contribute to docs" page and the NATS MAINTAINERS file that the CNCF criteria +cite as good examples, KubeVirt has stronger release-process coupling but weaker +documentation of the process itself. + +The weakness is that the process is implicit. A new contributor reading README +and CONTRIBUTING learns how to build the site and sign a commit but not who will +review, how approval works, how long to expect, what a good page looks like, or +when a change needs a redirect or a cherry-pick to a release branch. Ownership +is real but undocumented: no MAINTAINERS file, no named docs lead or SIG, and no +statement of who runs the Netlify deployment or the release-notes script. The +per-SIG aliases in `OWNERS_ALIASES` are defined but never used to route reviews, +so a storage or network expert is not automatically assigned to pages in their +area. Twelve open pull requests, the oldest six months old, suggest review +capacity depends on a small group of core maintainers who also carry the code. -Rating: 4 - Meets or exceeds standards +Strengths: + +- The kubevirt/kubevirt PR template and the VEP release checklist both require a + user-guide update to be considered and merged. +- Feature developers author the documentation for their features in the same + release cycle. +- Prow OWNERS automation with a curated approver list, emeritus tracking, and + automatic `kind/documentation` labeling. +- README documents local build, spell check, link check, and DCO sign-off. +- Release notes are generated by a script from upstream tags. + +Weaknesses: + +- No documented review and approval flow, expected turnaround, or explanation of + Prow commands for documentation contributors. +- No documentation style guide, page template, or guidance on redirects and + release branches. +- No MAINTAINERS file or named documentation owner; infrastructure ownership + (Netlify, release-notes script) is undocumented. +- Per-SIG reviewer aliases exist but are not mapped to directories in `OWNERS`. +- Root CONTRIBUTING.md is a pointer; the repository has no PR or issue + templates. +- Backlog of twelve open pull requests, some six months old. + +Rating: 3 - Meets standards #### Inclusive language @@ -778,69 +829,90 @@ Creating inclusive project communities is a key goal for all CNCF projects. We evaluate on the following: - Are there any customer-facing utilities, endpoints, class names, or feature - names that use non-recommended words as documented by the - [Inclusive Naming Initiative](https://inclusivenaming.org) website? - - No. A search of the documentation found no KubeVirt-defined utilities, - endpoints, class names, or feature names that use non-recommended terms, and - no occurrences of words such as "slave", "whitelist", "blacklist", "sanity - check", "grandfathered", or "man-in-the-middle". The word "master" does - appear, but only in contexts KubeVirt does not own: external URLs and Git - branch names (for example `.../blob/master/...`), version path segments in the - API reference (`api-reference/master/...`), a third-party CNI/bonding - configuration field (`"master": "eth1"`), a Kubernetes node-label example - (`kubevirt.io/nodeName: master`), and verbatim QEMU/libvirt command output - (`masterKey0`, `master-key.aes`). None of these are customer-facing names - coined by the project, so no renaming action is required within the guide. + names that use non-recommended words as documented by the Inclusive Naming + Initiative website? + + No, within KubeVirt's own naming. The KubeVirt API, CRDs, components + (`virt-api`, `virt-controller`, `virt-handler`, `virt-launcher`), `virtctl` + subcommands, and feature gates documented in the user guide do not use + "master", "slave", "whitelist", "blacklist", or other Inclusive Naming + Initiative tier-1 terms. The kubevirt/kubevirt default branch is `main`, and + the guide already uses the recommended replacement "allowlist" when describing + `permittedHostDevices`. The kubevirt.io home page is also free of these terms. + + The word "master" does appear 28 times in the guide, but almost entirely in + URLs and third-party content rather than in KubeVirt-controlled names. + Fourteen occurrences are links to the KubeVirt API reference at + `kubevirt.io/api-reference/master/...`; the API reference site now publishes + under `main` and per-version paths, so these links point at a legacy path. The + rest are links into upstream repositories (libvirt, Kubernetes enhancements, + cri-tools, vhost-md, QEMU, kubevirt-ansible) that still use a `master` branch, + a CNI configuration field named `master` in a live migration example, a QEMU + process listing, and a `kubevirt.io/nodeName: master` node label in an example + on the deprecated Presets page. "Abort" appears in the Live Migration page, + both as prose and as the `Abort Requested` and `Abort Status` field names from + the VirtualMachineInstanceMigration status. "Kill" appears once in prose on + Interfaces and Networks describing kubelet behavior. - Does the project use language like "simple", "easy", etc.? - Yes. Minimizing language is common throughout the documentation, with roughly - 80 occurrences of "simple", "simply", "easy", or "easily" across dozens of - pages (in addition to frequent use of "just"). Many are in explanatory prose - that judges difficulty on the reader's behalf—for example "allows easy - creation of", "which can be simply mounted", "switching the cloud-init data - source to ConfigDrive is as easy as", "it is easily fixed", and "updating ... - is as simple as". A smaller number are legitimate proper nouns or identifiers - that should not be changed, such as the passt project's "Plug A Simple Socket - Transport", the "PCI Simple" Windows device, and example resource names like - `simple-vm` and `simple-dv`. Replacing the subjective prose usages with - concrete descriptions (for example, stating the number of steps) would make - the documentation more inclusive of readers with varying experience levels. + Yes, frequently. Excluding the release notes, the guide contains 32 uses of + "simple", 28 of "simply", 12 each of "easy" and "easily", 19 of "just", four + of "of course", and one each of "obviously" and "trivial", across 39 of the 97 + pages. Typical examples are "Live migration can also be canceled by simply + deleting the migration object", "Attaching the virtio-win package can be done + simply by adding", "it can be easily cancelled", and "This is just a matter of + adding the name of the". + + These words are concentrated in older, longer pages such as Live Migration, + Windows Virtio Drivers, Node Assignment, and vsock. In most cases they add no + information and can be deleted without changing meaning. The guide has no + gendered pronouns, no "guys", and no other ableist or exclusionary terms in + prose. The repository's spelling check does not include an inclusive-language + or minimizing-language rule, so nothing prevents new occurrences. ##### Comment -The KubeVirt User Guide scores well on naming inclusivity. A review of the -documentation found no KubeVirt-defined utilities, endpoints, class names, or -feature names that use non-recommended terms from the Inclusive Naming -Initiative, and no occurrences of words such as "slave", "whitelist", -"blacklist", or "sanity check". The term "master" does appear, but exclusively -in contexts the project does not control—external URLs and Git branch names, -version path segments in the API reference, a third-party CNI bonding field -(`"master": "eth1"`), a Kubernetes node-label example, and verbatim QEMU/libvirt -command output. Because none of these are names coined by KubeVirt, no renaming -is warranted; the guide is already clean on this dimension. - -The clearer opportunity is the pervasive use of minimizing language. Words like -"simple", "simply", "easy", and "easily" appear roughly 80 times across dozens -of pages, often in explanatory prose that judges difficulty on the reader's -behalf—for example "allows easy creation of", "which can be simply mounted", "as -easy as", and "is as simple as". This phrasing can unintentionally discourage -readers who find a task harder than described, and it rarely adds information. -The most actionable improvement is to replace these subjective qualifiers with -concrete, factual descriptions: state the number of steps, name the single -command involved, or simply remove the adjective. Care should be taken to -preserve legitimate proper nouns and identifiers, such as the passt project's -"Plug A Simple Socket Transport", the "PCI Simple" Windows device, and example -resource names like `simple-vm`. - -To make this sustainable, the project could add the flagged minimizing terms to -its existing spelling check checks or adopt a dedicated inclusive-language -linter in CI. Automating detection would keep new contributions consistent and -reduce the manual review burden, building on the strong naming foundation the -guide already demonstrates. +# KubeVirt inclusive language: comment + +The KubeVirt user guide is in good shape on inclusive naming. KubeVirt's own API +objects, components, CLI, and feature gates avoid all Inclusive Naming +Initiative tier-1 terms, the project's default branch is `main`, and the guide +already uses "allowlist" where the older term might have appeared. The remaining +occurrences of "master" are in URLs and third-party content, and the only one +under the project's control, the 14 links to the API reference at the legacy +`/master/` path, is a mechanical fix now that the API reference publishes under +`/main/` and per-version paths. Field names such as `Abort Requested` are part +of the KubeVirt API and are a question for the API maintainers rather than the +documentation. + +The one systemic concern is minimizing language. Words such as "simply", +"simple", "easy", "easily", and "just" appear over a hundred times across 40 +percent of pages. This language tells a reader who is struggling with a step +that the step should have been easy, and in almost every case it can be deleted +with no loss of meaning. Because the repository's spelling check has no rule for +these words, the pattern will continue in new pages unless a style rule or lint +check is added. -Rating: 3 - Meets standards +Strengths: + +- No Inclusive Naming Initiative tier-1 terms in KubeVirt-controlled names, + commands, or feature gates. +- "Allowlist" is used consistently for `permittedHostDevices`. +- No gendered pronouns or other exclusionary terms in prose. +- kubevirt.io home page is free of non-recommended terms. + +Weaknesses: + +- Over a hundred uses of "simple", "simply", "easy", "easily", and "just" across + 39 pages. +- Fourteen API reference links still use the legacy `/api-reference/master/` + path. +- A `kubevirt.io/nodeName: master` example remains on the Presets page. +- No style rule or automated check discourages minimizing language in new + content. + +Rating: 4 - Meets or exceeds standards ### Recommendations @@ -1029,46 +1101,74 @@ KubeVirt user guide. The following recommendations address the content creation process of the KubeVirt user guide. -- Document the OWNERS/Prow approval model directly in `contributing.md`, - including how `/lgtm` and `/approve` work and who contributors should expect - review from, so the approval path is transparent to newcomers. -- Establish and document an expectation that user-facing changes in - `kubevirt/kubevirt` ship with a companion user-guide update, for example - through a release checklist item or a cross-repository issue link, to reduce - documentation drift. -- Add documentation creation and updates as an accountable step in the code - release process so docs are no longer decoupled from KubeVirt's release - cadence. -- Preserve and continue to signpost the existing strengths—the clear - `docs/contributing.md` GitHub workflow, the README's local authoring and - validation guidance (spell check and HTMLProofer `make` targets), and the - per-section `OWNERS` delegation to KubeVirt SIGs. -- Keep the automatic `kind/documentation` labeling and per-section `OWNERS` - files current as new topic areas are added under `docs/`, so review - responsibility remains clearly assigned. +- Expand CONTRIBUTING.md from a pointer into a documentation contributor guide + that covers the full lifecycle: how to propose a change, how to build and test + locally (move the README build steps here), what happens after opening a PR + (labels, `/lgtm`, `/approve`, expected turnaround), when to add a redirect to + `mkdocs.yml`, and when a change needs a cherry-pick to a `release-vX.Y-stable` + branch. Model it on the Thanos "How to contribute to docs" page. +- Add a MAINTAINERS.md (or a "Maintainers" section on the Contributing page) + that names the user guide approvers, the person or group responsible for the + Netlify deployment and the release-notes script, and how to reach them. Model + it on the NATS site MAINTAINERS file. +- Add a short documentation style guide covering page structure (title, short + concept, feature-state banner, procedure, related links), the standard + feature-state admonition, code block conventions (fenced blocks, no `$` + prompts), Kubernetes object capitalization, and file naming. Link it from + CONTRIBUTING.md and the Contributing page. +- Add a pull request template to `.github/` with a checklist: `.nav.yml` updated + for new pages, redirect added for moved pages, spelling and link checks run, + feature-state banner present, and the related kubevirt/kubevirt PR or VEP + linked. +- Route reviews to subject-matter experts by adding per-directory `OWNERS` files + (for example `docs/network/OWNERS`, `docs/storage/OWNERS`, + `docs/compute/OWNERS`) that reference the existing `sig-network-*`, + `sig-storage-*`, and `sig-compute-*` aliases, while keeping the root approvers + for site-wide changes. +- Ask the maintainers to consider a documentation-focused reviewer role or SIG + Docs alias, so that writers who are not core code approvers can share the + review load and reduce the open PR backlog. +- Document the release-cycle touch points for the user guide on the Contributing + page: when a release branch is cut, that the VEP checklist requires the docs + PR to be merged by code freeze, and how the release notes page is regenerated + with `update_changelog.sh`. +- Triage the twelve open pull requests, closing or merging the oldest, and add a + stale-PR policy to CONTRIBUTING.md so contributors know what to expect. #### Inclusive language The following recommendations address the inclusive language of the KubeVirt user guide. -- Replace subjective minimizing qualifiers such as "simple", "simply", "easy", - "easily", and "just" with concrete, factual descriptions—for example, state - the number of steps, name the single command involved, or remove the adjective - entirely. -- Preserve legitimate proper nouns and identifiers when revising, such as the - passt project's "Plug A Simple Socket Transport", the "PCI Simple" Windows - device, and example resource names like `simple-vm` and `simple-dv`. -- Add the flagged minimizing terms to the existing spell check checks, or adopt - a dedicated inclusive-language linter or Vale style rule in CI, to automate - detection and keep new contributions consistent. -- Leave the "master" occurrences unchanged, since they appear only in contexts - the project does not own—external URLs and Git branch names, API reference - version paths, a third-party CNI bonding field, a Kubernetes node-label - example, and verbatim QEMU/libvirt command output. -- Maintain the strong naming foundation by continuing to avoid non-recommended - terms from the Inclusive Naming Initiative in any new KubeVirt-defined - utilities, endpoints, class names, or feature names. +- Remove or reword minimizing language across the guide. Delete "simply", + "just", "of course", and "obviously" where they add nothing, and replace + "easy" or "easily" with a concrete statement of what the step requires (for + example, change "can be easily cancelled" to "can be cancelled by deleting the + migration object"). Start with the pages that have the most occurrences: Live + Migration, Windows Virtio Drivers, Node Assignment, vsock, and Disks and + Volumes. +- Add a rule to the documentation style guide (see the content creation process + recommendations) that discourages "simple", "simply", "easy", "easily", + "just", and "obviously", with a one-line explanation of why. +- Add an automated check for minimizing and non-recommended language to the + Makefile and the Prow pre-submit, using a tool such as Vale with the + `write-good` style, or a grep-based check alongside `make check_spelling`, so + new occurrences are flagged in pull requests. +- Update the 14 links to `kubevirt.io/api-reference/master/...` to the `/main/` + path, or to a specific version path such as `/v1.9.0/`, so the guide no longer + points at a legacy branch name. +- Replace the `kubevirt.io/nodeName: master` example on the Presets page with a + neutral node name such as `node01`, or remove the example, since the page + documents a deprecated feature. +- Ask the KubeVirt API maintainers whether the `Abort Requested` and + `Abort Status` fields in the VirtualMachineInstanceMigration status are + candidates for a "cancel" alias in a future API version; until then, prefer + "cancel" in the prose of the Live Migration page while continuing to show the + field names as they appear in `kubectl` output. +- When upstream projects linked from the guide (libvirt, cri-tools, vhost-md, + kubevirt-ansible) rename their default branch, update the links; in the + meantime prefer tagged or permalink URLs so the branch name is not repeated in + the guide. ## Contributor documentation From 08ee85101a7860538a156f3420e9423bf0663221 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Thu, 24 Sep 2026 21:18:20 -0700 Subject: [PATCH 43/49] misc fixes Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/analysis.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/analyses/2026/kubevirt/analysis.md b/analyses/2026/kubevirt/analysis.md index bafc662f..b4279fd6 100644 --- a/analyses/2026/kubevirt/analysis.md +++ b/analyses/2026/kubevirt/analysis.md @@ -1,7 +1,7 @@ --- title: KubeVirt Documentation Analysis created: 2026-05-24 -modified: 2026-07-19 +modified: 2026-09-24 author: Bruce Hamilton --- @@ -133,8 +133,6 @@ Documentation rubric. #### Overall -# Project Documentation - Overall Comment - The KubeVirt user guide meets CNCF standards for project documentation. Its foundations are sound: content is organized by audience and layer with deliberate ordering and preserved URLs, feature coverage is broad and kept @@ -873,8 +871,6 @@ evaluate on the following: ##### Comment -# KubeVirt inclusive language: comment - The KubeVirt user guide is in good shape on inclusive naming. KubeVirt's own API objects, components, CLI, and feature gates avoid all Inclusive Naming Initiative tier-1 terms, the project's default branch is `main`, and the guide From 526b887fff9889158ffdbb113e528ace4e671b41 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Fri, 25 Sep 2026 20:39:58 -0700 Subject: [PATCH 44/49] all AI output incorporated Signed-off-by: Bruce Hamilton --- .cspell.yml | 8 + analyses/2026/kubevirt/analysis.md | 2487 ++++++++++++++++------------ 2 files changed, 1422 insertions(+), 1073 deletions(-) diff --git a/.cspell.yml b/.cspell.yml index bf46ef37..f4b2b8d5 100644 --- a/.cspell.yml +++ b/.cspell.yml @@ -84,3 +84,11 @@ words: - addvolume - linux - kubelet + - asciibinder + - Docomo + - dpal + - HSTS + - jekyll + - lunr + - redhat + - wordmark diff --git a/analyses/2026/kubevirt/analysis.md b/analyses/2026/kubevirt/analysis.md index b4279fd6..bad14756 100644 --- a/analyses/2026/kubevirt/analysis.md +++ b/analyses/2026/kubevirt/analysis.md @@ -1,7 +1,7 @@ --- title: KubeVirt Documentation Analysis created: 2026-05-24 -modified: 2026-09-24 +modified: 2026-09-28 author: Bruce Hamilton --- @@ -112,8 +112,6 @@ to legal requirements such as copyright and licensing issues. ## Project documentation -Section analysis by author unless otherwise indicated - KubeVirt is an **incubating** project of CNCF. This means that the project should be developing professional-quality documentation alongside the project code. @@ -126,13 +124,6 @@ code. | Content creation processes | 3 - Meets standards | | Inclusive language | 4 - Meets or exceeds standards | -### Comments - -The following sections contain assessments of each element of the Project -Documentation rubric. - -#### Overall - The KubeVirt user guide meets CNCF standards for project documentation. Its foundations are sound: content is organized by audience and layer with deliberate ordering and preserved URLs, feature coverage is broad and kept @@ -183,110 +174,10 @@ the project's own APIs, CLI, and feature gates are clean, "allowlist" is used consistently, and the remaining issues are mechanical link updates and prose tightening rather than naming changes. -#### Overall (Author) - -The KubeVirt has a well-thought out structure that can accommodate improvements -without having to restructure sections on a wide basis. - -The Welcome page has long lines in bullets could be better formatted for -readability and scanning. See the rest of overall comments by the Author in the -next section, "Comments of KubeVirt documentation sections." - -The following observations are author observations on the KubeVirt documentation -(https://kubevirt.io/user-guide) by its sections as shown on the top navigation -bar. - -AI comments for these sections are tasks defined in the KubeVirt-Analysis.csv -file, described later in Recommendations. - -Docs welcome page: - -- From the home page, selecting **Docs** from the top navigation tabs opens the - **KubeVirt User Guide** page - with the main sections of the documentation as - options on the top navigation tabs. This differs from having the navigation - tabs the choices of all of the web site. This is unusual, but not a negative - experience. -- Selecting the KubeVirt icon on the upper-left should return to home page but - stays on the same page. To return to the home page, you must use the browser. -- On the Welcome page, the bulleted list of selection descriptions needed - consistent editing would read better as a two-column table (table head not - needed). -- The **Try it out** heading should include "QuickStarts" (besides the URL) so - that the reader doesn't wonder if its something different. - -Architecture: - -- This page describes essentials and core concepts as expected for an - Architecture page but could be organized better to coordinate with the - graphics. The Application Layout subsection would be better closer to the top. - -- The diagram labeled "simplified version" would be better with its own - description. - -- The How to and When to use a virtual machine sections would be better placed - in getting started or as administration tasks. - -QuickStarts: - -- The Labs, which are used in conjunction with the Quickstarts, are not shown - until select a QuickStart. Labs should in the navigation bar. - -- Creating a VM for KubeVirt would be an obvious paramount QuickStart. But there - are currently two topics to do this. The user starts with either start with - "KubeVirt QuickStart with Kind" or "KubeVirt QuickStart with Minikube", - followed by "Use KubeVirt" to create the VM. Perhaps the could be one main - topic with references to Kind and MiniKube. Such thoughts may have been - considered before. - -Cluster Administration: - -- The top (first) page in the section, Installation, has guidance what would be - helpful in getting started content. -- A majority topics are reference and also how-to's. -- The "Confidential computing" topic might be better titled as "Encrypted - Virtualization". -- The "KubeVirt Tekton" topic might be better titled as "Tekton pipelines." - -User Workloads: - -- The top overview for this section should describe the concept of User - Workloads and how it's pertinent to KubeVirt, such as to use workload - partitioning to accommodate resources spikes. -- The "Lifecycle" topic contains useful How-to guidance on VMs with Kubectl. -- The "Basic Use" topic has useful KubeVirt intro content. -- Helpful `virtctl` summary guidance could be aggregated from `virtctl in the - title.split computing -- The "Templates" and "Virtual Machine Templates" share the same content. - -Compute: - -- The topics comprise a variety of tasks that read well and have needs for - mostly tasks such as defining terms and providing examples. Adding subsections - to the left-side navigation bar could be helpful for discovery. - -Network and Storage: - -- Essentially reference content. Task-based titles could help discovery. - -Release notes: - -- A unusual prominent location for release notes, but clearly convenient. - Improvements suggests could be formatting, consistency edits, and perhaps data - aggregation. - -Contributing: - -- Provide an engaging page about ways to contribute. A large part of the content - could be in a more discoverable two-column table of links and descriptions. - -Virtualization Debugging: - -- Specifies the page is about KubeVirt debugging, so having "Virtualization" in - the title makes it seem like it might be subset of KubeVirt debugging. - -- Overview needs examples of debugging scenarios. +The following sections contain assessments of each element of the Project +Documentation rubric. -#### Information architecture +### Information architecture The overall structure (pages/subpages/sections/subsections) of your project documentation. We evaluate on the following: @@ -422,7 +313,7 @@ documentation. We evaluate on the following: pages exist outside the navigation. Release Notes, a 3,000-line page, sits in the main navigation between Storage and Contributing. -##### Comment +#### Comment The KubeVirt user guide has a sound top-level information architecture. Content is grouped by audience and layer (Cluster Administration, User Workloads, @@ -487,7 +378,7 @@ Weaknesses: Rating: 3 - Meets standards -#### New user content +### New user content New users are the most avid users of documentation, and need content specifically for them. We evaluate on the following: @@ -547,7 +438,7 @@ specifically for them. We evaluate on the following: `virtctl create vm` invocations, `kubectl` lifecycle commands, and YAML manifests. These are formatted for direct copy-paste. -##### Comment +#### Comment The KubeVirt user guide gives new users a solid technical starting point, but its on-ramp is fragmented across several differently named locations. New-user @@ -582,7 +473,7 @@ machine, would give new users an unbroken path from setup to a working workload. Rating: 3 - Meets standards -#### Content maintainability & site mechanics +### Content maintainability & site mechanics As a project scales, concerns like localized (translated) content and versioning become large maintenance burdens, particularly if you don’t plan for them. We @@ -639,7 +530,7 @@ evaluate on the following: (`update_changelog.sh`) that regenerates the page from kubevirt/kubevirt tags, but that process is also undocumented outside the script itself. -##### Comment +#### Comment The KubeVirt user guide is maintainable as a single-version, single-language site. Its toolchain is simple and well suited to a documentation-only @@ -691,7 +582,7 @@ Weaknesses: Rating: 3 - Meets standards -#### Content creation processes +### Content creation processes Documentation is only as useful as it is accurate and well-maintained, and requires the same kind of review and approval processes as code. We evaluate on @@ -770,7 +661,7 @@ the following: process. Ownership is inferable from Git history and OWNERS files but is not documented. -##### Comment +#### Comment KubeVirt's strongest asset in this area is that documentation is wired into the engineering process rather than left to chance. The kubevirt/kubevirt pull @@ -821,7 +712,7 @@ Weaknesses: Rating: 3 - Meets standards -#### Inclusive language +### Inclusive language Creating inclusive project communities is a key goal for all CNCF projects. We evaluate on the following: @@ -869,7 +760,7 @@ evaluate on the following: prose. The repository's spelling check does not include an inclusive-language or minimizing-language rule, so nothing prevents new occurrences. -##### Comment +#### Comment The KubeVirt user guide is in good shape on inclusive naming. KubeVirt's own API objects, components, CLI, and feature gates avoid all Inclusive Naming @@ -910,42 +801,9 @@ Weaknesses: Rating: 4 - Meets or exceeds standards -### Recommendations - -#### Overall (Author) - -The AI results capture my recommendations except for the following pressing -needs I see as a novice user: - -- Risks of embedded virtualization - - Guidance and frank advice about using a virtual machine on a Windows or MacOS - to then use a virtual machine in KubeVirt. This VM within a VM is nested - virtualization and is a key concept for getting to understand KubeVirt. Users - who have a Linux machine don't need to worry about nested virtualization. In - addition, VMs on Windows and MacOS are usually transitory, requiring the - reinstall of clusters, tools, and KubeVirt. This guidance should be in the top - overview or getting started section. - -- Add a Roadmap topic - - The AI results include having a common prerequisites topic, but at a higher - level a Roadmap topic or subsection of Getting Started should provide guidance - for different user scenarios to decide whether to use a VM in Windows or - invest in a Linux computer. While this isn't pertinent to develops, it will - save a lot of time for other users to get on the right path as soon as - possible. - -- Add architectural diagrams +## Project documentation - Recommendations - Diagrams should be updated in the Architecture topic and added to Quickstarts - and Getting Started content and ideally for each major section. Mermaid code - is recommended and be created initially by AI. - -#### Information architecture - -The following recommendations address the information architecture of the -KubeVirt user guide. +### Information architecture - Add a "Getting started" page to the User Workloads section (or expand Basic Use into one) that walks through the happy path on a single page: install @@ -1005,10 +863,7 @@ KubeVirt user guide. of the list or into a top-bar link, so the section list reads as a progression from concepts through administration, workloads, and infrastructure layers. -#### New user content - -The following recommendations address the new user content of the KubeVirt user -guide. +### New user content - Add a "Getting started" page, placed immediately after Architecture in the top-level navigation, that walks a new user from a working cluster to a @@ -1054,10 +909,7 @@ guide. top that points to the Getting started page, so the first-run path is discoverable without reading the section list. -#### Content maintainability & site mechanics - -The following recommendations address the content maintainability of the -KubeVirt user guide. +### Content maintainability & site mechanics - Document the content versioning model in CONTRIBUTING.md (and summarize it on the Contributing page). State what the `release-vX.Y-stable` and @@ -1092,10 +944,7 @@ KubeVirt user guide. user guide search to a site-wide index, so users can search the full documentation set from one place. -#### Content creation processes - -The following recommendations address the content creation process of the -KubeVirt user guide. +### Content creation processes - Expand CONTRIBUTING.md from a pointer into a documentation contributor guide that covers the full lifecycle: how to propose a change, how to build and test @@ -1131,10 +980,7 @@ KubeVirt user guide. - Triage the twelve open pull requests, closing or merging the oldest, and add a stale-PR policy to CONTRIBUTING.md so contributors know what to expect. -#### Inclusive language - -The following recommendations address the inclusive language of the KubeVirt -user guide. +### Inclusive language - Remove or reword minimizing language across the guide. Delete "simply", "just", "of course", and "obviously" where they add nothing, and replace @@ -1174,63 +1020,66 @@ code. | Criterion | Rating (1-5) | | ----------------------------------------- | ------------------------------ | -| Communication methods documented | 3 - Meets standards | -| Beginner friendly issue backlog | 3 - Meets standards | -| "New contributor" getting started content | 4 - Meets or exceeds standards | +| Communication methods documented | 4 - Meets or exceeds standards | +| Beginner friendly issue backlog | 2 - Needs improvement | +| "New contributor" getting started content | 3 - Meets standards | | Project governance documentation | 4 - Meets or exceeds standards | -### Comments - -KubeVirt's contributor documentation is in good overall shape, rating between -"meets standards" and "meets or exceeds standards" across the four criteria. Its -strongest assets are a well-organized onboarding path and mature governance: the -user guide's Contributing page acts as a single, canonical entry point covering -prerequisites, a clear "Your first contribution" section, and separate tracks -for documentation and code, while the `kubevirt/community` repository provides -comprehensive, CNCF-aligned governance through `GOVERNANCE.md`, a maintained -`MAINTAINERS.md`, and a well-defined contributor ladder. The essential -communication channels—Slack, the kubevirt-dev mailing list, and the issue -tracker—are documented and correctly linked. No structural overhaul is needed; -the recommended improvements are additive. - -The highest-impact gap is that the beginner-friendly issue backlog is -effectively empty, and this weakness undermines the otherwise excellent -onboarding content. Both the beginner-backlog and new-contributor analyses found -that the Contributing page tells newcomers to look for `good-first-issue` items, -yet at review time there were no open beginner issues in either the user-guide -or core repository, so a motivated first-timer who follows the documentation -reaches a dead end. This is compounded by a fixable labeling inconsistency—the -team applies the hyphenated `good-first-issue` label while GitHub's native -"Contribute" experience and discovery tooling key off the standard spaced -`good first issue`, hiding the project's real beginner issues. Curating a small -pool of triaged beginner issues and consolidating on the standard label would -let the strong onboarding path deliver on its promise. - -A second cross-cutting theme is discoverability from within the user guide -itself. Governance is reachable only through a single "Important community -resources" list on the Contributing page, with no dedicated community or -governance entry in the site navigation; project meetings are absent from the -guide entirely and documented only on the external community page; and the -"Getting help" section is a thin, inconsistent list that omits the community -page and the `#kubevirt-dev` Slack channel that appear elsewhere. Because so -much contributor-facing information lives outside the guide or is scattered -within it, a reader who stays on the documentation site can miss where to ask -questions, when meetings happen, or how the project is governed. - -Addressing these two themes together would move the section from good to strong. -Consolidating the communication channels, meeting cadence and calendar, and -governance pointers into a single, clearly labeled community landing area—each -channel given a one-line description of its purpose—would resolve the -discoverability gaps across three of the four areas at once. Pairing that with a -light triage pass that keeps a curated set of beginner issues open would close -the backlog gap. The underlying content is comprehensive and current; the -remaining work is largely about surfacing and maintaining it where contributors -are already reading. +KubeVirt's contributor documentation is strong at the community level and uneven +at the point where a newcomer actually tries to contribute. The +kubevirt/community repository is a model of its kind: governance with concrete +voting thresholds and maintainer selection rules, a full contributor ladder with +an inactivity policy, generated SIG lists, a detailed weekly meeting document, +and a help-wanted label guide. Communication channels are established and +active, with two purpose-specific Slack channels, a mailing list, a public +calendar, and recorded meetings, all gathered on the kubevirt.io Community page. +The user guide's Contributing page is a genuine, welcoming first-contribution +document and is the canonical entry point that both the repository and the +community repo point to. + +The highest-impact gap is that the path the Contributing page describes leads +nowhere. It tells newcomers to look for `good-first-issue`, but the label has +zero open items in kubevirt/user-guide and zero documentation-related items in +kubevirt/kubevirt, because every beginner issue closed in the past year was +auto-closed by the stale bot rather than fixed, including a well-written batch +of eight feature-lifecycle documentation tasks. Half of the small open backlog +is unlabeled and nothing is assigned or marked `triage/accepted`, so lifecycle +automation runs without a human deciding what should survive it. Reopening and +freezing that batch, seeding a standing set of single-page starter tasks, and +exempting beginner-labeled issues from auto-close would move this area from +needs-improvement to meets-standards quickly. + +The second cross-cutting theme is that excellent material in kubevirt/community +is not surfaced where users and contributors look. Three of the four areas note +the same pattern: governance, the maintainers list, and the SIG list are not +linked from the kubevirt.io Community page; the community meeting's day, time, +and join link appear only in the community repository; the help-wanted guide and +MAINTAINERS file are not linked from the guide; and the user guide's own +"Getting help" section is three bare URLs on the Welcome page with no guidance +on which channel suits which question and no mention of `#kubevirt-dev`. The +mkdocs-material header and footer carry no repository or social icons because +`repo_url` and `extra.social` are unset. Fixing these is largely a matter of +adding links and one-sentence descriptions. + +The third theme is the missing hand-off from motivation to mechanics. The +Contributing page ends before explaining how to claim an issue, fork, sign off, +open a pull request, or interpret Prow labels, and it names no channel, person, +or meeting where a stuck contributor can ask for help. Those mechanics exist in +the repository README and in kubevirt/kubevirt's CONTRIBUTING.md and +getting-started guide but are not presented as the next step. A "Making your +first documentation change" section and a "Where to ask for help" section on the +Contributing page, drawing on content that already exists, would close this gap +and reinforce the beginner backlog and communication fixes above. + +Project governance is the section's strongest area and, alongside the +communication infrastructure, shows that the project has done the hard +organizational work. The remaining effort is editorial and operational: link +what exists, keep the beginner backlog alive, and finish the Contributing page. The following sections contain brief assessments of each element of the Contributor Documentation rubric. -#### Communication methods documented +### Communication methods documented One of the easiest ways to attract new contributors is making sure they know how to reach you. We evaluate on the following: @@ -1238,170 +1087,240 @@ to reach you. We evaluate on the following: - Is there a Slack/Discord/Discourse/etc. community and is it prominently linked from your website? - Yes. The user guide's home page links directly to the KubeVirt Slack channel - (`https://kubernetes.slack.com/messages/virtualization`) in its "Getting help" - section, and the Contributing page invites readers to "participate on Slack" - through the KubeVirt community page. The broader project website - (`https://kubevirt.io/community/`) also surfaces the Slack workspace and - channels alongside a forum. Within the user guide, the Slack link is - reasonably visible on the landing page, but it appears only in a short - "Getting help" list rather than in the persistent site navigation, so its - prominence is limited. + Yes. KubeVirt uses two channels in the Kubernetes Slack workspace, + `#virtualization` for users and `#kubevirt-dev` for contributors. The + kubevirt.io home page links to Slack in its footer, and the kubevirt.io + Community page has a "Talk to Us!" section that names both channels, links to + each, and links to the Kubernetes Slack invitation page so a newcomer can get + an account. The kubevirt/community README repeats both channel links. + + In the user guide the link is less prominent. The Welcome page has a "Getting + help" section that links to `#virtualization` (as a raw URL rather than a + channel name), the GitHub issue tracker, and the mailing list; the + Contributing page mentions Slack in passing and points to the Community page. + The `#kubevirt-dev` channel is not mentioned in the guide. No other page in + the guide links to Slack, and the mkdocs-material header and footer do not + carry social or chat icons because `extra.social` and `repo_url` are not + configured in `mkdocs.yml`. - Is there a direct link to your GitHub organization/repository? - Yes. The Contributing page links to the KubeVirt GitHub organization - (`https://github.com/kubevirt`) and to individual repositories such as - `user-guide`, `kubevirt`, `containerized-data-importer`, and `community`. The - home page's "Getting help" section links directly to the issue tracker - (`https://github.com/kubevirt/kubevirt/issues`). Direct GitHub links appear - consistently throughout the guide. + Yes. The kubevirt.io home page and Community page link to the GitHub + organization (github.com/kubevirt) and to the main kubevirt/kubevirt + repository. The user guide's Welcome page links to the kubevirt/kubevirt issue + tracker under "Getting help" and to the API reference under "Developer", and + every page has "Edit this page" and "View source" actions that resolve to the + kubevirt/user-guide repository. The Contributing page links to the + organization, to the user-guide, kubevirt.github.io, community, kubevirt, and + containerized-data-importer repositories, and to their issue lists. + + The user guide does not display a repository link in its header, which + mkdocs-material provides when `repo_url` is set. A reader must reach the + Welcome or Contributing page, or use the edit icon, to find the source + repository. - Are weekly/monthly project meetings documented? Is it clear how someone can join those meetings? - Not within the user guide itself. The guide does not state the cadence of - community meetings or provide direct joining instructions; instead, the - Contributing page defers to the community page to "learn about local meetups - and events." The linked community page (`https://kubevirt.io/community/`) does - document recurring community meetings and embeds a public Google Calendar - (`kubevirt@cncf.io`) that readers can use to join. However, someone reading - only the user guide would not find meeting times, cadence, or a join link - without following that external link. + Yes, in the community repository; only indirectly on the websites. The + kubevirt/community repository's `community_meeting.md` documents the weekly + community meeting in detail: Zoom meeting ID and join link, time (Wednesdays + 16:00 CET/CEST), hosts, the running meeting-notes document, how recordings are + produced and posted to the YouTube "Community Meetings" playlist, and that + minutes are mailed to kubevirt-dev. The kubevirt.io Community page embeds the + KubeVirt community calendar (`kubevirt@cncf.io`) and states that anyone may + "join any of our community meetings - no registration required." + + The user guide itself does not mention the community meeting, the calendar, or + SIG meetings; its Contributing page links to the Community page and to a New + Contributor session recording on YouTube. SIG charters in kubevirt/community + (for example `sig-network/charter.md`) do not list meeting times or channels, + so SIG meeting cadence is discoverable only through the shared calendar. - Are mailing lists documented? - Yes. The home page's "Getting help" section links to the kubevirt-dev mailing - list (`https://groups.google.com/forum/#!forum/kubevirt-dev`), which is also - reachable from the community page. The mailing list is documented, though it - is presented as a bare link without describing its purpose or how it differs - from Slack or the forum. - -##### Comment - -The KubeVirt user guide provides a solid foundation of communication links for -both users and contributors. The home page's "Getting help" section and the -Contributing page together surface the Slack channel, the kubevirt-dev mailing -list, the GitHub organization and its key repositories, and a pointer to the -wider community page. As a result, readers have clear starting points to reach -the project and its maintainers. - -The most significant gap is project meetings. The user guide does not document -meeting cadence, times, or how to join; it only links to the community page for -"meetups and events." Because those details live entirely on the external -community page, a reader who stays within the user guide cannot learn when -community meetings happen or how to attend. Adding a short "Community meetings" -subsection that names the cadence and includes the public calendar link would -close this gap and keep the information where contributors are already reading. - -Discoverability of the channels that are present could also be stronger. The -Slack, mailing list, and issue links appear only in a brief list near the bottom -of the landing page, and the Contributing page's community links are spread -across several sections. Consolidating these into a single, clearly labeled -"Community and communication" section—covering Slack, the forum, the mailing -list, meetings, and social accounts—would make them easier to find. Giving each -channel a one-line description of its purpose would also help newcomers choose -where to ask a question versus where to follow announcements. - -Overall, the essential channels are documented and correctly linked, but -meetings are absent from the guide itself and the presentation is uneven. Small, -well-placed additions would move this area from adequate to strong. + Yes. The kubevirt-dev Google Group is linked from the kubevirt.io home page + footer, the Community page, the kubevirt/community README, and the user + guide's Welcome page under "Getting help". The community meeting document + states that weekly minutes are posted to the list, and the kubevirt/kubevirt + pull request template asks authors to consider announcing changes there. + + The list is presented as a bare link with no description of its purpose, + expected traffic, or whether it is the right place for user questions versus + development discussion. There is no separate user-oriented list, and the guide + does not say so. The Contributing page does not mention the mailing list at + all. + +#### Comment + +KubeVirt's communication channels are well established and thoroughly documented +at the community level. Two Slack channels, a Google Group, a GitHub +organization, a public community calendar, a weekly Zoom meeting with recorded +sessions on YouTube, and posted minutes are all in place, and the +kubevirt/community repository describes the meeting mechanics in more detail +than most CNCF projects. The kubevirt.io Community page gathers the channels, +the calendar, and the Slack invitation link on one page, and the home page +footer repeats the primary links. + +The gap is in how the user guide surfaces these channels. A user who hits a +problem while following a page has no path to help except to return to the +Welcome page, where "Getting help" offers three bare URLs with no guidance on +which channel suits which question. The guide does not mention the +`#kubevirt-dev` channel, the community meeting, the calendar, or that meeting +minutes are mailed to kubevirt-dev, and the mkdocs-material header and footer +carry no repository or social icons because `repo_url` and `extra.social` are +not set. Meeting details live only in the community repository; the websites +present a calendar embed and a one-line invitation without stating the day, +time, or how to join. SIG charters do not record meeting cadence, so SIG-level +participation depends on scanning the shared calendar. -Rating: 3 - Meets standards +Strengths: + +- Two purpose-specific Slack channels, a mailing list, a public calendar, and a + weekly recorded meeting are all active and linked from kubevirt.io. +- `community_meeting.md` documents Zoom details, time, hosts, notes, recordings, + and minutes distribution in depth. +- The Community page links the Kubernetes Slack invitation page so newcomers can + get an account. +- Every user guide page has edit and view-source actions pointing at the + repository. +- The Contributing page links every relevant repository and issue list. -#### Beginner friendly issue backlog +Weaknesses: + +- The user guide's only help section is on the Welcome page and consists of bare + URLs without guidance on which channel to use. +- No repository, Slack, or mailing list icons in the guide's header or footer. +- The community meeting, calendar, and `#kubevirt-dev` channel are not mentioned + in the user guide. +- Meeting day, time, and join instructions appear only in the community + repository, not on kubevirt.io. +- SIG charters do not list meeting times or channels. + +Rating: 4 - Meets or exceeds standards + +### Beginner friendly issue backlog We evaluate on the following: - Are docs issues well-triaged? - Documentation issues are only partially triaged. At the time of review the - user-guide repository had four open issues, and three of them carried no - labels at all; only one was categorized (with `kind/enhancement`). The - repository does provide a complete triage label taxonomy (`kind/*`, - `triage/accepted`, `triage/needs-information`, `sig/documentation`, and - others), and closed issues show that labels such as `kind/bug` and - `kind/enhancement` were applied over time. However, `triage/accepted` is - rarely used, and the currently open backlog is largely uncategorized, so - triage is inconsistent in practice. + Partially. The kubevirt/user-guide repository has a full Prow label set + inherited from the KubeVirt organization: `kind/*`, `sig/*` (including + `sig/documentation`), `triage/accepted`, `triage/needs-information`, + `triage/duplicate`, and `lifecycle/*`. Org-level issue templates + (`bug_report.md`, `docs_report.md`, `feature_request.md`) prompt reporters for + structured information, and issues opened through them arrive with a + consistent shape. + + The labels are applied inconsistently. Of the four issues open today, two + carry a `kind/*` label and two carry no label at all; none has a `triage/*` or + `sig/*` label and none is assigned. The two unlabeled issues are a proposal + for Simplified Chinese documentation and a report that the Material theme is + reaching end of life, both of which have been open for months without a + maintainer response recorded in labels. Twelve issues were opened in the past + year, so the volume is small enough that complete triage is achievable. - Is there a clearly marked way for new contributors to make code or - documentation contributions (i.e. a “good first issue” label)? - - Yes, a mechanism exists and is documented, but it is currently underused. The - user-guide repository has a `good-first-issue` label that has been applied to - 24 issues historically, and the contributing page explicitly tells newcomers - to "look for any labeled 'good-first-issue', which are triaged to help new - contributors." Two caveats reduce its effectiveness. First, there are - currently zero open `good-first-issue` items in both the user-guide and the - core kubevirt/kubevirt repositories, so a new contributor arriving today finds - an empty beginner backlog. Second, the repository has two near-duplicate - labels — the hyphenated `good-first-issue` that the team actually uses and the - standard spaced `good first issue` that is unused — which is inconsistent and - prevents GitHub's native "Contribute" tab from surfacing these issues. + documentation contributions (i.e. a "good first issue" label)? + + Yes in form, no in substance. The repository defines both `good-first-issue` + and `good first issue` labels and a `help wanted` label, and the Contributing + page in the user guide tells newcomers to look for `good-first-issue` in the + user-guide, kubevirt.github.io, and community repositories. The Contributing + page also links a New Contributor session recording. + + There are currently zero open `good-first-issue` items in kubevirt/user-guide. + In kubevirt/kubevirt, nine `good-first-issue` items are open and none is + labeled `kind/documentation`, and no open kubevirt/kubevirt issue carries + `kind/documentation` at all. A newcomer who follows the Contributing page's + advice finds an empty list. Over the past year ten `good-first-issue` items + were closed in kubevirt/user-guide, including a well-scoped batch of eight + "Update ... Documentation to Reflect Feature Lifecycle Changes" issues (#918 + through #925) filed in September 2025; all ten were closed by the stale bot + with the `lifecycle/rotten` label rather than by a pull request. - Are issues well-documented (i.e., more than just a title)? - Yes. Issues generally contain substantive descriptions rather than bare - titles. Bug reports follow a template with **Description**, **What you - expected**, and **URL** sections, and enhancement requests use the - feature-request template. The open issues ranged from roughly 400 to nearly - 1,900 characters of body text; for example, the Simplified Chinese - documentation proposal includes detailed context about the contributing team - and scope. This indicates issues are typically actionable and provide enough - information to begin work. + Yes. All four open issues have bodies over 300 characters. The enhancement + issue #948 uses the feature request template, describes the problem (no clear + structure for newcomers), and proposes persona-based getting-started paths. + The closed `good-first-issue` batch was exemplary: each issue (for example + #918) had a summary, a background section citing the specific + kubevirt/kubevirt pull requests and versions that changed feature status, a + list of affected files, and acceptance criteria, at roughly 1,800 characters. + + Issue quality is therefore not the constraint. The well-documented beginner + issues expired unworked, which points to discoverability and follow-through + rather than to how issues are written. - Are issues maintained for staleness? - Yes, staleness is actively — and aggressively — managed by the shared KubeVirt - Prow automation. Issues progress through `lifecycle/stale` and - `lifecycle/rotten` and are then auto-closed, with `lifecycle/frozen` available - to exempt long-lived items. Many closed user-guide issues carry the - `lifecycle/rotten` label, and the core kubevirt/kubevirt repository currently - shows roughly 31 stale, 32 rotten, and 30 frozen open issues. The main risk is - that valid but unattended issues (including enhancements) are closed purely - for inactivity rather than being triaged or preserved, so the backlog stays - small partly through automated closure. - -##### Comment - -The KubeVirt user guide has the building blocks of a healthy beginner-friendly -issue backlog, but the pieces are not consistently applied. A dedicated -`good-first-issue` label exists and has been used on two dozen issues over time, -and the contributing page clearly tells newcomers to look for it. Issues are -generally well written: bug reports and feature requests follow templates with -description, expectation, and URL fields, so most issues give a contributor -enough context to start work rather than just a title. Staleness is handled -automatically through the shared Prow lifecycle bot, which moves inactive issues -through `lifecycle/stale` and `lifecycle/rotten` before closing them. - -The main gap is that the beginner backlog is effectively empty and the currently -open issues are under-triaged. At the time of review there were no open -`good-first-issue` items in either the user-guide or the core repository, so a -new contributor who follows the documentation's advice finds nothing to pick up. -Of the small number of open documentation issues, most carried no labels at all -— no `kind/*`, no `sig/documentation`, and no `triage/accepted` — which means -the backlog is not being actively categorized even though the label taxonomy is -available. - -A specific, fixable inconsistency is the presence of two near-duplicate labels: -the hyphenated `good-first-issue` that the team actually applies and the -standard spaced `good first issue` that sits unused. GitHub's native -"Contribute" experience and the good-first-issues discovery tooling key off the -standard spaced label, so the project's real beginner issues are invisible to -those channels. Consolidating on the standard label (or aliasing consistently) -would immediately widen discovery. - -Finally, the aggressive auto-close behavior deserves attention. Because inactive -issues — including valid enhancements — are closed as `lifecycle/rotten` rather -than triaged or frozen, the backlog stays small in part by discarding work -rather than curating it. A light triage pass that accepts, labels, and where -appropriate freezes beginner-suitable issues would turn the existing automation -and labels into a genuinely inviting on-ramp for new contributors. + Yes, mechanically. The KubeVirt Prow instance applies `lifecycle/stale` after + inactivity, then `lifecycle/rotten`, then auto-closes, and `lifecycle/frozen` + is available to exempt an issue. Of 21 issues closed in the past year, 15 (71 + percent) were closed by this automation rather than by a fix. No open issue is + older than about ten months and none has gone six months without an update, so + the backlog does not accumulate. + + The same automation removed every beginner-friendly issue in the repository. + The eight feature-lifecycle documentation issues were valid when filed and, as + far as the closing comments show, were still valid when the bot closed them + five months later; nobody applied `lifecycle/frozen` or `help wanted` to keep + them alive. Staleness handling is tuned for a code repository with active + triage and, without a human in the loop, it erases the entry points the + Contributing page advertises. + +#### Comment + +The KubeVirt user guide has the infrastructure for a beginner-friendly backlog +but not the backlog itself. The repository inherits the KubeVirt organization's +Prow labels, issue templates, and lifecycle automation; the labels a newcomer +needs (`good-first-issue`, `help wanted`, `sig/documentation`, +`triage/accepted`) all exist; and the Contributing page points newcomers at +`good-first-issue` in this and two sibling repositories. When maintainers have +written beginner issues, they have written them well: the September 2025 batch +of eight feature-lifecycle documentation issues each carried background, +affected files, and acceptance criteria. + +The problem is follow-through. All ten `good-first-issue` items closed in the +past year, including that entire batch, were auto-closed by the stale bot +without a fix, and today the label has zero open items here and zero +documentation-related items in kubevirt/kubevirt. A newcomer who follows the +Contributing page's instructions finds nothing to do. Triage labels are applied +to only half of the small open backlog, and no issue is assigned or marked +`triage/accepted`, so the lifecycle automation runs without a human deciding +which issues should survive it. The net effect is a clean but empty backlog, +which is the wrong outcome for a project that explicitly invites first-time +contributors to start with documentation. -Rating: 3 - Meets standards +Strengths: + +- Full Prow label taxonomy, org-level issue templates, and automated lifecycle + management are in place. +- Open issues are substantive, with structured bodies and clear problem + statements. +- The retired `good-first-issue` batch (#918 to #925) is a model for how to + write scoped, self-contained documentation tasks. +- Issue volume (twelve per year) is small enough to triage completely. +- The Contributing page tells newcomers which label to look for and in which + repositories. + +Weaknesses: -#### New contributor getting started content +- Zero open `good-first-issue` items in kubevirt/user-guide and zero + documentation-labeled beginner issues in kubevirt/kubevirt. +- Every beginner issue closed in the past year was auto-closed as rotten rather + than fixed. +- Half of open issues are unlabeled; none carries `triage/*`, `sig/*`, or an + assignee. +- No process exempts valid, unworked beginner issues from the stale bot. +- A proposal for Simplified Chinese documentation and a theme end-of-life report + have no recorded triage decision. + +Rating: 2 - Needs improvement + +### New contributor getting started content Open source is complex and projects have many processes to manage that. Are processes easy to understand and written down so that new contributors can jump @@ -1409,151 +1328,201 @@ in easily? We evaluate on the following: - Do you have a community repository or section on your website? - Yes, both exist. KubeVirt maintains a dedicated `kubevirt/community` - repository that holds governance, the membership policy and checklist, a - maintainers list, per-SIG and working-group directories, community meeting - information, and a code of conduct. The project website also has a community - section at https://kubevirt.io/community/, and the user guide's contributing - page links to it directly. New contributors therefore have a clear, - discoverable home for community structure and processes. + Yes, both. The kubevirt/community repository holds the governance document, + membership policy and checklist, maintainers and alumni lists, code of + conduct, AI contribution policy, community meeting mechanics, a SIG list with + per-SIG charters, working groups, a help-wanted label guide adapted from + Kubernetes, and directories for events, design proposals, and conference + proposals. The kubevirt.io website has a Community page with the shared + calendar, GitHub, Slack, mailing list, and YouTube links, and a Contributing + tab in the user guide's top navigation. + + The two are loosely connected. The kubevirt/community + `contributors/contributing.md` is a one-line pointer to the user guide's + Contributing page, and the user guide's Contributing page links back to the + membership policy, governance, code of conduct, and AI policy in + kubevirt/community. However, the Contributing page does not link the community + repository's SIG list, help-wanted guide, community meeting document, or + MAINTAINERS file, so a newcomer sees only part of what the community + repository offers. - Is there a document specifically for new contributors/your first contribution? - Yes. The user guide's - [Contributing](https://kubevirt.io/user-guide/contributing/) page is the - canonical getting-started document, and the community repository's own - contributor file simply redirects to it, which avoids duplication. The page - includes a "Prerequisites" section, a "Your first contribution" section that - points newcomers to `good-first-issue` labeled work and to low-barrier - documentation and community repositories, separate guidance for code - contributors, a list of important community resources (code of conduct, - membership policy, governance), and a link to a New Contributor session - recording. This is a well-structured first-contribution path rather than a - bare pointer to the issue tracker. + Yes. The user guide's Contributing page is written for first-time contributors + and is the canonical entry point that both the root CONTRIBUTING.md and + kubevirt/community point to. It has a Prerequisites section (CNCF open source + primer, Git basics, the organization's repositories, quick start labs), a + "Your first contribution" section that lists documentation and community + repositories as low-barrier starting points and code repositories for Go + developers, an "Other ways to get started" section (review a pull request, + watch the New Contributor session recording, open an issue), and links to the + community's core documents. + + The document stops before the mechanics. It tells readers to look for + `good-first-issue` but the linked repositories currently have no such open + issues, and it does not describe how to claim an issue, the fork-branch-PR + flow with DCO sign-off, what Prow labels and `/lgtm` and `/approve` mean, or + how long review takes. Those mechanics are split between the repository README + (build, spell check, link check, sign-off) for documentation and + kubevirt/kubevirt's CONTRIBUTING.md and `docs/getting-started.md` for code. + The kubevirt/kubevirt CONTRIBUTING.md is the more complete document, covering + workflow, testing, draft pull requests, DCO, review, and membership, but it is + written for code contributors and is not surfaced in the user guide beyond one + link. - Do new users know where to get help? - Yes, though the help information is somewhat scattered and minimal in places. - The user guide's landing page has a "Getting help" section listing the issue - tracker, the `kubevirt-dev` mailing list, and the `#virtualization` Slack - channel. The contributing page additionally points to the community page and - the project's social channels, and the community repository README lists both - the `#virtualization` and `#kubevirt-dev` Slack channels. The main weaknesses - are that the user guide's "Getting help" section is only three bullets placed - at the bottom of the index page, it does not link the community page, and it - omits the `#kubevirt-dev` Slack channel, so the help entry points are not - fully consistent across sources. - -##### Comment - -KubeVirt provides strong new contributor getting started content. The user -guide's Contributing page serves as a single, well-organized entry point that -covers prerequisites, a clear "Your first contribution" section, separate tracks -for documentation and code contributors, and links to essential community -resources such as the code of conduct, membership policy, and governance. -Importantly, the community repository's own contributor file redirects to this -page rather than duplicating it, so there is one canonical source of truth. This -structure reflects a deliberate onboarding path rather than a bare pointer to -the issue tracker. - -The project also gives newcomers a real community home. The `kubevirt/community` -repository documents SIGs and working groups, community meetings, membership -progression, and maintainers, and the website exposes a companion community -section that the contributing page links to directly. Combined with a linked New -Contributor session recording, a first-time contributor has both written and -video onboarding material and a clear picture of how the community is organized. - -The main opportunity for improvement is the "Getting help" experience, which is -thinner and less consistent than the rest of the onboarding content. In the user -guide it is a three-bullet section at the bottom of the landing page that lists -the issue tracker, mailing list, and the `#virtualization` Slack channel, but it -omits the community page and the `#kubevirt-dev` Slack channel that appear in -other sources. Consolidating these entry points and surfacing them more -prominently would remove ambiguity about where to ask questions. - -A second, smaller gap connects to the beginner issue backlog: the contributing -page tells newcomers to look for `good-first-issue` items, but that backlog is -currently empty, so a motivated first-timer following the documentation can -reach a dead end. Keeping a small pool of curated beginner issues would let the -otherwise excellent onboarding content deliver on its promise. + Partially. The Welcome page's "Getting help" section lists the GitHub issue + tracker, the kubevirt-dev mailing list, and the `#virtualization` Slack + channel. The Contributing page invites readers to raise a bug if something is + missing, points to the Community page, and links the New Contributor session + recording. The kubevirt/community help-wanted guide states that + `good first issue` items come with a commitment from members to provide extra + assistance. + + Help is not framed for contributors specifically. Nothing tells a new + contributor which Slack channel to ask in when stuck on a documentation pull + request (`#kubevirt-dev` is not named in the guide), who the documentation + approvers are, whether there is a mentor or buddy program, or that the weekly + community meeting welcomes newcomer introductions. The help links are bare + URLs on the Welcome page and are not repeated on the Contributing page or in + CONTRIBUTING.md. + +#### Comment + +KubeVirt has a genuine new-contributor document and a mature community +repository behind it. The user guide's Contributing page is written for someone +making their first open source contribution: it sets expectations, points to +low-barrier repositories, offers non-code ways to start, and links the +governance, membership, code of conduct, and AI contribution policies. The +kubevirt/community repository supplies the depth, including a SIG list, a +membership checklist, a help-wanted label guide, and a detailed community +meeting document, and both sides point at each other as the canonical entry. + +The weakness is the hand-off from motivation to action. The Contributing page +ends where a newcomer needs the most guidance: how to pick and claim an issue, +how to fork, sign off, and open a pull request, what the Prow labels mean, and +who will review. Those mechanics exist but are scattered across the repository +README, kubevirt/kubevirt CONTRIBUTING.md, and kubevirt/kubevirt +`docs/getting-started.md`, none of which is presented as the next step. The page +also directs newcomers to `good-first-issue` lists that are currently empty, and +does not name a channel, person, or meeting where a stuck contributor can ask +for help. The community repository's most useful contributor resources (SIG +list, help-wanted guide, meeting document, MAINTAINERS) are not linked from the +guide at all. -Rating: 4 - Meets or exceeds standards +Strengths: + +- A dedicated, welcoming Contributing page that is the canonical entry point + from both CONTRIBUTING.md and kubevirt/community. +- Explicit low-barrier starting points (documentation, website, community + repositories) and non-code ways to contribute. +- A New Contributor session recording on YouTube. +- A comprehensive kubevirt/community repository with governance, membership, + SIG, and meeting documentation. +- Community page and Welcome page surface the primary help channels. -#### Project governance documentation +Weaknesses: + +- The Contributing page omits the contribution mechanics (claiming an issue, + fork and PR flow, DCO, Prow labels, review expectations). +- Newcomers are sent to `good-first-issue` lists that are empty. +- No contributor-specific help guidance: which Slack channel to ask in, who + reviews documentation, whether mentoring is available. +- The SIG list, help-wanted guide, community meeting document, and MAINTAINERS + file in kubevirt/community are not linked from the guide. +- Build and test instructions for the guide live only in the repository README, + not on the Contributing page. + +Rating: 3 - Meets standards + +### Project governance documentation One of the CNCF’s core project values is open governance. We evaluate on the following: - Is project governance clearly documented? -Yes. Project governance is clearly and comprehensively documented, and the user -guide points contributors to it. The community repository contains a dedicated -`GOVERNANCE.md` that covers the membership policy, maintainer responsibilities -and selection, meetings, CNCF resources, the code of conduct, off-boarding and -removing maintainers, voting, SIGs, subprojects, working groups, and roles and -organization management. It is complemented by a `MAINTAINERS.md` that lists -current maintainers with their areas of responsibility and employers, tracks -emeritus maintainers, and is kept in sync with the CNCF project-maintainers -list. A `membership_policy.md` document defines a full contributor ladder — from -new contributor through org member, reviewer, approver, SIG chair, subproject -lead, and working-group chair — with explicit requirements, responsibilities, -privileges, and an inactivity policy. An autogenerated `sig-list.md` (built from -`sigs.yaml`) enumerates the SIGs, working groups, chairs, contacts, and meeting -schedules. - -From the user guide's own perspective, the contributing page surfaces the -governance material by linking to the project governance document, the -membership policy, the code of conduct, and the AI contribution policy under its -"Important community resources" section. The main limitation is discoverability -rather than content: governance is only reachable through that one list on the -contributing page, and the user guide has no dedicated governance or community -landing page in its own navigation. The governance documentation itself, -however, is thorough, versioned, and aligned with CNCF expectations. - -##### Comment - -KubeVirt's project governance documentation is a clear strength. The -`kubevirt/community` repository provides a dedicated `GOVERNANCE.md` that -addresses the full range of governance concerns: the membership policy, -maintainer responsibilities and selection, meetings, voting, off-boarding and -removal of maintainers, code of conduct, and the organization of SIGs, -subprojects, and working groups. This is backed by a `MAINTAINERS.md` that names -current maintainers and their areas of responsibility, records emeritus -maintainers, and is explicitly kept in sync with the CNCF project-maintainers -list. Together these documents give contributors an unambiguous picture of who -leads the project and how decisions are made. - -The contributor ladder is especially well defined. The membership policy lays -out each role — from new contributor through org member, reviewer, approver, SIG -chair, subproject lead, and working-group chair — with concrete requirements, -responsibilities, privileges, and an inactivity policy that explains how roles -are maintained or lapse. The autogenerated SIG list, produced from a -machine-readable `sigs.yaml`, keeps the list of groups, chairs, contacts, and -meeting times consistent and current. This structure reflects mature, -CNCF-aligned governance rather than a token document. - -The primary opportunity for improvement is discoverability from within the user -guide itself. Governance is reachable only through a single "Important community -resources" list on the contributing page; the user guide's own navigation has no -dedicated community or governance entry point. A reader browsing the -documentation site would not easily find how the project is governed without -first landing on the contributing page. - -Because the analysis is scoped to the user guide, a light improvement would be -to surface governance more prominently — for example, a short "How KubeVirt is -governed" pointer or a community landing page that links to `GOVERNANCE.md`, the -maintainers list, and the membership ladder. The underlying governance content -is comprehensive and current; the gap is purely one of navigation from the -documentation site. + Yes. Governance lives in the kubevirt/community repository and is complete and + specific. `GOVERNANCE.md` (about 1,350 words) defines the maintainer role and + its responsibilities, the criteria and process for selecting maintainers (one + year of participation, demonstrated leadership, nomination by pull request + against `MAINTAINERS.md`, simple-majority vote), maintainer meetings, use of + CNCF resources, the code of conduct, off-boarding and mentorship, retiring and + removing maintainers, voting rules (lazy consensus by default, simple majority + for most matters, two-thirds to remove a maintainer or amend the governance), + and the structure of Special Interest Groups, subprojects, and working groups. + `MAINTAINERS.md` lists eight current maintainers with employer and area of + responsibility, a table of emeritus maintainers with retirement dates, and a + note that the list must stay in sync with the CNCF project maintainers list. + + The surrounding documents are equally thorough. `membership_policy.md` defines + a contributor ladder from new contributor through org member, reviewer, + approver, SIG chair, subproject lead, and working group chair, with + requirements and privileges for each level and an inactivity policy that + states how inactivity is measured. `membership_checklist.md`, + `code-of-conduct.md`, `ai-contribution-policy.md`, and `ALUMNI.md` complete + the set. SIGs and working groups are declared in `sigs.yaml`, from which + `sig-list.md` is generated, and each SIG has a charter with scope, roles, and, + in at least some cases, meeting mechanics. A `CNCF/` directory records the + incubation application and technical review. + + Discoverability from the user-facing sites is limited. The user guide's + Contributing page links `GOVERNANCE.md` under "Important community resources" + with the one-line description "Project Maintainer responsibilities", and links + the membership policy and code of conduct alongside it. The kubevirt.io + Community page does not link the governance document, the maintainers list, or + the SIG list, and neither site summarizes how decisions are made or who the + maintainers are. A user or prospective adopter evaluating the project's + governance must know to open the community repository. + +#### Comment + +KubeVirt's governance documentation is clear, specific, and maintained. +`GOVERNANCE.md` answers the questions an evaluator asks first: who the +maintainers are, how they are chosen and removed, how votes work and what +thresholds apply, and how SIGs and working groups relate to the maintainers. The +companion documents give the contributor ladder concrete requirements at each +level and an explicit inactivity policy, the maintainers list records employers +and areas of responsibility with an emeritus table, and SIG charters are +generated from a single source of truth. This is the level of governance +documentation expected of a CNCF incubating project and is a strength the +project can point to. + +The only shortfall is presentation. Governance is documented in the community +repository but not summarized or prominently linked from kubevirt.io or the user +guide; the Contributing page links `GOVERNANCE.md` with a one-line label among +other resources, and the Community page does not mention governance, +maintainers, or SIGs at all. Prospective adopters and contributors evaluating +the project from the website have to know the community repository exists to +find this material. -Rating: 4 - Meets or exceeds standards +Strengths: -### Recommendations +- `GOVERNANCE.md` covers maintainer selection, removal, voting thresholds, + meetings, SIGs, subprojects, and working groups with concrete rules. +- `MAINTAINERS.md` lists current maintainers with employer and responsibilities + plus an emeritus table, and is tied to the CNCF maintainers list. +- `membership_policy.md` defines a full contributor ladder with requirements, + privileges, and a measurable inactivity policy. +- SIGs and working groups are declared in `sigs.yaml` and the SIG list is + generated, so it cannot drift from the source. +- Code of conduct, AI contribution policy, and CNCF incubation records are + co-located. -> AUTHOR NOTE: Write general recommendations based on the comments from the -> previous section. +Weaknesses: + +- The kubevirt.io Community page does not link governance, maintainers, or the + SIG list. +- The user guide's Contributing page links `GOVERNANCE.md` with a one-line label + and no summary. +- Neither site names the maintainers or explains how decisions are made. + +Rating: 4 - Meets or exceeds standards + +## Contributor documentation - Recommendations -#### Communication methods documented +### Communication methods documented - Add a dedicated "Community and communication" section to the user guide that consolidates Slack, the forum, the kubevirt-dev mailing list, community @@ -1579,7 +1548,7 @@ Rating: 4 - Meets or exceeds standards accounts) are either mirrored or clearly linked from the guide, ensuring readers who stay in the user guide are not missing key channels. -#### Beginner friendly issue backlog +### Beginner friendly issue backlog - Consolidate the duplicate labels by standardizing on the GitHub-native `good first issue` label (spaced) and retiring or aliasing the hyphenated @@ -1610,56 +1579,60 @@ Rating: 4 - Meets or exceeds standards documentation-issue triage during a SIG or community meeting) to keep labeling, acceptance, and staleness decisions consistent over time. -#### New contributor getting started content - -- Consolidate and strengthen the "Getting help" section on the user guide - landing page so it lists all primary channels in one place: the - `#virtualization` and `#kubevirt-dev` Slack channels, the `kubevirt-dev` - mailing list, the community page, and the issue tracker. -- Make the "Getting help" information easier to find by linking to it from the - contributing page and considering a more prominent placement than the bottom - of the index page. -- Keep a small, curated pool of open `good-first-issue` items so that newcomers - who follow the "Your first contribution" guidance always have actionable work, - rather than reaching an empty backlog. -- Add a direct, filtered link from the contributing page to the current - `good-first-issue` list (for example, a saved label query) so first-timers - reach real issues in one click. -- Ensure help and community entry points are consistent across the user guide, - the contributing page, and the `kubevirt/community` README, since they - currently list slightly different channels. -- Consider adding a brief "how to ask a good question" note or - expected-response-time guidance near the help channels so new contributors - know what to include and where questions are best directed. -- Continue using the community repository's redirect-to-canonical approach for - contributor docs, and periodically verify that all "get started" links across - repositories still resolve to the single canonical contributing page. -- Optionally surface the New Contributor session recording and the community - meeting schedule closer to the "Your first contribution" section so newcomers - can quickly find live, synchronous ways to get onboarded. - -#### Project governance documentation - -- Improve discoverability from the documentation site by adding a short "How - KubeVirt is governed" pointer or a dedicated community/governance landing page - that links to `GOVERNANCE.md`, the maintainers list, and the membership - ladder, rather than relying solely on the contributing page's resource list. -- Surface the governance links in the user guide navigation (for example, under - a community or contributing section) so readers can reach them without first - knowing to open the contributing page. -- Add a brief, plain-language summary of the governance model and the - contributor ladder in the user guide, with a clear link out to the - authoritative documents in the community repository, so newcomers get an - overview without reading the full policy. -- Continue keeping `MAINTAINERS.md` synchronized with the CNCF - project-maintainers list, and note the last-reviewed date on the maintainers - and governance documents so readers can gauge currency. -- Ensure the SIG list and its meeting details remain generated from `sigs.yaml`, - and link the SIG list from the user guide so contributors can find the right - group and meeting to join. -- Cross-link related governance artifacts (code of conduct, membership policy, - AI contribution policy, and voting process) from a single place so - contributors can navigate the full set without hunting across repositories. +### New contributor getting started content + +- Add a "Making your first documentation change" section to the Contributing + page that walks through the mechanics end to end: find or file an issue, + comment to claim it, fork and branch, edit under `docs/` and update + `.nav.yml`, run `make check_spelling` and `make check_links`, sign off with + `git commit -s`, open the pull request, and what to expect from Prow + (`ok-to-test`, `lgtm`, `approved`) and reviewers. Move the build and test + steps from the repository README here or link them prominently. +- Add a "Where to ask for help" section to the Contributing page that names + `#kubevirt-dev` on Kubernetes Slack for contributor questions and + `#virtualization` for usage questions, links the Slack invitation page, states + that the weekly community meeting includes newcomer introductions with the + day, time, and Zoom link, and identifies the documentation approvers or a docs + contact. +- Link the kubevirt/community resources that newcomers need directly from the + Contributing page: the SIG list (to find the right SIG for a topic), the + help-wanted guide (to understand the labels), the community meeting document, + and the MAINTAINERS file. +- Replace the generic "look for good-first-issue" advice with a direct link to + the filtered issue list for each repository, and pair this with the beginner + issue backlog recommendations so the lists are populated when newcomers + arrive. +- Add a "Contributing to the code" subsection that summarizes the + kubevirt/kubevirt path in three or four steps (read CONTRIBUTING.md, follow + `docs/getting-started.md` to build and run a local cluster, pick an issue, + open a draft PR) so code-minded newcomers see a clear next step rather than a + single link. +- Ask the community whether a lightweight mentoring or buddy arrangement exists + or could be offered for first-time contributors, and document it on the + Contributing page if so; the help-wanted guide already promises "extra + assistance" on `good first issue` items, so state how to request it. +- Repeat the "Getting help" links from the Welcome page in CONTRIBUTING.md and + on the Contributing page so contributors do not have to navigate back to the + home page to find a channel. + +### Project governance documentation + +- Add a "Governance" section to the kubevirt.io Community page that states in + two or three sentences how KubeVirt is governed (CNCF incubating project, + maintainer group, SIGs and working groups, lazy consensus with maintainer + votes) and links `GOVERNANCE.md`, `MAINTAINERS.md`, `membership_policy.md`, + and `sig-list.md`. +- Expand the "Important community resources" list on the user guide's + Contributing page so each governance link has a one-sentence description of + what the reader will find, and add the maintainers list and SIG list to it. +- Add a short "How the project is run" paragraph to the Contributing page, above + the resource list, that names the maintainer group, explains that work is + organized in SIGs, and states that decisions default to lazy consensus, so a + newcomer understands the structure before following the links. +- Ask the maintainers to confirm that every SIG charter includes a "Meeting + Mechanics" section like SIG Storage's, and that `sigs.yaml` records each SIG's + meeting cadence and Slack channel, so the generated SIG list can serve as the + single place to find how to participate in each group. ## Website and infrastructure @@ -1667,87 +1640,76 @@ KubeVirt is an **incubating** project of CNCF. This means that the project should be developing professional-quality documentation alongside the project code. -| Criterion | Rating (1-5) | -| ------------------------------------- | ------------------------------ | -| Usability, accessibility, and design | 4 - Meets or exceeds standards | -| Branding and design | 4 - Meets or exceeds standards | -| Case studies/social proof | 3 - Meets standards | -| SEO, Analytics, and site-local search | 2 - Needs improvement | -| Maintenance planning | 4 - Meets or exceeds standards | - -Other metrics TBD: - -| Criterion | [Rating (1-5)] | -| ------------------------------------------- | -------------- | -| Single-source for all files | [rating (1-5)] | -| Meets min website req. (for maturity level) | [rating (1-5)] | -| A11y plan & implementation | [rating (1-5)] | -| Mobile-first plan & impl. | [rating (1-5)] | -| HTTPS access & HTTP redirect | [rating (1-5)] | -| Google Analytics 4 for production only | [rating (1-5)] | -| Indexing allowed for production server only | [rating (1-5)] | -| Intra-site / local search | [rating (1-5)] | -| Account custodians are documented | [rating (1-5)] | - -### Comments - -KubeVirt's website and infrastructure are on a strong footing overall, rating -"meets or exceeds standards" in three of the five criteria. The Material for -MkDocs foundation delivers a responsive, mobile-friendly site with clean -typography, semantic landmarks, descriptive ARIA labels, a "Skip to content" -link, and complete image alt text, so usability and accessibility are strong at -the structural level. The brand is clear and consistently applied, with the teal -palette and logo defined at the theme level rather than per author. Maintenance -is dependable and not dependent on a single person: the repository uses the -Kubernetes-style OWNERS model, draws on roughly 49 distinct authors over the -last year, builds quickly through Netlify previews and Prow CI, and serves -securely over HTTPS. The recommended improvements are mostly targeted fixes -rather than structural changes. - -The highest-impact gap—and the section's lowest rating—is the complete absence -of analytics. Neither the user guide nor the main site includes any analytics -tags, so there is no visibility into traffic, popular pages, search terms, or -broken inbound links, and 404 reports cannot be generated to guide maintenance. -This absence is consistent with the project's privacy posture, which is a -legitimate trade-off, but if the project wants data to drive documentation -improvements, adopting a privacy-respecting option (GA4 or an alternative), -enabling it only on the production deploy, and documenting the account -custodians would close an important blind spot. Two smaller SEO fixes accompany -it: make the preview `noindex` behavior an explicit project setting rather than -relying on the Netlify default, and correct the double slash in the `robots.txt` -sitemap URL. - -A cross-cutting accessibility theme surfaces in both the usability and branding -analyses: color contrast on the brand teal. The primary teal (`#0db2b6` in -`docs/stylesheets/extra.css`) yields only about 2.6:1 against white header -text—below the WCAG AA thresholds of 4.5:1 for normal text and 3:1 for large -text—and body links darkened with `filter: brightness(80%)` reach only about -3.96:1. Because this styling is defined once at the theme level, darkening the -primary teal (or the text on it) and re-checking links in both the light and -dark schemes is a small, high-value change that affects color-impaired and -low-vision readers most. Adding an automated contrast and accessibility check to -the build would keep the fix from regressing. - -Two further themes concern connecting the guide to the wider project and -hardening the stack. The strong adoption and community content—an active blog, -curated talk playlists, and an extensive adopter logo wall—lives on -`kubevirt.io` and is not linked from the user guide at all, so readers have no -easy path to this social proof; the guide would also benefit from a few -narrative case studies or testimonials that explain how and why organizations -use KubeVirt. This mirrors a broader cross-property gap, since the MkDocs guide -and the separate main site share a logo and color family but not an identical -look and feel. Documenting a small set of shared brand values and adding -targeted links (for example, a "Community" or "Adopters" entry) would align the -two properties and surface existing content. On the infrastructure side, the -build installs MkDocs and its plugins without pinned versions in `netlify.toml` -and the `Makefile`, which risks non-reproducible builds; pinning versions and -periodically reviewing the overhead of maintaining two separate stacks would -sustain the section's already solid maintenance posture. - -The following sections contain brief assessments of each element of the Website -and documentation infrastructure rubric. - -#### Single-source requirement +| Criterion | Rating (1-5) | +| ------------------------------------------- | ------------------------------ | +| Single-source for all files | 2 - Needs improvement | +| Meets min website req. (for maturity level) | 3 - Meets standards | +| Usability, accessibility, and design | 3 - Meets standards | +| Branding and design | 4 - Meets or exceeds standards | +| Case studies/social proof | 3 - Meets standards | +| SEO, Analytics, and site-local search | 2 - Needs improvement | +| Maintenance planning | 3 - Meets standards | + +Other Metrics: + +| Criterion | Rating (1-5) | +| ------------------------------------------- | ------------------------------ | +| A11y plan & implementation | 3 - Meets standards | +| Mobile-first plan & implementation | 3 - Meets standards | +| HTTPS access & HTTP redirect | 4 - Meets or exceeds standards | +| Google Analytics 4 for production only | 1 - Not present | +| Indexing allowed for production server only | 3 - Meets standards | +| Intra-site / local search | 4 - Meets or exceeds standards | +| Account custodians are documented | 1 - Not present | + +The KubeVirt web presence rests on a sound foundation. The user guide runs on +MkDocs Material, which supplies responsive layout, keyboard, screen-readers, +full-text search, dark mode, and sitemaps with little project effort, and a Prow +pipeline republishes both sites to GitHub Pages over HTTPS within a minute or +two of merge. Branding is applied once at the theme level and stays consistent +across roughly one hundred pages, the main website footer is a model of CNCF +compliance for an incubating project, and the project has real adoption evidence +in its adopters list, CNCF case studies, Summit recordings, and blog. Most of +what a reader needs is present; the shortfalls are in measurement, connection, +and stewardship rather than in the platform. + +The most consequential gap is that the user guide is invisible to the project. +It carries no analytics at all, so maintainers cannot see which pages are read, +which searches fail, or which inbound links break, and the main site's Adobe +Analytics tag runs on previews as well as production. The same blind spot +appears in governance: nobody is documented as custodian of the analytics, +Netlify, Search Console, DNS, or GitHub Pages accounts, the community +`sig/documentation` entry has no chairs or members, and commit history shows +both repositories leaning on one active documentation maintainer. Instrumenting +the guide and writing down who owns the infrastructure are low-effort changes +that would unblock every other improvement in this section. + +The second recurring theme, and the one that drives the two lowest ratings, is +that KubeVirt's web properties do not act as one. Pages under `kubevirt.io` are +built from three repositories with no submodule linkage, user-facing content +also sits in the `docs/` directories of the core and CDI repositories, and no +README explains which content belongs where. The guide and `kubevirt.io` use +different static-site generators, logo variants, typefaces, and header +treatments; neither site's search covers the other; and the guide's header, +footer, and landing page contain no link to adopters, case studies, talks, the +blog, or `kubevirt.io` itself. The guide's footer also omits the copyright, CNCF +affiliation, and trademark links the main site carries, so a documentation +reader sees no visible connection to CNCF. A shared header and footer, a +documented content boundary, cross-links from the guide's landing page, and a +`robots.txt` that lists both sitemaps would close most of this gap. + +Finally, a handful of small defects affect every page and are each a one-line +fix: white-on-teal header text at roughly 2.6:1 contrast fails WCAG AA, +`robots.txt` references a malformed sitemap URL, `netlify.toml` contains a dead +`sed` step and unpinned dependencies, the main site's copyright line lacks the © +symbol, and production responses lack an HSTS header. Content-side accessibility +issues (an ASCII-art architecture diagram with no text alternative, `$`-prefixed +code blocks, and 500-plus-line pages) belong with the content-maintainability +work rather than infrastructure. The branding implementation, the automated +publish pipeline, and the main website footer are strong enough to cite as +examples for other projects. + +### Single-source requirement Source files for _all website pages_ should reside in a single repo. Among other problems, keeping source files in two places: @@ -1757,18 +1719,105 @@ problems, keeping source files in two places: - increases the likelihood of errors - makes it more complicated to generate the documentation from source files -Ideally, all website files should be in the **website repo** itself. -Alternatively, files should be brought into the website repo via [git +Ideally, all website files should be in the website repo itself. Alternatively, +files should be brought into the website repo via [git submodules][git-submodules]. If a project chooses to keep source files in multiple repos, they need a clearly -documented strategy for managing mirrored files and new contributions. +documented strategy for managing mirrored files and new contributions. We +evaluate on the following: + +- Does the project have a single source for its documentation? If not, is there + a reason? + + No. Pages served under the `kubevirt.io` domain come from at least three + repositories, none of which pulls the others in as a Git submodule. The main + website (`kubevirt.io`, including the blog, labs, adopters, and community + pages) is a Jekyll site built from `kubevirt/kubevirt.github.io`. The user + guide (`kubevirt.io/user-guide`) is an MkDocs site built from + `kubevirt/user-guide`. The API reference (`kubevirt.github.io/api-reference`) + is generated into `kubevirt/api-reference` from the code in + `kubevirt/kubevirt`. Each repository is published independently by its own + Prow post submit job to its own `gh-pages` branch, and the website's + `pages/docs.md` is a one-line stub that simply links to the user guide. + + User-facing documentation is also spread across code repositories. The `docs/` + directory of `kubevirt/kubevirt` contains about sixty files, including + `architecture.md`, `cloud-init.md`, and `getting-started.md`, several of which + cover topics the user guide also covers, and the user guide links out to + `kubevirt/kubevirt/docs/getting-started.md` in three places. Containerized + Data Importer documentation lives in the `doc/` directory of + `kubevirt/containerized-data-importer` (about forty files), and the user guide + links to it from six pages. Contributor and governance documentation lives in + `kubevirt/community`. A reader therefore encounters KubeVirt documentation on + GitHub in four repositories in addition to the two rendered websites. + + There is a practical reason for the main split, but it is not written down. + The website and the user guide use different static-site generators (Jekyll + and MkDocs), have different maintainers listed in their `OWNERS` files, and + target different audiences (marketing and community versus operators and + users), so keeping them in separate repositories avoids coupling their + toolchains. Within the user guide itself, sourcing is clean: all content is + Markdown under `docs/`, navigation is declared in `.nav.yml` files, and + redirects are declared in `mkdocs.yml`. Neither repository's README or + contributing guide explains the division of content between the website, the + user guide, and the code repositories' `docs/` directories, so contributors + have to infer where a new page belongs. + +#### Comment + +KubeVirt does not meet the single-source requirement as the CNCF criteria define +it. The pages a visitor sees under `kubevirt.io` are built from three separate +repositories with three separate publish pipelines, and user-facing +documentation is additionally scattered across the `docs/` directories of the +core and CDI code repositories. The split between the website and the user guide +is defensible, since the two use different generators and serve different +audiences, but that rationale is undocumented, and the overlap between +`kubevirt/kubevirt/docs` and the user guide is not a design decision so much as +an accumulation. Contributors have no written guidance on which repository a new +page belongs in, and readers can land on developer-oriented Markdown in the core +repository that duplicates or contradicts the user guide. + +The user guide itself is a well-behaved single source: one `docs/` tree, +explicit navigation files, and a redirect map for moved pages. That makes it the +natural home for consolidating user-facing content that currently lives +elsewhere, and the existing cross-links from the guide to +`kubevirt/kubevirt/docs` and to the CDI repository identify exactly which +content is a candidate to move. + +Strengths: -#### Minimal website requirements +- The user guide keeps all of its content in one `docs/` tree with declarative + navigation and redirects. +- Each repository has one clear publish path, so there is no duplicate + deployment of the same content. +- The website's docs page defers to the user guide rather than hosting a + parallel copy. + +Weaknesses: + +- Website, user guide, and API reference are three repositories with no + submodule or other mechanism tying them together. +- The `kubevirt/kubevirt/docs` directory holds about sixty files that overlap + with user guide topics, and the guide links into it for getting-started + content. +- CDI documentation lives in the CDI repository, and the guide links to it from + six pages. +- No README or contributing guide explains which content belongs in which + repository, or why the split exists. + +Rating: 2 - Needs improvement + +### Website requirements Listed here are the minimal website requirements for projects based on their -[maturity level][maturity-level], either incubating or graduated. (These are the -only two levels for which a tech docs analysis can be requested.) +[maturity level][maturity-level], either incubating or graduated. These are the +only two levels for which a tech docs analysis can be requested. We evaluate on +the following: + +- Are most of the applicable CNCF Website + Guidelines(https://deploy-preview-358--cncf-techdocs.netlify.app/docs/website-guidelines-checklist/) + satisfied? @@ -1782,101 +1831,155 @@ only two levels for which a tech docs analysis can be requested.) -[git-submodules]: https://git-scm.com/book/en/v2/Git-Tools-Submodules -[maturity-level]: - https://github.com/cncf/toc/tree/main/process#ii-stages---definitions--expectations -[cncf-servicedesk]: https://servicedesk.cncf.io +#### Comment -#### Usability, accessibility and devices +### Usability, accessibility and devices Most CNCF websites are accessed from mobile and other non-desktop devices at least 10-20% of the time. Planning for this early in your website's design will -be much less effort than retrofitting a desktop-first design. +be much less effort than retrofitting a desktop-first design. We evaluate on the +following: - Is the website usable from mobile? - Yes. The live pages include a responsive viewport meta tag - (`width=device-width,initial-scale=1`), and the Material for MkDocs theme is - mobile-first and responsive, so the layout adapts to small screens. + Yes. The user guide uses mkdocs-material, which is responsive by default, and + every page carries a `width=device-width, initial-scale=1` viewport meta tag. + On narrow screens the header collapses to a hamburger drawer that contains the + section navigation, the page's table of contents, and the search entry point, + and the footer offers previous and next page links. A light and dark color + scheme toggle is available. + + Two content patterns reduce mobile usability. The site's `extra.css` sets + `.md-typeset table:not([class])` to `display: table; width: max-content`, + which forces wide tables such as the Arm64 feature-gate and device status + pages to their natural width. Whether they remain horizontally scrollable + depends on Material's JavaScript table wrapper; this needs verification on a + device. Separately, 531 non-table lines in the source exceed 140 characters, + most of them single-line commands and YAML in code blocks, which require + horizontal scrolling on phones. The 3,000-line Release Notes page is a single + document and is slow to load and scroll on mobile. - Are doc pages readable? - Yes. Pages use the theme's clean Roboto typography, clear heading hierarchy, - an in-page table of contents, admonitions, and syntax-highlighted code blocks, - all of which support comfortable reading on the documentation site. + Yes, in the main. Material's typography, line length, and spacing are used + unmodified apart from a slightly larger, teal-colored section label in the + sidebar on wide screens and a light border on inline code. Pages use a single + `h1` and a sensible heading hierarchy (`h2` through `h5` on Live Migration), + admonitions are used for notes and warnings on newer pages, and footnotes and + permalinks are enabled. + + Readability varies with page age. Older pages such as Installation, Lifecycle, + and Disks and Volumes present commands as indented blocks with `$` prompts and + mix command and output in one block, which is harder to scan than the fenced, + language-tagged blocks on newer pages. The Architecture page conveys its + central "stack" diagram as ASCII art in a preformatted block, and several long + pages (Live Migration at 500 lines, Disks and Volumes at over 1,300 lines, + Interfaces and Networks at about 700 lines) have no in-page summary or + grouping beyond the table of contents. - Are all / most website features accessible from mobile -- such as the top-nav, site search and in-page table of contents? - Yes. The primary navigation (rendered as tabs on desktop) collapses into a - mobile drawer, site search is present (`md-search`), and the in-page table of - contents is available. All are exposed with descriptive ARIA labels (for - example, "Header," "Navigation," "Search," "Table of contents," and "Tabs"), - so the key features remain reachable on mobile. + Yes. Material moves the top-level tabs into the drawer on mobile, the search + icon opens a full-screen search overlay, and the in-page table of contents + appears inside the drawer under the current page. The Welcome, Architecture, + Quickstarts, Release Notes, and Contributing pages hide the navigation sidebar + via front matter (`hide: navigation`), so on those pages the drawer shows only + the table of contents; the section list on the Welcome page is prose rather + than links, so a mobile reader must open the drawer to move into a section. - Are color contrasts significant enough for color-impaired readers? - Partially, and this is the area's weakest point. The brand teal used as the - primary color (`--md-primary-fg-color: #0db2b6`, set in - `docs/stylesheets/extra.css`) provides only about a 2.6:1 contrast ratio with - the white header text, which is below the WCAG AA threshold of 4.5:1 for - normal text and even below the 3:1 threshold for large text. Body links are - darkened with `filter: brightness(80%)`, which improves them to roughly 3.96:1 - but still falls short of the 4.5:1 AA requirement for normal text. Contrast - therefore needs improvement for color-impaired readers. + Mostly, with one clear failure. The site overrides Material's teal palette + with a custom primary color, `#0db2b6`. White text on that color, which is how + the header bar, tabs, and site title render, has a contrast ratio of about + 2.6:1, below the WCAG AA minimum of 4.5:1 for normal text and 3:1 for large + text. Body links use the primary color darkened to 80 percent brightness + (about `#0a8e92`), giving roughly 3.96:1 on white, which passes for large text + but not for normal body text. The sidebar section labels (`#00797f`, 5.2:1) + and the accent color (`#006166`, 7.2:1) pass. + + The site does not rely on color alone. Active tabs are underlined as well as + colored, links are distinguished by color and hover underline, and admonitions + carry icons and titles in addition to colored borders. The dark scheme uses + the same primary color, so the header contrast issue persists in dark mode + while link contrast improves slightly (about 4.06:1 on the slate background). - Are most website features usable using a keyboard only? - Yes. The page includes a "Skip to content" link (`md-skip`), and the Material - theme provides full keyboard navigation and search keyboard shortcuts, so the - main features can be operated without a mouse. + Yes. Material provides a "Skip to content" link as the first focusable + element, the search field is reachable by Tab and by the `/` or `s` shortcut, + search results are navigable with arrow keys, and the navigation drawer, table + of contents, tabs, color toggle, and previous and next links are standard + focusable controls. The rendered page contains 47 `aria-label` attributes on + controls. The site adds no custom JavaScript that would trap or hide focus. + Code blocks have no copy button, so there is nothing to reach; enabling one + would add a keyboard-accessible control. - Does text-to-speech offer listeners a good experience? - Largely yes. The document declares its language (``), uses - semantic landmarks and ARIA labels, provides a skip link, and every image in - the documentation carries non-empty alt text (25 markdown images, none with - empty alt, and no raw `` tags lacking `alt`). These give screen readers - and text-to-speech tools a solid foundation, though the ongoing quality of alt - text and heading order depends on authors. - -##### Comment - -The KubeVirt user guide is highly usable and, for the most part, accessible, -thanks to its Material for MkDocs foundation. The site is responsive and works -well on mobile: it sets a proper viewport, collapses the top navigation into a -mobile drawer, and keeps site search and the in-page table of contents reachable -on small screens. Pages are readable, with clean typography, clear heading -structure, and syntax-highlighted code, so readers can move through technical -content comfortably on any device. - -Accessibility support is strong at the structural level. The document declares -its language, exposes semantic landmarks and descriptive ARIA labels (Header, -Navigation, Search, Table of contents, Tabs), and provides a "Skip to content" -link, all of which help keyboard and screen-reader users. Keyboard-only -operation is well supported through the theme's navigation and search shortcuts. -Text-to-speech users are also well served: every image in the documentation -carries non-empty alt text, and there are no raw image tags missing an `alt` -attribute. - -The clear weak point is color contrast. The brand teal used as the primary color -(`#0db2b6` in `docs/stylesheets/extra.css`) yields only about 2.6:1 against the -white header text, which fails the WCAG AA requirement of 4.5:1 for normal text -and even the 3:1 threshold for large text. Body links, darkened with -`filter: brightness(80%)`, reach roughly 3.96:1 but still fall short of 4.5:1. -This affects color-impaired and low-vision readers most, and it is the single -most impactful fix in this area. - -Addressing contrast would be straightforward and high value: darken the primary -teal (or the text placed on it) until header text and links meet WCAG AA, and -verify the result in both the light and dark schemes. To sustain accessibility -over time, maintainers could add an automated contrast and accessibility check -to the build and keep encouraging descriptive alt text and correct heading order -in new pages. + Partially. Pages declare `lang="en"`, use real headings for structure, and + label controls with ARIA attributes, so a screen reader can announce structure + and navigate by heading. The two images on the Windows Virtio Drivers page + have descriptive alt text ("Choose driver", "Install driver", and so on). + + Content patterns work against listeners. The Architecture page's ASCII stack + diagram will be read as a stream of plus signs, pipes, and tildes with no + textual equivalent. Indented code blocks with `$` prompts are announced as + "dollar" before each command. Long YAML manifests and `kubectl` output tables + are read line by line with no summary of what they show. The logo image's alt + text is "logo" rather than "KubeVirt". Wide status tables (for example the + Arm64 feature-gate table with a status column per gate) are readable but + tedious without a caption or summary row. + +#### Comment + +The KubeVirt user guide inherits a solid usability and accessibility baseline +from mkdocs-material. The site is responsive, the navigation, search, and table +of contents all work from a mobile drawer, keyboard users get a skip link, +search shortcuts, and standard focusable controls, and pages declare a language +and use a proper heading hierarchy. The project has customized the theme lightly +and, apart from color, has not undermined these defaults. Dark mode is available +and previous and next links help linear reading. + +The one clear defect is color contrast. The custom teal primary color produces +white-on-teal header and tab text at roughly 2.6:1 and body links at roughly +4:1, both below WCAG AA for normal text. This affects every page and is a +one-line CSS change to fix. The remaining issues are in content rather than the +platform: the Architecture page's central diagram is ASCII art with no textual +equivalent, older pages use `$`-prefixed indented code blocks that read poorly +on screen readers and scroll horizontally on phones, several pages exceed 500 +lines without internal grouping, and wide status tables and long command lines +depend on horizontal scrolling on small screens. The `width: max-content` table +override in `extra.css` should be verified on a real device to confirm tables +still scroll rather than overflow the viewport. -Rating: 4 - Meets or exceeds standards +Strengths: + +- Responsive mkdocs-material theme with viewport meta, mobile drawer navigation, + full-screen search, and in-drawer table of contents. +- Skip-to-content link, search keyboard shortcuts, and ARIA-labeled controls out + of the box. +- `lang="en"`, single `h1`, and consistent heading hierarchy on pages. +- Light and dark schemes with a toggle; active tabs underlined as well as + colored. +- Descriptive alt text on the Windows driver screenshots. -#### Branding and design +Weaknesses: + +- Header and tab text on the custom teal primary color fails WCAG AA (about + 2.6:1); body links are borderline (about 4:1). +- The Architecture stack diagram is ASCII art with no text alternative. +- Older pages use `$`-prefixed indented code blocks mixed with output. +- Very long pages (Disks and Volumes, Interfaces and Networks, Live Migration, + Release Notes) with no internal grouping. +- Wide tables and 500-plus long code lines require horizontal scrolling on + mobile; the `max-content` table override needs device verification. +- Logo alt text is "logo" rather than the project name; no code copy button. + +Rating: 3 - Meets standards + +### Branding and design CNCF seeks to support enterprise-ready open source software. A key aspect of this is branding and marketing. We evaluate on the following: @@ -1884,75 +1987,108 @@ this is branding and marketing. We evaluate on the following: - Is there an easily recognizable brand for the project (logo + color scheme) clearly identifiable? - Yes. The KubeVirt logo, a teal heptagon enclosing a stylized "V," is displayed - in the site header and configured through - `theme.logo: assets/KubeVirt_icon.png`, with matching favicons - (`assets/favicon.ico` and `assets/favicon32x32.png`) in `mkdocs.yml`. The - color scheme reinforces the logo: the Material theme uses a teal palette, and - `docs/stylesheets/extra.css` pins the exact brand colors - (`--md-primary-fg-color: #0db2b6` and `--md-accent-fg-color: #006166`). - Together the logo and teal palette make the project brand clearly identifiable - on every page. + Yes. The KubeVirt user guide displays the project's teal heptagon logo + (`docs/assets/KubeVirt_icon.png`) in the site header and uses it for the + favicon (`favicon32x32.png`). The `mkdocs.yml` theme configuration selects the + Material `teal` palette for both the light and dark color schemes, and + `docs/stylesheets/extra.css` pins the primary color to `#0db2b6` and the + accent color to `#006166`. Navigation section labels in the sidebar use a + third brand tone, `#00797f`. + + The colors come from the same family the main `kubevirt.io` website defines in + `_sass/_colors.scss` as `$kv-color--green-300` through `$kv-color--green-700` + (for example, `#00797f` and `#006166`). The logo mark itself is distinctive + and is the only mark used in the guide's chrome, so a reader landing on any + page can identify the site as KubeVirt immediately. - Is the brand used across the website consistently? - Within the user guide, yes. The teal palette is applied globally through the - Material theme and `extra.css`, so the primary and accent colors are - consistent across all pages and are defined for both the light (`default`) and - dark (`slate`) schemes. The logo appears in the header site-wide, and section - labels in the navigation are given a coordinated teal tone (`#00797f`). One - caveat is that the user guide is a MkDocs Material site, while the main - `kubevirt.io` website is a separate property with its own styling, so the two - share the logo and general color family but do not share an identical look and - feel. + Yes, within the user guide. Logo, favicon, and palette are set once at the + theme level, so every page renders the same header, colors, and active-tab + underline without any per-page effort from authors. The dark scheme reuses the + same teal primary and accent values, so switching modes keeps the brand + intact. + + Consistency across the project's two web properties is partial. The main + `kubevirt.io` site is a Jekyll and Bootstrap site that uses the horizontal + wordmark `KubeVirt_logo_color.svg`, the Open Sans typeface, and a fully + documented SCSS color scale, while the user guide uses the square icon-only + mark, Roboto, and three hand-copied hex values. The two sites share the color + family and logo mark but differ in logo variant, typography, header layout, + and footer, so the transition between them is noticeable. The user guide's + `mkdocs.yml` defines no `extra.social` links or `copyright` footer, and the + `docs/assets` directory still contains legacy assets from a previous site + generator (`asciibinder-logo-horizontal.png`, `asciibinder_web_logo.svg`, + `book_pages_bg.jpg`) that are not referenced by any page. - Is the website's typography clean and well-suited for reading? - Yes. The guide does not override the theme fonts, so it inherits the Material - theme's default typeface (Roboto for body text and Roboto Mono for code), - which is a clean, legible sans-serif well-suited to on-screen reading. - Headings, body copy, tables, and code blocks are styled consistently by the - theme, code uses monospaced type with syntax highlighting, and tables are set - to full width (`min-width: 100%`) for readability. The custom - `filter: brightness(80%)` applied to links slightly darkens link text, which - is a minor contrast consideration but does not materially harm readability. - -##### Comment - -The KubeVirt user guide presents a clear and recognizable brand. The project's -teal heptagon logo appears in the site header, and the Material theme is -configured with a teal palette that is anchored to the exact brand colors in -`docs/stylesheets/extra.css` (`#0db2b6` primary and `#006166` accent). Because -these colors are defined at the theme level, the brand identity carries across -every page rather than depending on individual authors, which is the right -approach for a documentation site. - -Brand usage is consistent within the guide. The palette is defined for both the -light and dark color schemes, the logo and favicons are set globally, and -navigation section labels use a coordinated teal tone. The main point of -friction is cross-property consistency: the user guide is a MkDocs Material -site, while the primary `kubevirt.io` website is a separate property with its -own styling. The two share the logo and color family but not an identical look -and feel, so a reader moving between them will notice the shift. Documenting a -small set of shared brand values (hex colors, logo files, and font choices) -would help keep the properties aligned over time. - -Typography is clean and well-suited for reading. By not overriding the theme -fonts, the guide inherits Material's default Roboto and Roboto Mono, which are -legible on screen and applied consistently to headings, body text, tables, and -syntax-highlighted code. One minor design choice worth revisiting is the -`filter: brightness(80%)` rule applied to links, which darkens link text and -could reduce contrast in some contexts; verifying it against accessibility -contrast targets would remove any doubt. - -Overall, the branding and design are in good shape: the brand is identifiable, -applied consistently within the guide, and paired with readable typography. The -main opportunities are cross-site brand alignment and a quick contrast check of -the customized link styling. + Yes. The guide does not override the Material theme fonts, so it inherits + Roboto for body text and Roboto Mono for code, loaded from Google Fonts. + Headings, body copy, admonitions, tables, and syntax-highlighted code blocks + all use these two faces at Material's default sizes and line heights, which + are tuned for long-form technical reading. Inline code receives a light `1px` + border from `extra.css`, which helps distinguish identifiers from prose. + + Two custom rules affect readability. + `.md-nav a, .md-typeset a { filter: brightness(80%); }` darkens all link text, + including links inside the dark scheme, and its effect on contrast has not + been verified. `.md-typeset table:not([class]) { width: max-content; }` lets + wide tables extend past the content column and rely on horizontal scrolling, + which is useful for the many API-field tables but can crowd narrow view ports. + Typography differs from the main site, which uses Open Sans at a 16px base. + +#### Comment + +The KubeVirt user guide has a clear, recognizable identity. The teal heptagon +mark, the teal Material palette pinned to the project's own hex values, and the +coordinated sidebar label color together make every page unmistakably KubeVirt. +Because the branding is configured once in `mkdocs.yml` and +`docs/stylesheets/extra.css` rather than in individual pages, it stays +consistent across the roughly one hundred pages of the guide and across the +light and dark schemes without any effort from content authors. This is the +right model for a documentation site and is worth pointing to as an example. + +The main gap is that KubeVirt's brand is expressed in two different ways on its +two web properties. The main `kubevirt.io` site carries a documented SCSS color +scale, the horizontal wordmark, and Open Sans; the user guide carries three +copied hex values, the square icon, and Roboto. The colors are from the same +family, so nothing looks wrong, but there is no single source of truth for the +brand, and the guide's header and footer give the reader no visual or +navigational cue that it belongs to the larger site. Unused assets from a +previous site generator also remain in the repository. + +Typography is clean and well-suited to reading long technical pages, with a +sensible pairing of proportional and monospaced faces and good default spacing. +The only design choices worth a second look are the small custom CSS rules that +darken all links and let tables grow to their natural width, since both trade a +little readability for a stylistic or layout effect. + +Strengths: + +- Distinctive logo mark and brand colors applied at the theme level, so branding + is uniform on every page. +- Light and dark schemes share the same brand palette. +- Default Material typography (Roboto and Roboto Mono) is legible and + consistently applied to prose, tables, and code. +- Brand colors match the color family the main website defines, so the two + properties feel related. + +Weaknesses: + +- The user guide and `kubevirt.io` use different logo variants, typefaces, and + header and footer treatments, with no shared brand definition to keep them + aligned. +- The guide's header and footer contain no link back to `kubevirt.io` or to the + project's community channels. +- The `filter: brightness(80%)` link rule and the `max-content` table rule have + not been checked for contrast and small-viewport behavior. +- Legacy logos and a background image remain in `docs/assets` without being + used. Rating: 4 - Meets or exceeds standards -#### Case studies/social proof +### Case studies/social proof One of the best ways to advertise an open source project is to show other organizations using it. We evaluate on the following: @@ -1960,77 +2096,119 @@ organizations using it. We evaluate on the following: - Are there case studies available for the project and are they documented on the website? - There are case studies available for KubeVirt, but they are not documented on - the project website. The kubevirt.io navigation includes Blogs, Videos, - Gallery, Docs, Labs, and Community, but it has no dedicated case studies - section. - - Case studies live on external sites instead, such as the CNCF Swisscom case - study and third-party write-ups like Puzzle ITC's continuous integration - story. Because these are not linked from or hosted on kubevirt.io, a visitor - cannot find them from the project website. + Partially. Two CNCF-published end-user case studies feature KubeVirt: NTT + Docomo Business and Swisscom, both at `cncf.io/case-studies`. Neither the + `kubevirt.io` website nor the user guide links to them, so a visitor to either + property has no way to discover them. The `kubevirt.io` landing page and the + `ADOPTERS.md` file in the `kubevirt/kubevirt` repository also invite + contributors to submit "blog posts, case studies, or labs", and the user + guide's `contributing.md` repeats that invitation, but the website has no + case-study section or category and no blog post is tagged or titled as a case + study. + + The closest thing to project-hosted case studies is the `ADOPTERS.md` table, + which lists roughly 44 organizations across three types (End-user, + Integration, Vendor) with a "Since" year and a one- to three-sentence + "Use-Case" column. Several entries, such as Cloudflare, CoreWeave, NVIDIA, SK + Telecom, and S3NS, describe concrete production uses. This text is only in the + GitHub repository; the website reads the same organizations from + `_data/adopters.yml` but renders only logos and links, dropping the use-case + descriptions. - Are there user testimonials available? - Not evident. The website lists adopting organizations by logo, but there are - no quoted testimonials from users describing their experience or outcomes. The - user guide does not include or reference testimonials. + No, not in the form of attributed quotes on the website. The "Use-Case" + statements in `ADOPTERS.md` are written by the adopters in the first person + ("We use KubeVirt as part of our ...") and function as informal testimonials, + but they are not surfaced on `kubevirt.io` or in the user guide. The website's + Interviews video playlist contains community and contributor interviews rather + than customer testimonials. - Is there an active project blog? - Yes. The `kubevirt.io` site maintains an active blog with regular posts; - recent entries are dated 2026 (for example, "Beta Features Enabled by Default - in KubeVirt v1.9" and "Announcing the release of KubeVirt v1.8"), covering - releases, features, and technical topics. The blog lives on the main site; the - user guide links to release notes but does not link directly to the blog. + Yes, at `kubevirt.io/blogs`, with about 106 posts plus 24 "This Week in + KubeVirt" digests and a set of release announcements. Cadence has slowed + markedly: 24 to 25 posts per year in 2018 and 2019, 20 in 2020, 6 to 8 per + year from 2021 to 2023, 2 in 2024, 6 in 2025, and 3 so far in 2026 (most + recently September 2026). Recent posts are substantive (the v1.8 release, beta + features on by default in v1.9, a security audit announcement, cross-cluster + live migration networking). Categorization is thin: 92 posts are in the `news` + category, 12 in `uncategorized`, and tags are used inconsistently, so there is + no way to filter for adoption or user-story content. - Are there community talks for the project and are they present on the website? - Yes. The `kubevirt.io/videos/` page organizes community talks into curated - YouTube playlists, including Talks, Demos, Interviews, and the annual KubeVirt - Summit, alongside recorded community meetings. This content is well organized - on the main site, but the user guide does not surface or link to it. + Yes. The `kubevirt.io/videos` section has pages for Talks, Demos, Interviews, + KubeVirt Summit, and Weekly Meetings, each embedding a curated YouTube + playlist. The Summit page links per-year playlists for five past editions and + advertises the sixth annual KubeVirt Summit in October 2The following + recommendations address the SEO Analytics and Site Search of the KubeVirt user + guide.026 with its CfP dates. The Talks page also points to the community + Events wiki for upcoming CfPs and conference sessions. The user guide's + `contributing.md` links only to the New Contributor session recording; nothing + in the user guide points to the talks, demos, or Summit content. - Is there a logo wall of users/participating organizations? - Yes. The website homepage features a prominent logo wall grouped into End - Users (such as Arm, Aussie Broadband, Cloudflare, CoreWeave, and NVIDIA), - Vendors (such as Deckhouse, Microsoft, Oracle, Red Hat, and SUSE), and - Integrations. The user guide does not display or link to this logo wall. - -##### Comment - -KubeVirt has a strong base of community and adoption content, though it lives on -the main `kubevirt.io` website rather than in the user guide. The website -maintains an active blog with recent posts dated 2026, organizes community talks -into curated YouTube playlists (Talks, Demos, Interviews, and the annual -KubeVirt Summit), and presents an extensive logo wall of adopting organizations -grouped into End Users, Vendors, and Integrations. These are clear signals of a -healthy, active project and provide good social proof for prospective users. - -The main gaps are dedicated case studies and user testimonials. The adopter logo -walls show who uses KubeVirt but do not explain how or why, and there are no -quoted testimonials describing real-world outcomes. Narrative case studies, even -a small number, would help prospective adopters understand practical use cases, -migration paths, and the benefits organizations have realized. These carry -particular weight for an infrastructure project where adoption decisions are -significant. - -From the user guide's perspective, the more immediate issue is discoverability. -The guide is technical documentation and does not link to the blog, community -talks, or adopter logo wall at all. A reader who lands in the user guide has no -easy path to this adoption and community content, even though it exists one site -over. Adding a few targeted links, for example from the landing page or a -"Community" or "Adopters" entry, would connect readers to material that builds -confidence in the project. - -Overall, the project scores well on blog, talks, and a logo wall, but lacks true -case studies and testimonials, and the user guide does not surface the adoption -content that already exists. Closing those gaps would round out this area. + Yes. The `kubevirt.io` landing page renders three logo walls ("End Users", + "Vendors", and "Integrations") from `_data/adopters.yml`, which is generated + by `adopters.py` and kept in sync with `ADOPTERS.md` through a documented + two-step PR process. Each logo links to the organization's site and shows the + name in a tooltip. The wall shows who uses KubeVirt but not how or why, + because the use-case text is not carried over. The user guide does not display + or link to the logo wall. + +#### Comment + +KubeVirt has more adoption evidence than its websites show. The project +maintains a curated adopters list with first-person use-case statements from +well-known production users, publishes talks, demos, interviews, and five years +of Summit recordings, keeps a blog that still produces substantive release and +feature posts, and is featured in two CNCF-published end-user case studies. The +logo wall and video section on `kubevirt.io` are well organized and clearly +signal an active, widely adopted project. + +The weakness is that the most persuasive material is disconnected from where +prospective users look. The CNCF case studies are not linked from either +property, the adopter use-case statements live only in a GitHub Markdown table +while the website shows bare logos, and no blog category or page collects user +stories. The result is that the project appears to have a logo wall and a blog +but no case studies or testimonials, when in fact it has the raw material for +both. Blog cadence has also fallen from about two posts a month to a handful a +year, and the flat `news` category makes the archive hard to browse by theme. + +From the user guide's side, the gap is discoverability. The guide is where +evaluators end up when they want to know whether KubeVirt fits their +environment, yet its landing page and navigation contain no link to adopters, +case studies, talks, or the blog. Only `contributing.md` mentions the website's +community content, and it frames it as a place to contribute rather than a place +to learn. + +Strengths: + +- Curated adopters list with a "Since" year and first-person use-case text for + roughly 44 organizations, including major production users. +- Three-category logo wall on the landing page, kept in sync with `ADOPTERS.md` + through a documented process. +- Video section with separate Talks, Demos, Interviews, Summit, and Weekly + Meetings playlists, plus an annual Summit with a public CfP. +- Blog posts remain technically substantive when published. + +Weaknesses: + +- Two CNCF case studies featuring KubeVirt are not linked from `kubevirt.io` or + the user guide. +- Adopter use-case statements are dropped when the adopters list is rendered as + a logo wall. +- No attributed testimonials, case-study page, or blog category for user + stories. +- Blog cadence has declined sharply since 2020 and categorization is nearly + flat. +- The user guide does not link to adopters, case studies, talks, or the blog. Rating: 3 - Meets standards -#### SEO, Analytics and site-local search +### SEO, Analytics and site-local search SEO helps users find your project and it's documentation, and analytics helps you monitor site traffic and diagnose issues like page 404s. Intra-site search, @@ -2039,93 +2217,121 @@ evaluate on the following: - Is analytics enabled for the production server? - No. The user guide's `mkdocs.yml` has no `extra.analytics` configuration, and - the live production pages contain no analytics tags (no Google Analytics, - Google Tag Manager, or measurement ID). The main `kubevirt.io` homepage - likewise shows no analytics tags. This appears consistent with the project's - privacy stance, but it means no usage analytics are collected. + Partially. The main website (kubevirt.io, built from the kubevirt.github.io + repository) loads Adobe Analytics through a Red Hat–hosted tag script + (`//www.redhat.com/ma/dpal.js`) in `_includes/head.html`, so page views on the + main site are collected. The user guide (kubevirt.io/user-guide, built from + this repository with MkDocs) has no analytics of any kind: `mkdocs.yml` + contains no `extra.analytics` block, and the rendered pages load only the + Material theme bundle. The main site also carries a `google-site-verification` + meta tag, indicating that Google Search Console is set up for the domain. - Is analytics disabled for all other deploys? - Not applicable in practice. Because no analytics is configured anywhere, it is - inherently absent from pull-request previews and non-default branch builds as - well. The intended "production-only analytics" pattern cannot be assessed - since there is no analytics to scope. + No for the main site; not applicable for the user guide. The Adobe Analytics + script is included unconditionally in the main site's `head.html`, with no + check on the Jekyll environment or the Netlify deploy context, so it also runs + on Netlify deploy previews and local builds. The user guide has no analytics + in any deploy, including the Netlify production alias + (`kubevirt-user-guide.netlify.app`) and pull-request previews. - If project is using Google Analytics, has it migrated to GA4? - Not applicable. The project does not use Google Analytics on the user guide, - so there is no Universal Analytics or GA4 property in use to migrate. + Not applicable. The project uses Adobe Analytics rather than Google Analytics, + so there is no Universal Analytics property to migrate. No `G-` or `UA-` + measurement ID appears in either repository or in the rendered pages. - Can Page-not-found (404) reports easily be generated from site analytics? - No. Material for MkDocs generates a `404.html` page, but without any analytics - in place there is no mechanism to report on 404 hits or generate not-found - reports from site analytics. + Not for the user guide, because it has no analytics; broken inbound links to + the user guide are invisible. Both sites do serve proper 404 responses (the + user guide returns HTTP 404 with the Material theme's not-found page, and the + main site has a custom `404.html`), so a 404 report would be possible if + page-level analytics were collecting the URL. For the main site, whether a 404 + report is available depends on the Adobe Analytics workspace that Red Hat + administers, and nothing in the repositories documents how to obtain one. - Is site indexing supported for the production server, while disabled for website previews and builds for non-default branches? - Partially. Production indexing is supported: a site-wide `robots.txt` is - served (returning 200) with a `Sitemap` directive and no `Disallow` rules, - MkDocs generates a `sitemap.xml`, and pages carry no `noindex` meta tag. - Pull-request previews are built on Netlify, whose deploy-preview and - branch-deploy subdomains are served with a `noindex` `X-Robots-Tag` by - Netlify's default behavior; however, this preview-noindex behavior is not - explicitly configured in `netlify.toml`, so it relies on the platform default - rather than an intentional project setting. One minor SEO defect is that the - `robots.txt` Sitemap URL contains a double slash - (`https://kubevirt.io//sitemap.xml`). + Indexing is supported in production. The main site generates a sitemap with + `jekyll-sitemap`, and MkDocs generates + `https://kubevirt.io/user-guide/sitemap.xml`, which resolves with HTTP 200. + Each user-guide page sets a canonical link to + `https://kubevirt.io/user-guide/...` because `site_url` is set in + `mkdocs.yml`, and the canonical is preserved on the Netlify alias, which + steers search engines to the production URL. The `robots.txt` at kubevirt.io + contains only a Sitemap directive (with a stray double slash, + `https://kubevirt.io//sitemap.xml`) and does not reference the user guide + sitemap. Neither repository sets a `noindex` meta tag or `X-Robots-Tag` header + for previews; the project relies on Netlify's default behavior of marking + deploy-preview URLs as `noindex`. The `netlify.toml` in this repository still + runs a `sed` command that rewrites `site_url: https://kubevirt.io/docs`, a + value that no longer exists in `mkdocs.yml`, so that step is a no-op. - Is local intra-site search available from the website? - Yes. The MkDocs `search` plugin is enabled in `mkdocs.yml` (with a customized - separator), and the Material theme provides the search box and results UI, - giving readers client-side, intra-site search across the user guide. + Yes for the user guide, and only partially for the main site. The user guide + enables the MkDocs Material `search` plugin with a custom token separator, and + the search box appears in the header on every page. The main site has a + `search.html` page backed by lunr.js, but its index is built only from + `site.posts`, so it covers blog posts and not the main site's other pages. + Neither search covers the other site; a user-guide search does not surface + blog or main-site content, and the main-site search does not surface + user-guide pages. - Are the current custodian(s) of the analytics accounts (such as Google CSE) documented? - No. No analytics or search-account custodians are documented in the - repository. Since no analytics account currently exists there is nothing to - attribute, but there is also no documented owner should analytics be - introduced. - -##### Comment - -The KubeVirt user guide handles site search and basic SEO well but has no -analytics at all. Local intra-site search is enabled through the MkDocs `search` -plugin and surfaced by the Material theme, giving readers fast client-side -search across the documentation. For discoverability, the production site is -indexable: a site-wide `robots.txt` is served with a `Sitemap` directive and no -blocking rules, MkDocs generates a `sitemap.xml`, and pages carry no `noindex` -tag. Pull-request previews are built on Netlify, whose preview subdomains are -`noindex` by default, which keeps previews out of search results. - -The clear gap is analytics. Neither the user guide nor the main site includes -any analytics tags, so there is no visibility into traffic, popular pages, -search terms, or broken links. In particular, 404 reports cannot be generated -from analytics, which makes it harder to find and fix broken inbound links over -time. This absence appears consistent with the project's privacy posture, and -that is a legitimate trade-off; but if the project wants data to guide -documentation improvements, a privacy-respecting analytics option would fill an -important blind spot. - -If analytics is introduced, a few practices are worth adopting up front. Use a -GA4 property (or a privacy-friendly alternative), enable it only on the -production deploy while leaving previews and non-default branches untracked, and -document the account custodians so ownership is clear as maintainers change. -Configuring these through the theme rather than per page keeps the setup -consistent. - -Two smaller items round out the SEO picture: make the preview `noindex` behavior -an explicit project setting rather than relying on the Netlify default, and fix -the double slash in the `robots.txt` Sitemap URL -(`https://kubevirt.io//sitemap.xml`). + No. Neither repository documents who administers the Adobe Analytics property, + the Netlify sites (`kubevirt-user-guide` and the main site), or the Google + Search Console verification. The `OWNERS` and `OWNERS_ALIASES` files list code + approvers and reviewers only, and the README mentions the Netlify Open Source + plan without naming an account owner. Because the analytics script is served + from redhat.com, access to the data appears to be held by Red Hat staff rather + than by the project, and that dependency is not recorded anywhere. + +#### Comment + +The KubeVirt web presence splits across two sites with very different analytics +postures. The main site collects data through a Red Hat–administered Adobe +Analytics tag, while the user guide, which is the documentation users spend most +of their time in, collects nothing. As a result the project has no visibility +into which documentation pages are read, which searches fail, or which inbound +links break. The main site's tag is also loaded on every deploy, so preview +traffic is mixed into production numbers. + +Search-engine fundamentals are in reasonable shape. Both sites produce sitemaps, +the user guide emits correct canonical URLs even on its Netlify alias, and +Google Search Console is verified for the domain. Local search works well in the +user guide thanks to the MkDocs Material plugin, though the main site's lunr +search indexes only blog posts and neither site can search the other. The +biggest governance gap is that nobody is named as custodian of the analytics, +Netlify, or Search Console accounts, and the project's dependence on a +vendor-hosted analytics account is undocumented. + +Strengths: + +- Full-text local search in the user guide, with a tuned separator for technical + tokens. +- Sitemaps for both sites and correct canonical links on user-guide pages. +- Google Search Console verification on the production domain. +- Proper HTTP 404 responses and custom not-found pages on both sites. + +Weaknesses: + +- No analytics on the user guide, so page-level usage and 404 data for + documentation are unavailable. +- Main-site analytics run on previews and local builds as well as production. +- Main-site search indexes blog posts only, and there is no cross-site search. +- The `robots.txt` on kubevirt.io references a malformed sitemap URL and omits + the user-guide sitemap. +- Custodians of the analytics, Netlify, and Search Console accounts are not + documented. Rating: 2 - Needs improvement -#### Maintenance planning +### Maintenance planning Website maintenance is an important part of project success, especially when project maintainers aren’t web developers. We evaluate on the following: @@ -2134,212 +2340,355 @@ project maintainers aren’t web developers. We evaluate on the following: Docsy theme) or commonly used by CNCF projects? Yes. The user guide is built with MkDocs and the Material for MkDocs theme, - along with the `awesome-nav`, `redirects`, and `html-proofer` plugins (see - `mkdocs.yml`, `Makefile`, and `netlify.toml`). While this is not the Hugo and - Docsy stack named in the question, MkDocs Material is a mature, actively - maintained, and widely adopted documentation tool used across many CNCF and - Kubernetes-ecosystem projects, so the tooling is well supported. Note that the - main `kubevirt.io` website is a separate Jekyll site, so the project maintains - two different stacks. + plus the `mkdocs-awesome-nav` and `mkdocs-redirects` plugins. All four are + actively maintained, widely used open-source projects, and MkDocs Material in + particular is common among CNCF and Kubernetes-ecosystem projects. The main + website (kubevirt.io) is a Jekyll site with a hand-built Bootstrap 4 layout + and a dozen Jekyll plugins; Jekyll is mature and well supported but is less + common among CNCF projects than Hugo or Docusaurus, and the custom theme means + design changes fall entirely on the project. The two sites use different + static-site generators, so maintainers need to know both toolchains. - Is there active cultivating website maintainers from within the community? - Yes. The repository has an `OWNERS` file that defines reviewers and approvers - roles (via aliases) and lists emeritus approvers, and the project uses the - Kubernetes-style OWNERS model for delegating maintenance. Git history shows - sustained activity, with roughly 49 distinct authors contributing in the last - 12 months and a steady stream of merged pull requests, indicating an active - and growing maintainer and contributor base. + Only informally. Both repositories have `OWNERS` files with active reviewer + and approver lists, and the main website's `OWNERS` file records emeritus + approvers with dates, which shows the roster is periodically pruned. The + website README explicitly invites UI/UX developers to pick up `kind/website` + issues, and the user guide README says contributions are welcome. However, + there is no documented path from contributor to website maintainer, and the + community `sig-list.md` shows a `sig/documentation` label with no chairs or + members. Commit history over the past year shows one person as the top human + committer in both repositories, with most other contributions coming from + feature authors documenting their own work or from Dependabot. - Are site build times reasonable? - Yes. MkDocs produces a static site of this size quickly, typically well under - a minute, and the build is a straightforward `mkdocs build`. Netlify builds - preview deployments for pull requests and the project's Prow-based CI builds - the site as well, so build times are reasonable for both previews and - production. + Yes. Both sites are built by a Prow post submit job that runs `make build` and + pushes the output to a `gh-pages` branch served by GitHub Pages. Comparing + commit timestamps on `main` with the corresponding post submit site update + commits on `gh-pages` shows the user guide is republished within about 40 + seconds of a merge and the main website within about 90 seconds. Pull-request + previews for the user guide build on Netlify from a pinned `netlify.toml` + command that installs MkDocs with `pip` on every build. The `netlify.toml` + still contains a `sed` step that targets an obsolete `site_url` value and does + nothing, which is harmless but suggests the file has not been reviewed + recently. - Do site maintainers have adequate permissions? - Yes. Permissions are managed through the Kubernetes-style OWNERS model, where - designated approvers can approve and merge changes and reviewers can review. - The `OWNERS` file separates reviewers and approvers and records emeritus - approvers, giving maintainers the access they need while keeping the roles - documented. + Partly documented. Merging is governed by Prow and the `OWNERS` files, so + approvers can land content changes without additional access. Deployment is + fully automated through the `kubevirt-bot` account, which pushes to + `gh-pages`, so no maintainer needs push rights to the published branch. Access + to the supporting services is not documented: nothing in either repository + states who can administer the Netlify site (`kubevirt-user-guide`), the GitHub + Pages and custom-domain settings, DNS for kubevirt.io, or the Prow job + definitions in `kubevirt/project-infra`. Whether current approvers hold those + permissions cannot be determined from the repositories. - Is the website accessible via HTTPS? - Yes. Requesting `https://kubevirt.io/user-guide/` returns HTTP 200 over HTTPS. + Yes. Both `https://kubevirt.io/` and `https://kubevirt.io/user-guide/` are + served over HTTPS by GitHub Pages with a valid certificate for the custom + domain. The Netlify preview alias `https://kubevirt-user-guide.netlify.app/` + is also served over HTTPS. - Does HTTP access, if any, redirect to HTTPS? - Yes. Requesting `http://kubevirt.io/user-guide/` returns a 301 redirect to the - HTTPS URL, and the apex `http://kubevirt.io/` likewise 301-redirects to HTTPS. - -##### Comment - -The KubeVirt user guide is on a solid maintenance footing. It is built with -MkDocs and the Material for MkDocs theme, supplemented by the `awesome-nav`, -`redirects`, and `html-proofer` plugins. Although this differs from the Hugo and -Docsy stack, MkDocs Material is a mature and widely adopted documentation -toolchain used across the CNCF and Kubernetes ecosystems, so maintainers can -rely on strong community support and a steady stream of upstream updates. - -Maintenance responsibility is clearly structured and actively exercised. The -repository uses the Kubernetes-style OWNERS model, defining reviewers and -approvers roles and recording emeritus approvers, which gives maintainers -appropriate permissions to review and merge changes. The commit history reflects -a healthy, cultivated community, with roughly 49 distinct authors in the last -twelve months and a continuous flow of merged pull requests, so the guide is not -dependent on a single maintainer. - -The build and hosting setup is dependable. MkDocs builds this static site -quickly, Netlify produces per-pull-request previews, and the project's -Prow-based CI builds the site as well. The site is served securely: HTTPS -returns a 200 response, and HTTP requests are 301-redirected to HTTPS for both -the user guide path and the apex domain. These are exactly the properties one -wants for low-friction, secure maintenance. - -The main opportunities are around build reproducibility and stack consolidation. -The build installs MkDocs and its plugins without pinned versions (in -`netlify.toml` and the `Makefile`), which risks non-reproducible builds or -breakage when an upstream package changes; pinning versions would harden this. -Maintaining two separate stacks (MkDocs for the user guide and Jekyll for the -main site) also adds ongoing overhead worth periodically reviewing. + Yes. Requests to `http://kubevirt.io/`, `http://www.kubevirt.io/`, and + `http://kubevirt.io/user-guide/` all return `301 Moved Permanently` to the + HTTPS equivalent (with `www` also collapsing to the bare domain), and the + Netlify alias redirects HTTP to HTTPS as well. The production responses do not + include a `Strict-Transport-Security` header, so browsers rely on the redirect + rather than HSTS to enforce HTTPS on repeat visits. + +#### Comment + +The KubeVirt documentation infrastructure is low-maintenance by design and +largely automated. The user guide runs on MkDocs Material, one of the most +widely adopted documentation stacks in the cloud-native ecosystem, and both +sites are published to GitHub Pages by a Prow job within a minute or two of +merge. HTTPS is enforced everywhere, Netlify provides pull-request previews, and +Dependabot keeps the Jekyll site's dependencies current. For a project of +KubeVirt's size, the tooling choices are sensible and the deploy pipeline is +fast and hands-off. + +The risk lies in people rather than tooling. The two sites use different +generators, so a maintainer must know both Jekyll and MkDocs, and the main +site's hand-built Bootstrap theme has no upstream to inherit fixes from. Commit +history shows the documentation effort leaning on a single active maintainer, +the community's `sig/documentation` label has no chairs or members, and neither +repository describes how someone grows into a website maintainer role or who +holds the keys to Netlify, DNS, GitHub Pages settings, and the Prow job +definitions. If that maintainer stepped away, the project would have working +automation but no documented map of who can change it. -Rating: 4 - Meets or exceeds standards +Strengths: -### Recommendations - -> AUTHOR NOTE: Write general recommendations based on the comments from the -> previous section. - -#### Single-source requirement - -#### Minimal website requirements - -#### Usability, accessibility and devices - -- Increase color contrast for the brand teal primary color (`#0db2b6` in - `docs/stylesheets/extra.css`) so that white header text meets the WCAG AA - contrast ratio of at least 4.5:1 for normal text, either by darkening the teal - or by adjusting the text color placed on it. -- Adjust the body link color (currently the primary color darkened with - `filter: brightness(80%)`) so that links reach at least 4.5:1 contrast against - the page background, rather than the roughly 3.96:1 they achieve today. -- Verify all contrast changes in both the light (`default`) and dark (`slate`) - schemes, checking header text, links, navigation section labels, and code - blocks. -- Add a-ln automated accessibility and contrast check to the site build (for - example, a Lighthouse or axe-based check) so contrast regressions are caught - before publishing. -- Continue requiring descriptive, non-empty alt text on all images and maintain - correct heading order in new pages, so screen-reader and text-to-speech users - keep getting a good experience. -- Preserve the existing strengths, keeping the responsive viewport, mobile - drawer navigation, site search, in-page table of contents, skip-to-content - link, and ARIA labels intact as the theme is upgraded. - -#### Branding and design - -- Document a small set of shared brand values in the repository, such as the - brand hex colors (`#0db2b6` and `#006166`), the logo and favicon files, and - the chosen fonts, so the branding is defined in one place rather than implied - by the theme configuration. -- Align the user guide's look and feel more closely with the main `kubevirt.io` - website by agreeing on a shared logo, color family, and typography across both - properties, so readers experience a consistent brand as they move between the - sites. -- Verify the customized link styling (`filter: brightness(80%)` in - `docs/stylesheets/extra.css`) against accessibility contrast targets in both - the light and dark schemes, and adjust or remove the filter if it reduces - contrast below recommended levels. -- Keep relying on the Material theme's default Roboto and Roboto Mono - typography, and if a custom font is ever introduced, apply it through the - theme configuration so it remains consistent across all pages. -- Confirm the teal palette renders correctly in the dark (`slate`) scheme, - checking that logo, links, code blocks, and navigation labels retain - sufficient contrast and remain on-brand. -- Continue defining brand colors through theme-level variables in `extra.css` - rather than per-page styling, so the brand stays consistent as new pages are - added. - -#### Case studies/social proof - -- Publish a small set of narrative case studies on the project website that - describe how specific organizations adopted KubeVirt, the problems they - solved, and the outcomes they achieved, going beyond the existing adopter logo - walls. -- Gather and display user testimonials, for example short quotes from adopting - organizations, to complement the logo walls with real-world perspectives on - the project's value. -- Link the user guide to the project's adoption and community content so readers - can discover it, for example by adding references to the blog, the community - talks and videos page, and the adopters logo wall from the user guide landing - page. -- Add a "Community" or "Adopters" entry to the user guide that points to the - case studies, testimonials, and logo wall once they exist, giving - documentation readers a clear path to social proof. -- Continue maintaining the active blog and the curated talk playlists (Talks, - Demos, Interviews, and KubeVirt Summit), and consider surfacing the most - relevant posts or talks from within related documentation pages. -- Where a case study or talk illustrates a documented feature, cross-link it - from the corresponding user guide page so readers can see the feature applied - in practice. - -#### SEO, Analytics and site-local search - -- Decide whether to adopt analytics for the documentation, and if so, choose - either a GA4 property or a privacy-respecting alternative that aligns with the - project's privacy policy, so maintainers gain visibility into traffic and - popular content. -- If analytics is adopted, enable it only on the production deploy and keep it - disabled for pull-request previews and non-default branch builds, configuring - it through the Material theme's analytics integration rather than per page. -- If analytics is adopted, ensure Page-not-found (404) reporting is available so - broken inbound links can be identified and fixed over time. -- Document the custodians of any analytics or search accounts (for example, who - owns the analytics property) in the repository, so ownership remains clear as - maintainers change. -- Make the preview `noindex` behavior an explicit project setting (for example, - an `X-Robots-Tag` header for Netlify preview and branch deploys) rather than - relying solely on the Netlify default, so indexing rules are intentional and - documented. -- Fix the double slash in the `robots.txt` Sitemap URL - (`https://kubevirt.io//sitemap.xml`) so it points to a single canonical - sitemap location. -- Keep the MkDocs `search` plugin enabled and continue to benefit from the - Material theme's intra-site search, periodically reviewing the search - separator configuration as content grows. - -#### Maintenance planning - -- Pin the versions of MkDocs and its plugins (`mkdocs`, `mkdocs-material`, - `mkdocs-awesome-nav`, `mkdocs-redirects`, and `mkdocs-html-proofer-plugin`) in - the build definitions, for example via a `requirements.txt`, so that Netlify - and Prow builds are reproducible and resistant to breaking upstream changes. -- Keep the pinned dependency versions current through a regular update cadence, - ideally automated (for example with Dependabot or Renovate), so the guide - continues to benefit from the actively maintained MkDocs Material toolchain. -- Continue cultivating maintainers through the OWNERS model, and periodically - review the reviewers and approvers lists to confirm they reflect currently - active contributors and that coverage is not concentrated in too few people. -- Preserve the existing HTTPS posture, keeping the site accessible over HTTPS - and retaining the HTTP-to-HTTPS redirects for both the user guide path and the - apex domain. -- Periodically review the overhead of maintaining two separate stacks (MkDocs - for the user guide and Jekyll for the main `kubevirt.io` site), and consider - whether consolidation or closer alignment would reduce long-term maintenance - effort. -- Document the local and CI build process (build commands, dependencies, and - preview workflow) in a contributor-facing location so new maintainers can - reproduce and troubleshoot builds easily. - -#### Other - -#### References and notes - -##### Rating values +- MkDocs Material for the user guide is well supported and common among CNCF + projects. +- Fully automated publish pipeline: merge to `main` triggers a Prow job that + pushes to `gh-pages` in roughly 40 to 90 seconds. +- HTTPS everywhere, with HTTP and `www` redirecting to the canonical HTTPS + domain. +- `OWNERS` files are maintained, including dated emeritus entries on the website + repository. +- Netlify pull-request previews and a periodic Prow link checker catch problems + before and after publish. + +Weaknesses: + +- Two different static-site generators and a custom Jekyll theme double the + maintenance surface. +- No documented path for cultivating website maintainers; the + `sig/documentation` entry in the community SIG list is empty. +- Heavy reliance on one active documentation maintainer across both + repositories. +- Administrative access to Netlify, DNS, GitHub Pages, and Prow job definitions + is undocumented. +- No `Strict-Transport-Security` header on production responses. + +Rating: 3 - Meets standards + +## Website & Infrastructure - Recommendations + +### Single-source requirement + +- Document the content boundary. Add a short "Where documentation lives" section + to the README of `kubevirt/user-guide`, `kubevirt/kubevirt.github.io`, and + `kubevirt/kubevirt` stating that user and operator documentation belongs in + the user guide, marketing, blog, and community content belongs on the website, + and `kubevirt/kubevirt/docs` is for design and developer notes only. Link to + it from `docs/contributing.md` in the user guide. +- Audit `kubevirt/kubevirt/docs` for user-facing content. Start with the files + the user guide already links to (`getting-started.md`, `architecture.md`, + `cloud-init.md`), move the user-facing portions into the guide, and replace + the originals with a one-line pointer so search results and old links still + resolve. +- Do the same triage for the CDI `doc/` directory: move the pages the user guide + links to from six storage pages into the guide's `storage/` section, or add a + clear "CDI reference documentation" page in the guide that explains why the + rest remains in the CDI repository. +- Decide whether the website and user guide should share a repository, and + record the decision. If they stay separate, note the reason (different + generators, maintainers, and audiences) in both READMEs. If the project later + converges the two toolchains, as suggested in the maintenance-planning + recommendations, move the website pages into the user-guide repository or + bring the guide into the website repository as a Git submodule. +- Give the API reference a visible home in the user guide by adding a navigation + entry or landing page that links to `kubevirt.github.io/api-reference`, so + readers do not need to know it is published from a separate repository. + +### Website requirements + +- Bring the user guide footer into compliance. Set + `copyright: "Copyright © KubeVirt a Series of LF Projects, LLC"` in + `mkdocs.yml`, and add an `overrides/partials/copyright.html` (or a + `footer.html` override) that appends "We are a Cloud Native Computing + Foundation incubating project", the CNCF logo linked to `cncf.io`, and a link + to `https://lfprojects.org/policies/` for trademark and terms. Match the + wording and links used in the main website footer so the two properties read + as one. +- Add the © symbol to the main website copyright line in `_includes/footer.html` + so it reads "Copyright © KubeVirt a Series of LF Projects, LLC". +- Point vendor logos at KubeVirt-specific pages. For each entry in `ADOPTERS.md` + whose link is a corporate homepage, ask the vendor for a URL that mentions + KubeVirt support or their KubeVirt-based product, and update the link; drop + the logo from the Vendors section if none exists. +- Add a root `CODE_OF_CONDUCT.md` to both `kubevirt/user-guide` and + `kubevirt/kubevirt.github.io` that links to the `kubevirt/community` code of + conduct, so the file is present where the checklist expects it rather than + only inherited from the organization default. +- Add a `CONTRIBUTING.md` to `kubevirt/kubevirt.github.io` that points to the + existing contributing content in its README and to the user guide's + contributing page. +- Update the maturity statement in both footers when the project's CNCF status + changes, and add a note in each repository's README naming the file to edit so + the statement does not go stale. + +### Usability, accessibility and devices + +- Fix the header and link contrast in `docs/stylesheets/extra.css`. Darken + `--md-primary-fg-color` to a teal that gives at least 4.5:1 against white (for + example `#007a7e` or darker), or keep the brand teal for decorative elements + only and set the header and tab text to a dark foreground. Check links against + the same 4.5:1 target and remove the `filter: brightness(80%)` hack in favor + of an explicit color. Verify both light and dark schemes with a contrast + checker. +- Replace the ASCII stack diagram on the Architecture page with an image that + has descriptive alt text or, better, a Mermaid diagram (enable + `pymdownx.superfences` custom fences for `mermaid` in `mkdocs.yml`) + accompanied by a one-paragraph prose description of the layers, so screen + reader users and mobile readers get the same information. +- Convert `$`-prefixed indented code blocks to fenced blocks with a language tag + and no prompt, and separate output into its own block. Start with the pages on + the new-user path (Installation, Lifecycle, `virtctl`) and the longest + reference pages (Disks and Volumes, Export API). This helps screen readers, + copy-paste, and mobile scrolling at once. +- Enable `content.code.copy` in `theme.features` so long commands can be copied + without horizontal scrolling, and break commands over 100 characters across + lines with `\` continuations in the source. +- Verify on a phone that tables on the Arm64 feature-gate and device status + pages scroll horizontally rather than overflowing the page; if they overflow, + remove the `display: table; width: max-content` override from `extra.css` or + scope it to specific tables with `attr_list` classes. +- Split or restructure pages over about 500 lines. Candidates are Disks and + Volumes (split by volume type), Interfaces and Networks (split binding methods + from network attachment), and Live Migration (move migration strategies and + network configuration to sub-pages). Split Release Notes into one page per + minor release or paginate it, and set the Release Notes tab to open the newest + release. +- Set the logo alt text to "KubeVirt" by adding `extra.homepage` or a custom + `partials/logo.html` override, and add a short caption or introductory + sentence above each wide status table stating what the table shows. +- Add an accessibility check to the Makefile and Prow pre submit, for example + running `pa11y-ci` or Lighthouse against the built site for a sample of pages, + so contrast regressions are caught in pull requests. + +### Branding and design + +- Publish a short brand reference, either in the `kubevirt.github.io` repository + or in the `community` repository, that lists the canonical logo files (icon + and horizontal wordmark), the hex values of the `$kv-color--green-*` scale, + and the approved typefaces. Have `docs/stylesheets/extra.css` in the user + guide cite that reference in a comment so the two sites stay aligned when the + palette changes. +- Align the user guide's brand tokens with the main site's scale. Replace the ad + hoc `#0db2b6` primary with a value from the documented scale (for example, + `$kv-color--green-300`, `#00aab2`), or add `#0db2b6` to the scale so both + properties draw from the same list. +- Add an `extra.social` block and a `copyright` line to `mkdocs.yml` so the + Material footer shows the project's GitHub, Slack, and `kubevirt.io` links. + This gives readers a visual and navigational link between the guide and the + main site at almost no cost. +- Consider using the horizontal `KubeVirt_logo_color.svg` wordmark in the + guide's header, or add the wordmark to the main site's header alongside the + icon, so both properties present the same logo variant. +- Check the `filter: brightness(80%)` link rule against WCAG AA contrast in both + the light and dark schemes. If it fails, replace the filter with explicit + `--md-typeset-a-color` values per scheme so the link color is deliberate + rather than derived. +- Review the `.md-typeset table:not([class]) { width: max-content; }` rule on a + narrow viewport. If wide tables push past the content column, scope the rule + to a class applied only to tables that need it, or wrap those tables so they + scroll within the column. +- Remove the unused legacy assets `asciibinder-logo-horizontal.png`, + `asciibinder_web_logo.svg`, and `book_pages_bg.jpg` from `docs/assets` so the + repository contains only current brand assets. +- Remove the unsupported top-level `site_favicon` key from `mkdocs.yml`; MkDocs + ignores it and the active favicon is already set under `theme.favicon`. + +### Case studies/social proof + +- Link the two existing CNCF case studies (NTT Docomo Business and Swisscom) + from `kubevirt.io`, for example in a "Case Studies" block beneath the End + Users logo wall on the landing page. This is a quick win: the content already + exists and is published by CNCF. +- Extend `adopters.py` and `_data/adopters.yml` to carry the "Use-Case" text + from `ADOPTERS.md`, and show it on the website as a tooltip or an expandable + card on each logo. This turns the logo wall into a set of short, attributed + testimonials at no authoring cost. +- Create a `/adopters/` or `/case-studies/` page on `kubevirt.io` that renders + the full adopters table (type, name, since, use case) and links to the CNCF + case studies, so evaluators have a single place for adoption evidence. Add it + to `_data/site_nav_pages.yml`. +- Invite two or three adopters with strong use-case statements (for example + Cloudflare, CoreWeave, or SK Telecom) to expand them into short blog posts or + Summit talks, and tag those posts with a `case-study` or `user-story` category + so they can be listed together. +- Add a blog category or tag scheme beyond `news` and `uncategorized`, and + backfill recent posts, so the blog index can filter by release, feature, + community, and user story. +- Set a modest publishing target for the blog, such as one post per KubeVirt + minor release plus one community or adopter post per quarter, and track it in + the community repository so cadence does not depend on a single author. +- In the user guide, add a short "Community and adoption" block to + `docs/index.md` that links to the `kubevirt.io` blog, videos, Summit, adopters + or case-studies page, and Slack. Optionally add a top-level "Community" entry + to `docs/.nav.yml` that opens the `kubevirt.io/community` page. +- In `docs/contributing.md`, in addition to inviting readers to submit case + studies, link to the existing adopters list and case studies so contributors + can see the format they are being asked to follow. + +### SEO, Analytics and site-local search + +- Enable analytics on the user guide. Add an `extra.analytics` block to + `mkdocs.yml` (Material supports Google Analytics 4 natively, or use a custom + `overrides/main.html` partial to load the same Adobe Analytics tag the main + site uses) so documentation page views, search terms, and 404 hits are + captured. +- Gate analytics to production only. In the main site, wrap the `dpal.js` + include in `_includes/head.html` with a check on + `jekyll.environment == "production"` and set `JEKYLL_ENV=production` only in + the Netlify production context. In the user guide, inject the analytics + snippet only when the Netlify `CONTEXT` variable equals `production`, for + example by templating it in the `netlify.toml` build command. +- Add an explicit `noindex` for non-production deploys rather than relying on + Netlify defaults. Emit `X-Robots-Tag: noindex` from a `_headers` file or a + `[context.deploy-preview]` / `[context.branch-deploy]` section in each + repository's `netlify.toml`. +- Fix `robots.txt` on kubevirt.io: correct the sitemap URL to + `https://kubevirt.io/sitemap.xml` and add a second `Sitemap:` line for + `https://kubevirt.io/user-guide/sitemap.xml`. +- Remove the obsolete `sed` line in this repository's `netlify.toml` that + rewrites `site_url: https://kubevirt.io/docs`, since `mkdocs.yml` already sets + `site_url` to `https://kubevirt.io/user-guide` and the command no longer has + any effect. +- Extend the main site's lunr index in `_layouts/search.html` to include + `site.pages` in addition to `site.posts` so that non-blog pages are + searchable, and add a link from the main site's search page to the user guide + search (or vice versa) so users can find documentation from either entry + point. +- Document analytics custodianship. Add a short "Site infrastructure" section to + the README of each repository (or to the SIG Docs or community repository) + that names the owners or aliases responsible for the Adobe Analytics property, + the Netlify sites, and Google Search Console, and describes how a maintainer + requests access or a 404 report. +- Once analytics are in place, set up a recurring 404 report (for example, a + saved report filtered on the not-found page title) and use it to add missing + entries to the `redirects` plugin map in `mkdocs.yml`. + +### Maintenance planning + +- Document infrastructure ownership. Add a "Site infrastructure" section to the + README of both `kubevirt/user-guide` and `kubevirt/kubevirt.github.io` (or a + page in `kubevirt/community`) that lists who administers the Netlify site, + GitHub Pages and custom-domain settings, DNS for kubevirt.io, and the Prow job + definitions in `kubevirt/project-infra`, and how a maintainer requests access. +- Give documentation a formal home. Populate the `sig/documentation` entry in + the community `sig-list.md` with chairs, a meeting cadence or async channel, + and a charter that includes both the user guide and the website, so newcomers + know where to volunteer and maintainers have a succession path. +- Publish a maintainer ladder. In the website and user-guide READMEs, describe + how a contributor becomes a reviewer and then an approver (for example, a + number of merged docs PRs and a nomination), mirroring the process in + `kubevirt/community` for code SIGs. +- Reduce bus-factor risk by recruiting at least one additional regular website + reviewer for each repository, using the existing `kind/website` and + `kind/documentation` labels and a `good-first-issue` pass to seed starter + tasks. +- Plan to converge the two toolchains. Evaluate moving the main site to MkDocs + Material or another Hugo/Docusaurus-style generator with a supported theme so + a single skill set covers both sites, and track the decision in an issue even + if the migration is deferred. +- Clean up `netlify.toml` in the user-guide repository: remove the obsolete + `sed` line that targets `site_url: https://kubevirt.io/docs`, and pin the + MkDocs package versions (or use a `requirements.txt`) so preview builds are + reproducible and match the Prow image. +- Add a `Strict-Transport-Security` header. GitHub Pages does not let you set + response headers directly, so either enable HSTS through the DNS/CDN provider + in front of kubevirt.io or, if none exists, record the limitation in the + infrastructure section so it is a known gap. +- Periodically review `OWNERS_ALIASES` in the user-guide repository and add + dated emeritus entries as the website repository already does, so the approver + list reflects who is actually active. + +## Related information + +### References and notes + +### Rating values The numeric rating values used in this document are as follows @@ -2348,11 +2697,3 @@ The numeric rating values used in this document are as follows 3. Meets standards 4. Meets or exceeds standards 5. Exemplary - - From 59fee64199c6d591de506fe76130c81b6ae52486 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Fri, 25 Sep 2026 21:01:41 -0700 Subject: [PATCH 45/49] format fixes Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/analysis.md | 22 ++++++++++------------ 1 file changed, 10 insertions(+), 12 deletions(-) diff --git a/analyses/2026/kubevirt/analysis.md b/analyses/2026/kubevirt/analysis.md index bad14756..9caf0147 100644 --- a/analyses/2026/kubevirt/analysis.md +++ b/analyses/2026/kubevirt/analysis.md @@ -1720,8 +1720,7 @@ problems, keeping source files in two places: - makes it more complicated to generate the documentation from source files Ideally, all website files should be in the website repo itself. Alternatively, -files should be brought into the website repo via [git -submodules][git-submodules]. +files should be brought into the website repo through git submodules. If a project chooses to keep source files in multiple repos, they need a clearly documented strategy for managing mirrored files and new contributions. We @@ -1811,9 +1810,8 @@ Rating: 2 - Needs improvement ### Website requirements Listed here are the minimal website requirements for projects based on their -[maturity level][maturity-level], either incubating or graduated. These are the -only two levels for which a tech docs analysis can be requested. We evaluate on -the following: +maturity level, either incubating or graduated. These are the only two levels +for which a tech docs analysis can be requested. We evaluate on the following: - Are most of the applicable CNCF Website Guidelines(https://deploy-preview-358--cncf-techdocs.netlify.app/docs/website-guidelines-checklist/) @@ -1821,13 +1819,13 @@ the following: -| Criterion | Incubating Requirement | Graduated Requirement | -| ----------------------------- | ------------------------------------------------------- | ----------------------------------------- | -| [Website guidelines] | All guidelines satisfied | All guidelines satisfied | -| **Docs analysis** (this) | Requested through CNCF [service desk][cncf-servicedesk] | All follow-up actions addressed | -| **Project doc**: stakeholders | Roles identified and doc needs documented | All stakeholder need identified | -| **Project doc**: hosting | Hosted directly | Hosted directly | -| **Project doc**: user docs | Comprehensive, addressing most stakeholder needs | Fully addresses needs of key stakeholders | +| Criterion | Incubating Requirement | Graduated Requirement | +| ----------------------------- | ------------------------------------------------ | ----------------------------------------- | +| [Website guidelines] | All guidelines satisfied | All guidelines satisfied | +| **Docs analysis** (this) | Requested through CNCF service desk | All follow-up actions addressed | +| **Project doc**: stakeholders | Roles identified and doc needs documented | All stakeholder need identified | +| **Project doc**: hosting | Hosted directly | Hosted directly | +| **Project doc**: user docs | Comprehensive, addressing most stakeholder needs | Fully addresses needs of key stakeholders | From a09e2d16bb7b084a95ce1b850fc3d5e257833157 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Fri, 25 Sep 2026 21:09:33 -0700 Subject: [PATCH 46/49] heading tweaks Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/analysis.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/analyses/2026/kubevirt/analysis.md b/analyses/2026/kubevirt/analysis.md index 9caf0147..f3dcba63 100644 --- a/analyses/2026/kubevirt/analysis.md +++ b/analyses/2026/kubevirt/analysis.md @@ -801,7 +801,7 @@ Weaknesses: Rating: 4 - Meets or exceeds standards -## Project documentation - Recommendations +## Recommendations ### Information architecture @@ -1520,7 +1520,7 @@ Weaknesses: Rating: 4 - Meets or exceeds standards -## Contributor documentation - Recommendations +## Recommendations ### Communication methods documented @@ -1634,7 +1634,7 @@ Rating: 4 - Meets or exceeds standards meeting cadence and Slack channel, so the generated SIG list can serve as the single place to find how to participate in each group. -## Website and infrastructure +## Website & infrastructure KubeVirt is an **incubating** project of CNCF. This means that the project should be developing professional-quality documentation alongside the project @@ -2449,7 +2449,7 @@ Weaknesses: Rating: 3 - Meets standards -## Website & Infrastructure - Recommendations +## Recommendations ### Single-source requirement From d8cd8fe7709d3b5a4d7a14aa98f72714b7f75866 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Fri, 25 Sep 2026 22:35:11 -0700 Subject: [PATCH 47/49] removed overall comments for areas Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/analysis.md | 471 +++++++---------------------- 1 file changed, 101 insertions(+), 370 deletions(-) diff --git a/analyses/2026/kubevirt/analysis.md b/analyses/2026/kubevirt/analysis.md index f3dcba63..710db53c 100644 --- a/analyses/2026/kubevirt/analysis.md +++ b/analyses/2026/kubevirt/analysis.md @@ -313,40 +313,6 @@ documentation. We evaluate on the following: pages exist outside the navigation. Release Notes, a 3,000-line page, sits in the main navigation between Storage and Contributing. -#### Comment - -The KubeVirt user guide has a sound top-level information architecture. Content -is grouped by audience and layer (Cluster Administration, User Workloads, -Compute, Network, Storage, Virtualization Debugging), ordering is controlled -deliberately through `.nav.yml` files, and the redirects map shows the project -maintained old URLs when it reorganized. Most feature pages follow a consistent -pattern of a short concept, a feature-state banner where relevant, and runnable -manifests or `virtctl` commands. Deprecated mechanisms are labeled and point to -their replacements. Compared with the Prometheus documentation, which the CNCF -criteria cite as a good example, the KubeVirt guide has comparable feature -coverage but lacks Prometheus's clear "Getting started" spine and its -consolidated reference material. - -The main weakness is that the guide is a well-organized encyclopedia rather than -a guided path. A new user must assemble the happy path from Installation, the -`virtctl` install page, Creating VirtualMachines, Lifecycle, and Accessing -Virtual Machines, and the guide points to external Killercoda and kubevirt.io -labs to fill that gap. The oldest foundational pages (Basic Use, Lifecycle) -still present VirtualMachineInstance as the primary object, which is out of step -with the VirtualMachine-centric approach used everywhere else. Reference -material for `virtctl` and for feature gates is not consolidated, and there is -no user-facing troubleshooting or FAQ page, so the escalation path jumps -straight from feature pages to Slack and GitHub issues. - -Currency is uneven. New v1.9 features are documented where a page exists -(VirtualMachine Templates, Plugins), but the Plugins page is not in the -navigation, several v1.9 APIs and feature gates appear only in release notes, -and Installation still carries legacy OKD Service Catalog and k3OS content. -Section-internal organization is the other systemic issue: Compute and Storage -are long flat lists named after APIs rather than user goals, and the User -Workloads "Workloads" sub-group mixes current, legacy, and deprecated mechanisms -without signaling which one a reader wants. - Strengths: - Audience- and layer-based top-level sections with explicit, intentional page @@ -438,38 +404,31 @@ specifically for them. We evaluate on the following: `virtctl create vm` invocations, `kubectl` lifecycle commands, and YAML manifests. These are formatted for direct copy-paste. -#### Comment - -The KubeVirt user guide gives new users a solid technical starting point, but -its on-ramp is fragmented across several differently named locations. New-user -material is split between a top-level "Quickstarts" entry, an "Installation" -page buried as the first item under "Cluster Administration," and "Try it out" -and "KubeVirt Labs" sections on the homepage. Because none of these is labeled -"Getting Started" or "First Steps," newcomers must piece the path together -themselves. Consolidating these entry points under a single, clearly named -"Getting Started" section—ideally as its own top-level navigation item—would -match the convention new users expect and provide one obvious front door. The -Falco getting-started guide (https://falco.org/docs/getting-started/) is a good -model for this unified structure. - -The installation documentation itself is strong: it lists prerequisites, -provides ordered and copy-pasteable operator and CR commands, shows how to -verify a healthy deployment, and covers multiple platforms (Kubernetes, OKD, -k3OS) and architectures (x86_64 and Arm64). The main weakness is that the guide -leans heavily on external links—Killercoda, the minikube/kind/cloud quickstarts, -and the kubevirt.io labs—rather than an in-guide walkthrough that carries a -reader from a fresh cluster to a running virtual machine. Bringing at least one -complete, end-to-end "deploy KubeVirt and launch your first VM" tutorial into -the guide would reduce reliance on off-site content and give users a -self-contained first success. - -The most actionable single improvement is to close the gap between installation -and first use. The installation page currently ends with optional topics -(network plugins, node placement) and offers no explicit "Next steps" pointer -toward the first-VM tasks in "User Workloads" (such as `basic_use.md` and -`creating_vms.md`). Adding a clear "Next steps" call-to-action at the end of -installation, linking directly to creating and accessing a first virtual -machine, would give new users an unbroken path from setup to a working workload. +Strengths: + +- Installation gives a correct, short operator-based procedure with expected + output and a software-emulation fallback. +- The Welcome page links to live Killercoda scenarios, quickstarts for minikube, + kind, and cloud providers, and four hands-on labs. +- Arm64 platform status is documented in a dedicated sub-section. +- Recently revised pages provide clean, pasteable manifests and `virtctl` + pipelines. +- Requirements are stated up front, including `--allow-privileged=true` and + hardware virtualization validation. + +Weaknesses: + +- No page labeled "Getting started" and no single in-guide path from install to + first running VM. +- Installation mixes the core procedure with AppArmor, kernel compatibility, + OKD, k3OS, developer builds, and node placement, and ends without a next step. +- `virtctl` install covers only Linux amd64 via `wget`; macOS, Windows, and + arm64 binaries and `PATH` setup are not mentioned. +- Basic Use and Lifecycle reference `vmi.yaml` without providing it and do not + link onward. +- Older pages use `$`-prefixed indented code blocks interleaved with output, and + the copy button is not enabled. +- The Quickstarts page has no introduction, prerequisites, or outcome statement. Rating: 3 - Meets standards @@ -530,33 +489,6 @@ evaluate on the following: (`update_changelog.sh`) that regenerates the page from kubevirt/kubevirt tags, but that process is also undocumented outside the script itself. -#### Comment - -The KubeVirt user guide is maintainable as a single-version, single-language -site. Its toolchain is simple and well suited to a documentation-only -repository: plain Markdown under `docs/`, mkdocs-material with built-in search, -explicit `.nav.yml` ordering, centralized redirects, and a Makefile that runs -spelling and link checks in a container. The redirects map shows the maintainers -preserved URLs through a major reorganization, which is the kind of discipline -that keeps a site maintainable over time. - -The gap is that the project has outgrown the single-version model without -documenting the alternative. KubeVirt ships minor releases with feature-gate -graduations and API changes, and the repository already has per-release -branches, yet the published site tracks only `main`, offers no version selector, -and no document explains what the release branches are for or how contributors -should use them. Users of an older KubeVirt cannot tell which features on a page -apply to them except where an individual author added an "as of vX.Y" banner. -Compared with the Kubernetes documentation that the CNCF criteria cite as a good -example, which publishes each supported minor version with a selector and -documents its branching and localization processes, KubeVirt's approach is -informal and depends on maintainer memory. - -Localization is absent but not blocked. There is no demand documented, no -framework configured, and no language directory, so this is a low priority; the -main cost of the current layout is that adding a first translation later would -require moving every file. - Strengths: - Simple, low-dependency MkDocs toolchain with search enabled on every page. @@ -661,31 +593,6 @@ the following: process. Ownership is inferable from Git history and OWNERS files but is not documented. -#### Comment - -KubeVirt's strongest asset in this area is that documentation is wired into the -engineering process rather than left to chance. The kubevirt/kubevirt pull -request checklist asks every author whether a user-guide update is needed, and -the VEP process requires SIGs to confirm the docs PR is merged before release. -Recent history shows this works: feature developers routinely land the user -guide page for their VEP in the same release cycle, and the release notes are -regenerated on each release. Reviews and approvals are automated through Prow -OWNERS files with a curated approver list. Compared with the Thanos "How to -contribute to docs" page and the NATS MAINTAINERS file that the CNCF criteria -cite as good examples, KubeVirt has stronger release-process coupling but weaker -documentation of the process itself. - -The weakness is that the process is implicit. A new contributor reading README -and CONTRIBUTING learns how to build the site and sign a commit but not who will -review, how approval works, how long to expect, what a good page looks like, or -when a change needs a redirect or a cherry-pick to a release branch. Ownership -is real but undocumented: no MAINTAINERS file, no named docs lead or SIG, and no -statement of who runs the Netlify deployment or the release-notes script. The -per-SIG aliases in `OWNERS_ALIASES` are defined but never used to route reviews, -so a storage or network expert is not automatically assigned to pages in their -area. Twelve open pull requests, the oldest six months old, suggest review -capacity depends on a small group of core maintainers who also carry the code. - Strengths: - The kubevirt/kubevirt PR template and the VEP release checklist both require a @@ -760,27 +667,6 @@ evaluate on the following: prose. The repository's spelling check does not include an inclusive-language or minimizing-language rule, so nothing prevents new occurrences. -#### Comment - -The KubeVirt user guide is in good shape on inclusive naming. KubeVirt's own API -objects, components, CLI, and feature gates avoid all Inclusive Naming -Initiative tier-1 terms, the project's default branch is `main`, and the guide -already uses "allowlist" where the older term might have appeared. The remaining -occurrences of "master" are in URLs and third-party content, and the only one -under the project's control, the 14 links to the API reference at the legacy -`/master/` path, is a mechanical fix now that the API reference publishes under -`/main/` and per-version paths. Field names such as `Abort Requested` are part -of the KubeVirt API and are a question for the API maintainers rather than the -documentation. - -The one systemic concern is minimizing language. Words such as "simply", -"simple", "easy", "easily", and "just" appear over a hundred times across 40 -percent of pages. This language tells a reader who is struggling with a step -that the step should have been easy, and in almost every case it can be deleted -with no loss of meaning. Because the repository's spelling check has no rule for -these words, the pattern will continue in new pages unless a style rule or lint -check is added. - Strengths: - No Inclusive Naming Initiative tier-1 terms in KubeVirt-controlled names, @@ -1151,29 +1037,6 @@ to reach you. We evaluate on the following: does not say so. The Contributing page does not mention the mailing list at all. -#### Comment - -KubeVirt's communication channels are well established and thoroughly documented -at the community level. Two Slack channels, a Google Group, a GitHub -organization, a public community calendar, a weekly Zoom meeting with recorded -sessions on YouTube, and posted minutes are all in place, and the -kubevirt/community repository describes the meeting mechanics in more detail -than most CNCF projects. The kubevirt.io Community page gathers the channels, -the calendar, and the Slack invitation link on one page, and the home page -footer repeats the primary links. - -The gap is in how the user guide surfaces these channels. A user who hits a -problem while following a page has no path to help except to return to the -Welcome page, where "Getting help" offers three bare URLs with no guidance on -which channel suits which question. The guide does not mention the -`#kubevirt-dev` channel, the community meeting, the calendar, or that meeting -minutes are mailed to kubevirt-dev, and the mkdocs-material header and footer -carry no repository or social icons because `repo_url` and `extra.social` are -not set. Meeting details live only in the community repository; the websites -present a calendar embed and a one-line invitation without stating the day, -time, or how to join. SIG charters do not record meeting cadence, so SIG-level -participation depends on scanning the shared calendar. - Strengths: - Two purpose-specific Slack channels, a mailing list, a public calendar, and a @@ -1271,29 +1134,6 @@ We evaluate on the following: triage and, without a human in the loop, it erases the entry points the Contributing page advertises. -#### Comment - -The KubeVirt user guide has the infrastructure for a beginner-friendly backlog -but not the backlog itself. The repository inherits the KubeVirt organization's -Prow labels, issue templates, and lifecycle automation; the labels a newcomer -needs (`good-first-issue`, `help wanted`, `sig/documentation`, -`triage/accepted`) all exist; and the Contributing page points newcomers at -`good-first-issue` in this and two sibling repositories. When maintainers have -written beginner issues, they have written them well: the September 2025 batch -of eight feature-lifecycle documentation issues each carried background, -affected files, and acceptance criteria. - -The problem is follow-through. All ten `good-first-issue` items closed in the -past year, including that entire batch, were auto-closed by the stale bot -without a fix, and today the label has zero open items here and zero -documentation-related items in kubevirt/kubevirt. A newcomer who follows the -Contributing page's instructions finds nothing to do. Triage labels are applied -to only half of the small open backlog, and no issue is assigned or marked -`triage/accepted`, so the lifecycle automation runs without a human deciding -which issues should survive it. The net effect is a clean but empty backlog, -which is the wrong outcome for a project that explicitly invites first-time -contributors to start with documentation. - Strengths: - Full Prow label taxonomy, org-level issue templates, and automated lifecycle @@ -1388,29 +1228,6 @@ in easily? We evaluate on the following: URLs on the Welcome page and are not repeated on the Contributing page or in CONTRIBUTING.md. -#### Comment - -KubeVirt has a genuine new-contributor document and a mature community -repository behind it. The user guide's Contributing page is written for someone -making their first open source contribution: it sets expectations, points to -low-barrier repositories, offers non-code ways to start, and links the -governance, membership, code of conduct, and AI contribution policies. The -kubevirt/community repository supplies the depth, including a SIG list, a -membership checklist, a help-wanted label guide, and a detailed community -meeting document, and both sides point at each other as the canonical entry. - -The weakness is the hand-off from motivation to action. The Contributing page -ends where a newcomer needs the most guidance: how to pick and claim an issue, -how to fork, sign off, and open a pull request, what the Prow labels mean, and -who will review. Those mechanics exist but are scattered across the repository -README, kubevirt/kubevirt CONTRIBUTING.md, and kubevirt/kubevirt -`docs/getting-started.md`, none of which is presented as the next step. The page -also directs newcomers to `good-first-issue` lists that are currently empty, and -does not name a channel, person, or meeting where a stuck contributor can ask -for help. The community repository's most useful contributor resources (SIG -list, help-wanted guide, meeting document, MAINTAINERS) are not linked from the -guide at all. - Strengths: - A dedicated, welcoming Contributing page that is the canonical entry point @@ -1476,27 +1293,6 @@ following: maintainers are. A user or prospective adopter evaluating the project's governance must know to open the community repository. -#### Comment - -KubeVirt's governance documentation is clear, specific, and maintained. -`GOVERNANCE.md` answers the questions an evaluator asks first: who the -maintainers are, how they are chosen and removed, how votes work and what -thresholds apply, and how SIGs and working groups relate to the maintainers. The -companion documents give the contributor ladder concrete requirements at each -level and an explicit inactivity policy, the maintainers list records employers -and areas of responsibility with an emeritus table, and SIG charters are -generated from a single source of truth. This is the level of governance -documentation expected of a CNCF incubating project and is a strength the -project can point to. - -The only shortfall is presentation. Governance is documented in the community -repository but not summarized or prominently linked from kubevirt.io or the user -guide; the Contributing page links `GOVERNANCE.md` with a one-line label among -other resources, and the Community page does not mention governance, -maintainers, or SIGs at all. Prospective adopters and contributors evaluating -the project from the website have to know the community repository exists to -find this material. - Strengths: - `GOVERNANCE.md` covers maintainer selection, removal, voting thresholds, @@ -1763,27 +1559,6 @@ evaluate on the following: user guide, and the code repositories' `docs/` directories, so contributors have to infer where a new page belongs. -#### Comment - -KubeVirt does not meet the single-source requirement as the CNCF criteria define -it. The pages a visitor sees under `kubevirt.io` are built from three separate -repositories with three separate publish pipelines, and user-facing -documentation is additionally scattered across the `docs/` directories of the -core and CDI code repositories. The split between the website and the user guide -is defensible, since the two use different generators and serve different -audiences, but that rationale is undocumented, and the overlap between -`kubevirt/kubevirt/docs` and the user guide is not a design decision so much as -an accumulation. Contributors have no written guidance on which repository a new -page belongs in, and readers can land on developer-oriented Markdown in the core -repository that duplicates or contradicts the user guide. - -The user guide itself is a well-behaved single source: one `docs/` tree, -explicit navigation files, and a redirect map for moved pages. That makes it the -natural home for consolidating user-facing content that currently lives -elsewhere, and the existing cross-links from the guide to -`kubevirt/kubevirt/docs` and to the CDI repository identify exactly which -content is a candidate to move. - Strengths: - The user guide keeps all of its content in one `docs/` tree with declarative @@ -1813,15 +1588,11 @@ Listed here are the minimal website requirements for projects based on their maturity level, either incubating or graduated. These are the only two levels for which a tech docs analysis can be requested. We evaluate on the following: -- Are most of the applicable CNCF Website - Guidelines(https://deploy-preview-358--cncf-techdocs.netlify.app/docs/website-guidelines-checklist/) - satisfied? - | Criterion | Incubating Requirement | Graduated Requirement | | ----------------------------- | ------------------------------------------------ | ----------------------------------------- | -| [Website guidelines] | All guidelines satisfied | All guidelines satisfied | +| **Website guidelines** | All guidelines satisfied | All guidelines satisfied | | **Docs analysis** (this) | Requested through CNCF service desk | All follow-up actions addressed | | **Project doc**: stakeholders | Roles identified and doc needs documented | All stakeholder need identified | | **Project doc**: hosting | Hosted directly | Hosted directly | @@ -1829,7 +1600,81 @@ for which a tech docs analysis can be requested. We evaluate on the following: -#### Comment +- Are most of the applicable CNCF Website Guidelines satisfied? See + https://github.com/cncf/techdocs/blob/main/docs/website-guidelines-checklist.md + + Yes for the main website, and only partly for the user guide. KubeVirt is a + CNCF incubating project, so the "developing" standard applies. Taking the + checklist items in order: + 1. Open source repository. Both sites are hosted in the `kubevirt` GitHub + organization alongside the main project: the website in + `kubevirt/kubevirt.github.io` and the user guide in `kubevirt/user-guide`. + Both repositories run the DCO check on every pull request (it appears as a + required `dco` status alongside `tide` and the Netlify preview), and the + user guide README explains how to sign commits. + + 2. Origin company. The homepage does not refer to Red Hat as the originator; + Red Hat appears only as one logo among the alphabetized End Users and + Vendors lists. + + 3. Enterprise support leads. There are no lead-capture links or forms on + either site; the only forms are the search boxes and the user guide's + color-scheme toggle. The homepage has a Vendors section of eighteen logos, + sorted alphabetically, populated from `ADOPTERS.md` through a documented + process, which serves as the vetting step. + + 4. Vendor links. Several vendor logos link to pages that describe the vendor's + KubeVirt offering (Kubermatic, Platform9, Spectro Cloud, KubeSphere), but + others link to the vendor's generic corporate homepage (Microsoft, Oracle, + SUSE, Red Hat, NCR Voyix, TrueFullstaq), which does not mention KubeVirt + support. + + 5. Copyright notice. The main website footer reads "Copyright KubeVirt a + Series of LF Projects, LLC", which is the wording the checklist specifies + for projects converted to the Series LLC model, though it omits the © + symbol. The user guide footer contains only "Made with Material for MkDocs" + and no copyright notice; `mkdocs.yml` sets no `copyright` value. + + 6. CNCF branding. The main website footer states "We are a Cloud Native + Computing Foundation incubating project", which matches the project's + current maturity level, and displays the CNCF color logo linked to + `cncf.io`. The user guide has no CNCF statement or logo anywhere on the + page. + + 7. Footer trademark and policy links. The main website footer links to + `https://lfprojects.org/policies/` "for website terms of use, trademark + policy and other project policies", which satisfies the + trademark-guidelines requirement through a terms page. The user guide + footer has no trademark or policy link. + + Community and license files. Both repositories have a `LICENSE` file. The user + guide has a `CONTRIBUTING.md`; the website repository has none, though its + README covers contributing in detail. Neither repository has a + `CODE_OF_CONDUCT.md` in its root; GitHub applies the organization-wide default + from the `kubevirt/.github` repository, so the code of conduct is visible on + the repository page but is not a file in the repository as the checklist asks. + +Strengths: + +- Both sites hosted in the `kubevirt` organization with DCO enforced on every + pull request. +- Main website footer includes the correct maturity statement, Series LLC + copyright, CNCF logo, and LF Projects policies link. +- No origin-company references or enterprise lead capture; vendor list is + alphabetized and sourced from `ADOPTERS.md`. +- `LICENSE` present in both repositories and `CONTRIBUTING.md` in the user + guide. + +Weaknesses: + +- User guide footer has no copyright, CNCF branding, or trademark link. +- Several vendor logos link to corporate homepages rather than KubeVirt support + pages. +- No root `CODE_OF_CONDUCT.md` in either repository; no `CONTRIBUTING.md` in the + website repository. +- Main website copyright line omits the © symbol. + +Rating: 3 - Meets standards ### Usability, accessibility and devices @@ -1930,28 +1775,6 @@ following: Arm64 feature-gate table with a status column per gate) are readable but tedious without a caption or summary row. -#### Comment - -The KubeVirt user guide inherits a solid usability and accessibility baseline -from mkdocs-material. The site is responsive, the navigation, search, and table -of contents all work from a mobile drawer, keyboard users get a skip link, -search shortcuts, and standard focusable controls, and pages declare a language -and use a proper heading hierarchy. The project has customized the theme lightly -and, apart from color, has not undermined these defaults. Dark mode is available -and previous and next links help linear reading. - -The one clear defect is color contrast. The custom teal primary color produces -white-on-teal header and tab text at roughly 2.6:1 and body links at roughly -4:1, both below WCAG AA for normal text. This affects every page and is a -one-line CSS change to fix. The remaining issues are in content rather than the -platform: the Architecture page's central diagram is ASCII art with no textual -equivalent, older pages use `$`-prefixed indented code blocks that read poorly -on screen readers and scroll horizontally on phones, several pages exceed 500 -lines without internal grouping, and wide status tables and long command lines -depend on horizontal scrolling on small screens. The `width: max-content` table -override in `extra.css` should be verified on a real device to confirm tables -still scroll rather than overflow the viewport. - Strengths: - Responsive mkdocs-material theme with viewport meta, mobile drawer navigation, @@ -2036,32 +1859,6 @@ this is branding and marketing. We evaluate on the following: which is useful for the many API-field tables but can crowd narrow view ports. Typography differs from the main site, which uses Open Sans at a 16px base. -#### Comment - -The KubeVirt user guide has a clear, recognizable identity. The teal heptagon -mark, the teal Material palette pinned to the project's own hex values, and the -coordinated sidebar label color together make every page unmistakably KubeVirt. -Because the branding is configured once in `mkdocs.yml` and -`docs/stylesheets/extra.css` rather than in individual pages, it stays -consistent across the roughly one hundred pages of the guide and across the -light and dark schemes without any effort from content authors. This is the -right model for a documentation site and is worth pointing to as an example. - -The main gap is that KubeVirt's brand is expressed in two different ways on its -two web properties. The main `kubevirt.io` site carries a documented SCSS color -scale, the horizontal wordmark, and Open Sans; the user guide carries three -copied hex values, the square icon, and Roboto. The colors are from the same -family, so nothing looks wrong, but there is no single source of truth for the -brand, and the guide's header and footer give the reader no visual or -navigational cue that it belongs to the larger site. Unused assets from a -previous site generator also remain in the repository. - -Typography is clean and well-suited to reading long technical pages, with a -sensible pairing of proportional and monospaced faces and good default spacing. -The only design choices worth a second look are the small custom CSS rules that -darken all links and let tables grow to their natural width, since both trade a -little readability for a stylistic or layout effect. - Strengths: - Distinctive logo mark and brand colors applied at the theme level, so branding @@ -2156,32 +1953,6 @@ organizations using it. We evaluate on the following: because the use-case text is not carried over. The user guide does not display or link to the logo wall. -#### Comment - -KubeVirt has more adoption evidence than its websites show. The project -maintains a curated adopters list with first-person use-case statements from -well-known production users, publishes talks, demos, interviews, and five years -of Summit recordings, keeps a blog that still produces substantive release and -feature posts, and is featured in two CNCF-published end-user case studies. The -logo wall and video section on `kubevirt.io` are well organized and clearly -signal an active, widely adopted project. - -The weakness is that the most persuasive material is disconnected from where -prospective users look. The CNCF case studies are not linked from either -property, the adopter use-case statements live only in a GitHub Markdown table -while the website shows bare logos, and no blog category or page collects user -stories. The result is that the project appears to have a logo wall and a blog -but no case studies or testimonials, when in fact it has the raw material for -both. Blog cadence has also fallen from about two posts a month to a handful a -year, and the flat `news` category makes the archive hard to browse by theme. - -From the user guide's side, the gap is discoverability. The guide is where -evaluators end up when they want to know whether KubeVirt fits their -environment, yet its landing page and navigation contain no link to adopters, -case studies, talks, or the blog. Only `contributing.md` mentions the website's -community content, and it frames it as a place to contribute rather than a place -to learn. - Strengths: - Curated adopters list with a "Since" year and first-person use-case text for @@ -2289,25 +2060,6 @@ evaluate on the following: from redhat.com, access to the data appears to be held by Red Hat staff rather than by the project, and that dependency is not recorded anywhere. -#### Comment - -The KubeVirt web presence splits across two sites with very different analytics -postures. The main site collects data through a Red Hat–administered Adobe -Analytics tag, while the user guide, which is the documentation users spend most -of their time in, collects nothing. As a result the project has no visibility -into which documentation pages are read, which searches fail, or which inbound -links break. The main site's tag is also loaded on every deploy, so preview -traffic is mixed into production numbers. - -Search-engine fundamentals are in reasonable shape. Both sites produce sitemaps, -the user guide emits correct canonical URLs even on its Netlify alias, and -Google Search Console is verified for the domain. Local search works well in the -user guide thanks to the MkDocs Material plugin, though the main site's lunr -search indexes only blog posts and neither site can search the other. The -biggest governance gap is that nobody is named as custodian of the analytics, -Netlify, or Search Console accounts, and the project's dependence on a -vendor-hosted analytics account is undocumented. - Strengths: - Full-text local search in the user guide, with a tuned separator for technical @@ -2401,27 +2153,6 @@ project maintainers aren’t web developers. We evaluate on the following: include a `Strict-Transport-Security` header, so browsers rely on the redirect rather than HSTS to enforce HTTPS on repeat visits. -#### Comment - -The KubeVirt documentation infrastructure is low-maintenance by design and -largely automated. The user guide runs on MkDocs Material, one of the most -widely adopted documentation stacks in the cloud-native ecosystem, and both -sites are published to GitHub Pages by a Prow job within a minute or two of -merge. HTTPS is enforced everywhere, Netlify provides pull-request previews, and -Dependabot keeps the Jekyll site's dependencies current. For a project of -KubeVirt's size, the tooling choices are sensible and the deploy pipeline is -fast and hands-off. - -The risk lies in people rather than tooling. The two sites use different -generators, so a maintainer must know both Jekyll and MkDocs, and the main -site's hand-built Bootstrap theme has no upstream to inherit fixes from. Commit -history shows the documentation effort leaning on a single active maintainer, -the community's `sig/documentation` label has no chairs or members, and neither -repository describes how someone grows into a website maintainer role or who -holds the keys to Netlify, DNS, GitHub Pages settings, and the Prow job -definitions. If that maintainer stepped away, the project would have working -automation but no documented map of who can change it. - Strengths: - MkDocs Material for the user guide is well supported and common among CNCF From fbd6f33f9d8e80c31762e2296bfec02bbfe6e612 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Fri, 25 Sep 2026 22:52:53 -0700 Subject: [PATCH 48/49] spellling additions Signed-off-by: Bruce Hamilton --- .cspell.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.cspell.yml b/.cspell.yml index f4b2b8d5..acc58962 100644 --- a/.cspell.yml +++ b/.cspell.yml @@ -92,3 +92,7 @@ words: - lunr - redhat - wordmark + - Fullstaq + - Kubermatic + - Spectro + - Voyix From c98cca8f317a15e07921939fcbe389f5bfb7fca8 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Fri, 25 Sep 2026 23:07:20 -0700 Subject: [PATCH 49/49] headings fixes Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/analysis.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/analyses/2026/kubevirt/analysis.md b/analyses/2026/kubevirt/analysis.md index 710db53c..f1dd4a88 100644 --- a/analyses/2026/kubevirt/analysis.md +++ b/analyses/2026/kubevirt/analysis.md @@ -687,7 +687,7 @@ Weaknesses: Rating: 4 - Meets or exceeds standards -## Recommendations +## Project documentation recommendations ### Information architecture @@ -1316,7 +1316,7 @@ Weaknesses: Rating: 4 - Meets or exceeds standards -## Recommendations +## Contributor documentation recommendations ### Communication methods documented @@ -2180,7 +2180,7 @@ Weaknesses: Rating: 3 - Meets standards -## Recommendations +## Website & infrastructure recommendations ### Single-source requirement