From c58b2914aee370b392fb93f404f784c80ee4b442 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Sun, 14 Jun 2026 18:07:27 -0700 Subject: [PATCH 01/29] 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/29] 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/29] 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/29] 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/29] 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/29] 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/29] 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/29] 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/29] 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/29] 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/29] 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/29] 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/29] 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/29] 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/29] 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/29] 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/29] 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/29] 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/29] 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/29] 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/29] 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/29] 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/29] 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/29] 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/29] 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/29] 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/29] 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/29] 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/29] 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