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