KubeVirt docs analysis

.cspell.yml

@@ -45,3 +45,4 @@ words:
   - Uchechukwu
   - webdev
   - Welsch
+  - KubeVirt

analyses/2026/kubevirt/analysis.md

@@ -0,0 +1,337 @@
+---
+title: KubeVirtDocumentation Analysis
+created: 2026-05-24
+modified: 2026-06-17
+author: Bruce Hamilton
+---
+
+<!-- markdownlint-disable no-duplicate-heading -->
+
+## 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 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
+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
+
+<!-- - Website: https://_PROJECT_.io
+- Documentation: https://_PROJECT_.io/user-guide
+- Website repo: https://github.com/_PROJECT_/user-guide -->
+
+#### 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.
+
+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. 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
+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