From c58b2914aee370b392fb93f404f784c80ee4b442 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Sun, 14 Jun 2026 18:07:27 -0700 Subject: [PATCH 1/9] 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 2/9] 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 3/9] 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 4/9] 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 5/9] 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 6/9] 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 7/9] 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 8/9] 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 9/9] 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