From 07fd26a3dc33f4deaeb8e5dc6d325ee5a891e4bf Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Mon, 1 Jun 2026 19:17:27 -0700 Subject: [PATCH 01/13] created files Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/analysis.md | 523 +++++++++++++++++++++++ analyses/2026/kubevirt/implementation.md | 52 +++ analyses/2026/kubevirt/issues-list.md | 55 +++ analyses/2026/kubevirt/issues.md | 64 +++ 4 files changed, 694 insertions(+) create mode 100644 analyses/2026/kubevirt/analysis.md create mode 100644 analyses/2026/kubevirt/implementation.md create mode 100644 analyses/2026/kubevirt/issues-list.md create mode 100644 analyses/2026/kubevirt/issues.md diff --git a/analyses/2026/kubevirt/analysis.md b/analyses/2026/kubevirt/analysis.md new file mode 100644 index 0000000..514afd0 --- /dev/null +++ b/analyses/2026/kubevirt/analysis.md @@ -0,0 +1,523 @@ +--- +title: KubeVirt Documentation Analysis +tags: KubeVirt +created: 2026-05-24 +modified: 2026-05-31 +author: @iRaindrop +--- + + + +## Introduction + +This document is an analyzes the effectiveness and completeness of the +[KubeVirt](https://kubevirt.io) 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 +documentation. It aims to provide project leaders with an informed understanding +of potential problems in current project documentation. A second +[implementation](implementation.md) document outlines an actionable plan for +improvement. A third document is an [issues list](issues-list.md) 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 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 + +### 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 +KubeVirt GitHub repository. + +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 KubeVirt GitHub repo. + +#### In scope + +- Website: https://kubevirt.io +- Documentation: https://kubevirt.io/user-guide +- Website repo: https://github.com/kubevirt/user-guide + + +#### Out of scope + +- 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 KubeVirt + software, aimed at people who intend to use the project software. +- **Contributor documentation:** concerns documentation for new and existing + 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 KubeVirt users achieve their goals. +- **Recommendations**: suggested changes that would improve the effectiveness of + the documentation. + +The accompanying [implementation](./implementation.md) 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 `https://github.com/kubevirt/kubevirt/issues`. + +### How to use this document + +Readers interested only in actionable improvements should skip this document and +read the [implementation](./implementation.md) plan and [issues list](./issues-list.md). + +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 + +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)] | + +### Comments + +> AUTHOR NOTE: make any overall comments about the Project Documentation here. + +The following sections contain brief assessments of each element of the Project +Documentation rubric. + +> AUTHOR NOTE: For each heading below, discuss how well the in-scope items, and +> especially the technical documentation, meet these criteria. (Criteria are +> copied from criteria.md) + +#### 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 + +> AUTHOR NOTE: Pick the CNCF maturity level of the project: + +KubeVirt is a **graduated** project of CNCF. This means that the project should +have [_very high_][criteria] standards for documentation. + +> AUTHOR NOTE: or + +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)] | +| ----------------------------------------- | -------------- | +| 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 + +> AUTHOR NOTE: make any overall comments about the Contributor Documentation +> here. + +The following sections contain brief assessments of each element of the +Contributor Documentation rubric. + +> AUTHOR NOTE: For each heading below, discuss how well the in-scope items meet +> these criteria. Keep in mind that much of the contributor documentation might +> be contained in the documentation repository. (Criteria are copied from +> criteria.md) + +#### Communication methods documented + +One of the easiest ways to attract new contributors is making sure they know how +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 + +## Website and infrastructure + +> AUTHOR NOTE: Pick the CNCF maturity level of the project: + +KubeVirt is a **graduated** project of CNCF. This means that the project should +have [_very high_][criteria] standards for documentation. + +> AUTHOR NOTE: or + +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 | [rating (1-5)] | +| Meets min website req. (for maturity level) | [rating (1-5)] | +| Usability, accessibility, and design | [rating (1-5)] | +| Branding and design | [rating (1-5)] | +| Case studies/social proof | [rating (1-5)] | +| SEO, Analytics, and site-local search | [rating (1-5)] | +| Maintenance planning | [rating (1-5)] | +| A11y plan & implementation | [rating (1-5)] | +| Mobile-first plan & impl. | [rating (1-5)] | +| HTTPS access & HTTP redirect | [rating (1-5)] | +| Google Analytics 4 for production only | [rating (1-5)] | +| Indexing allowed for production server only | [rating (1-5)] | +| Intra-site / local search | [rating (1-5)] | +| Account custodians are documented | [rating (1-5)] | + +### Comments + +> AUTHOR NOTE: make any overall comments about the Website and documentation +> infrastructure here. + +The following sections contain brief assessments of each element of the Website +and documentation infrastructure rubric. + +> AUTHOR NOTE: for each heading below, discuss how well the in-scope items meet +> these criteria. Keep in mind that much of the website infrastructure criteria +> depend on the tools (static site generator, website framework and hosting, +> analytics tools, etc.) and processes (project CI, release procedures, +> governance, etc.) used to produce the documentation. (Criteria are copied from +> criteria.md) + +#### Single-source requirement + +Source files for _all website pages_ should reside in a single repo. Among other +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. + +#### 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 + +#### 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? +- Are doc pages readable? +- Are all / most website features accessible from mobile -- such as the top-nav, + site search and in-page table of contents? +- Might a [mobile-first] design make sense for your project? + +[mobile-first]: + https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Responsive/Mobile_first + +Plan for suitable [accessibility][] measures for your website. For example: + +- Are color contrasts significant enough for color-impaired readers? +- Are most website features usable using a keyboard only? +- Does text-to-speech offer listeners a good experience? + +It is up to each project to set their own guidelines. + +[accessibility]: https://developer.mozilla.org/en-US/docs/Web/Accessibility + +#### 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? +- Is the brand used across the website consistently? +- Is the website’s typography clean and well-suited for reading? + +#### 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? +- Are there user testimonials available? +- Is there an active project blog? +- Are there community talks for the project and are they present on the website? +- Is there a logo wall of users/participating organizations? + +#### 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? + - Is analytics disabled for all other deploys? + - If your project used Google Analytics, have you migrated to GA4? + - Can Page-not-found (404) reports easily be generated from you site + analytics? Provide a sample of the site's current top-10 404s. +- Is site indexing supported for the production server, while disabled for + website previews and builds for non-default branches? +- Is local intra-site search available from the website? +- Are the current custodian(s) of the following accounts clearly documented: + analytics, Google Search Console, site-search (such as Google CSE or Algolia) + +#### 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?) +- Are you actively cultivating website maintainers from within the community? +- Are site build times reasonable? +- Do site maintainers have adequate permissions? + +#### Other + +- Is your website accessible via HTTPS? +- Does HTTP access, if any, redirect to HTTPS? + +### Recommendations + +> AUTHOR NOTE: Write general recommendations based on the comments from the +> previous section. + +#### Single-source requirement + +#### Minimal website requirements + +#### Usability, accessibility and devices + +#### Branding and design + +#### Case studies/social proof + +#### SEO, Analytics and site-local search + +#### Maintenance planning + +#### Other + +#### 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 + +[criteria]: ../criteria.md +[implementation]: ./implementation.md +[issues list]: ./issues-list.md +[project-website]: ?fixme-target-dne=https://kubevirt.o +[Rating (1-5)]: #rating-values +[rfc-spec]: https://www.rfc-editor.org/rfc/rfc2119 +[website guidelines]: ../../website-guidelines-checklist.md diff --git a/analyses/2026/kubevirt/implementation.md b/analyses/2026/kubevirt/implementation.md new file mode 100644 index 0000000..a87456d --- /dev/null +++ b/analyses/2026/kubevirt/implementation.md @@ -0,0 +1,52 @@ +--- +title: Implementing KubeVirt Doc Improvements +tags: KubeVirt +created: 2026-05-24 +modified: 2026-05-31 +author: @iRaindrop +--- + + + +## Introduction + +This document provides actionable suggestions for improving the _PROJECT_ +technical documentation. + +For an analysis and general discussion of recommendations on _PROJECT_ technical +documentation, see [analysis.md](analysis.md). + +### 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, +recommendations are based on documentation best practices as understood by the +reviewers. The recommended implementations represent the reviewers' experience +with how to apply those best practices. In other words, borrowing terminology +from the lexicon of [RFCs][rfc-keywords], 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. + +The top-level documentation recommendations for this project are: + +> AUTHOR NOTE: Provide a summary or outline of the recommendations. Depending on +> the analysis findings, recommended actions might be organized into two or +> three high-level items that contain multiple actions, or might just be a list +> of independent changes. For examples, see a completed implementation plan such +> as 0008-Backstage or 0010-etcd. + +## High-level action 1 + +### Issue 1 + +### Issue 2 + +## High-level action 2 + +### Issue 1 + +### Issue 2 + +[rfc-keywords]: https://www.rfc-editor.org/rfc/rfc2119 \ No newline at end of file diff --git a/analyses/2026/kubevirt/issues-list.md b/analyses/2026/kubevirt/issues-list.md new file mode 100644 index 0000000..d87cb3c --- /dev/null +++ b/analyses/2026/kubevirt/issues-list.md @@ -0,0 +1,55 @@ +--- +title: KubeVirt Umbrella Issue and Issues List +tags: KubeVirt +created: 2026-05-24 +modified: 2026-05-31 +author: @iRaindrop +--- + +## Overview + +> AUTHOR NOTES: +> +> - Provide an outline or high-level description of the recommended changes. +> Note any general patterns that occur throughout the documentation, such as a +> lack of step-by-step procedures. +> +> -Items might be disjoint and unrelated; that's OK. If there are high-level +> items that must be broken down into smaller issues, use the high-level items +> to organize the issues in this plan. Otherwise, list issues in order from the +> analysis document. This is an improvement plan, not a legal brief. +> +> - The following is boilerplate language to include in the umbrella issue in +> the repo: + +This issue tracks recommended changes resulting from an analysis of the +_PROJECT_ documentation commissioned by CNCF. The analysis and supporting +documents are here: https://github.com/cncf/techdocs/tree/main/analyses under +`00NN-project`. + +The CNCF _PROJECT_ documentation effort is tracked in the CNCF Tech Docs repo: +https://github.com/cncf/techdocs/issues + +## Umbrella issue + +> AUTHOR NOTE: Link to the umbrella issue in the project's documentation repo + +## Issues + +This is a list of issues representing the recommended work on the _PROJECT_ +website and technical documentation. + +> AUTHOR NOTE: Consider using the [issue](issue.md) template. + +### Issue: Item 1 + +> AUTHOR NOTE: Summarize the documentation changes prescribed by this issue. Use +> enough detail to estimate the scope of the issue. Fine-grained detail can go +> in the issue itself. In the GitHub umbrella issue, link to the sub-issue using +> a Markdown checkbox as shown below. + +- [ ] `https://github.com/_PROJECT_/repo/issues/NNN` + +### Issue: Item 2 + +> AUTHOR NOTE: ... and so on. \ No newline at end of file diff --git a/analyses/2026/kubevirt/issues.md b/analyses/2026/kubevirt/issues.md new file mode 100644 index 0000000..920bc16 --- /dev/null +++ b/analyses/2026/kubevirt/issues.md @@ -0,0 +1,64 @@ +--- +title: KubeVirt Issue +tags: KubeVirt +created: 2026-05-24 +modified: 2026-05-31 +author: @iRaindrop +--- + +> AUTHOR NOTE: This template provides one possible format for the individual +> issues filed in the Issues of a project repository. Within the CNCF tech docs +> repo, include all issues in one document, `_PROJECT_-issues.md`. See any +> completed analysis for an example. + +## Overview + +> AUTHOR NOTE: +> +> - Summarize the documentation changes prescribed by this issue. +> - For the audience, provide the user role to which the issue is most +> applicable. + +Audience: + +Type: + +> AUTHOR NOTE: What type of documentation topic the change affects. One of Task, +> Reference, or Conceptual. + +## Context + +> AUTHOR NOTE: This is boilerplate text linking back to the doc analysis. + +This issue tracks recommended changes resulting from an analysis of the etcd +documentation commissioned by CNCF. The analysis and supporting documents are +here: https://github.com/cncf/techdocs/tree/main/analyses under `00NN-project`. + +## Possible Implementation + +> AUTHOR NOTE: Include a bullet list of links to pages that are affected by the +> change: + +Related material in the current doc: + +- For example, + `https://github.com/_PROJECT_/website/tree/main/content/en/docs/v3.5/tutorials` + +> AUTHOR NOTE: Describe in detail a suggested way to achieve the goals of the +> issue. This should be specific enough to provide a contributor with a recipe +> for making the change; however, the contributor should feel free to solve the +> problem differently if they have an idea how it should be done. +> +> An EXAMPLE is provided next. + +Suggested changes: + +Use the following outline to write a procedure for each task: + +- Prerequisites (bullet list of prerequisite conditions, if any) +- Procedure + 1. Step 1 (keep steps discrete and atomic. Put command-line input and expected + output in a code block.) + 2. Step 2 ... +- Result (optional; describe output or side effects if they're notable or + unexpected.) \ No newline at end of file From 26907b2938bea59df64801c7933fa52669869d66 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Mon, 1 Jun 2026 19:59:29 -0700 Subject: [PATCH 02/13] spelling fixes - prittier Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/analysis.md | 69 ++++++++++++------------ analyses/2026/kubevirt/implementation.md | 6 +-- analyses/2026/kubevirt/issues-list.md | 6 +-- analyses/2026/kubevirt/issues.md | 6 +-- 4 files changed, 45 insertions(+), 42 deletions(-) diff --git a/analyses/2026/kubevirt/analysis.md b/analyses/2026/kubevirt/analysis.md index 514afd0..b22d01b 100644 --- a/analyses/2026/kubevirt/analysis.md +++ b/analyses/2026/kubevirt/analysis.md @@ -1,6 +1,6 @@ --- -title: KubeVirt Documentation Analysis -tags: KubeVirt +title: Kubevirt Documentation Analysis +tags: Kubevirt created: 2026-05-24 modified: 2026-05-31 author: @iRaindrop @@ -11,7 +11,7 @@ author: @iRaindrop ## Introduction This document is an analyzes the effectiveness and completeness of the -[KubeVirt](https://kubevirt.io) open source software (OSS) project's +[Kubevirt](https://Kubevirt.io) 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. @@ -23,17 +23,17 @@ efforts. ### Purpose -This document was written to analyze the current state of KubeVirt +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](implementation.md) document outlines an actionable plan for +[implementation](.implementation.md) document outlines an actionable plan for improvement. A third document is an [issues list](issues-list.md) 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 KubeVirt 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 @@ -41,51 +41,53 @@ This document: The documentation discussed here includes the entire contents of the website, the technical documentation, and documentation for contributors and users on the -KubeVirt GitHub repository. +Kubevirt GitHub repository. -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 KubeVirt GitHub repo. +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 Kubevirt GitHub repo. #### In scope -- Website: https://kubevirt.io -- Documentation: https://kubevirt.io/user-guide -- Website repo: https://github.com/kubevirt/user-guide - +- Website: https://Kubevirt.io +- Documentation: https://Kubevirt.io/user-guide +- Website repo: https://github.com/Kubevirt/user-guide #### Out of scope -- Other KubeVirt 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 KubeVirt +- **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 KubeVirt 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 KubeVirt 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. -The accompanying [implementation](./implementation.md) 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 `https://github.com/kubevirt/kubevirt/issues`. +The accompanying [implementation](./implementation.md) 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 +`https://github.com/Kubevirt/Kubevirt/issues`. ### How to use this document Readers interested only in actionable improvements should skip this document and -read the [implementation](./implementation.md) plan and [issues list](./issues-list.md). +read the [implementation](./implementation.md) plan and +[issues list](./issues-list.md). Readers interested in the current state of the documentation and the reasoning behind the recommendations should read the section of this document pertaining @@ -104,15 +106,16 @@ 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 +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 -KubeVirt is an **incubating** project of CNCF. This means that the project -should be developing professional-quality documentation alongside the project code. +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)] | | -------------------------- | -------------- | @@ -221,12 +224,12 @@ We evaluate on the following: > AUTHOR NOTE: Pick the CNCF maturity level of the project: -KubeVirt is a **graduated** project of CNCF. This means that the project should +Kubevirt is a **graduated** project of CNCF. This means that the project should have [_very high_][criteria] standards for documentation. > AUTHOR NOTE: or -KubeVirt 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_][criteria] professional-quality documentation alongside the project code. @@ -311,12 +314,12 @@ We evaluate on the following: > AUTHOR NOTE: Pick the CNCF maturity level of the project: -KubeVirt is a **graduated** project of CNCF. This means that the project should +Kubevirt is a **graduated** project of CNCF. This means that the project should have [_very high_][criteria] standards for documentation. > AUTHOR NOTE: or -KubeVirt 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_][criteria] professional-quality documentation alongside the project code. @@ -517,7 +520,7 @@ The numeric rating values used in this document are as follows [criteria]: ../criteria.md [implementation]: ./implementation.md [issues list]: ./issues-list.md -[project-website]: ?fixme-target-dne=https://kubevirt.o +[project-website]: ?fixme-target-dne=https://Kubevirt.o [Rating (1-5)]: #rating-values [rfc-spec]: https://www.rfc-editor.org/rfc/rfc2119 [website guidelines]: ../../website-guidelines-checklist.md diff --git a/analyses/2026/kubevirt/implementation.md b/analyses/2026/kubevirt/implementation.md index a87456d..597aa34 100644 --- a/analyses/2026/kubevirt/implementation.md +++ b/analyses/2026/kubevirt/implementation.md @@ -1,6 +1,6 @@ --- -title: Implementing KubeVirt Doc Improvements -tags: KubeVirt +title: Implementing Kubevirt Doc Improvements +tags: Kubevirt created: 2026-05-24 modified: 2026-05-31 author: @iRaindrop @@ -49,4 +49,4 @@ The top-level documentation recommendations for this project are: ### Issue 2 -[rfc-keywords]: https://www.rfc-editor.org/rfc/rfc2119 \ No newline at end of file +[rfc-keywords]: https://www.rfc-editor.org/rfc/rfc2119 diff --git a/analyses/2026/kubevirt/issues-list.md b/analyses/2026/kubevirt/issues-list.md index d87cb3c..b712bcf 100644 --- a/analyses/2026/kubevirt/issues-list.md +++ b/analyses/2026/kubevirt/issues-list.md @@ -1,6 +1,6 @@ --- -title: KubeVirt Umbrella Issue and Issues List -tags: KubeVirt +title: Kubevirt Umbrella Issue and Issues List +tags: Kubevirt created: 2026-05-24 modified: 2026-05-31 author: @iRaindrop @@ -52,4 +52,4 @@ website and technical documentation. ### Issue: Item 2 -> AUTHOR NOTE: ... and so on. \ No newline at end of file +> AUTHOR NOTE: ... and so on. diff --git a/analyses/2026/kubevirt/issues.md b/analyses/2026/kubevirt/issues.md index 920bc16..c3bcf0d 100644 --- a/analyses/2026/kubevirt/issues.md +++ b/analyses/2026/kubevirt/issues.md @@ -1,6 +1,6 @@ --- -title: KubeVirt Issue -tags: KubeVirt +title: Kubevirt Issue +tags: Kubevirt created: 2026-05-24 modified: 2026-05-31 author: @iRaindrop @@ -61,4 +61,4 @@ Use the following outline to write a procedure for each task: output in a code block.) 2. Step 2 ... - Result (optional; describe output or side effects if they're notable or - unexpected.) \ No newline at end of file + unexpected.) From 8eda7e5e4447db26259819e78795de1dd287cab8 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Mon, 1 Jun 2026 21:43:52 -0700 Subject: [PATCH 03/13] format fixes Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/analysis.md | 50 ++++++++++++------------ analyses/2026/kubevirt/implementation.md | 8 ++-- analyses/2026/kubevirt/issues-list.md | 9 ++--- analyses/2026/kubevirt/issues.md | 6 +-- 4 files changed, 36 insertions(+), 37 deletions(-) diff --git a/analyses/2026/kubevirt/analysis.md b/analyses/2026/kubevirt/analysis.md index b22d01b..bfdfd1a 100644 --- a/analyses/2026/kubevirt/analysis.md +++ b/analyses/2026/kubevirt/analysis.md @@ -1,9 +1,9 @@ --- -title: Kubevirt Documentation Analysis -tags: Kubevirt +title: KubeVIRT Documentation Analysis +tags: KubeVIRT created: 2026-05-24 modified: 2026-05-31 -author: @iRaindrop +author: iRaindrop --- @@ -11,7 +11,7 @@ author: @iRaindrop ## Introduction This document is an analyzes the effectiveness and completeness of the -[Kubevirt](https://Kubevirt.io) open source software (OSS) project's +[KubeVIRT](https://KubeVIRT.io) 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. @@ -23,7 +23,7 @@ efforts. ### Purpose -This document was written to analyze the current state of Kubevirt +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](.implementation.md) document outlines an actionable plan for @@ -33,7 +33,7 @@ by contributors to improve the documentation. This document: -- Analyzes the current Kubevirt 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 @@ -41,38 +41,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 -Kubevirt GitHub repository. +KubeVIRT GitHub repository. -The Kubevirt 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 Kubevirt GitHub repo. +code is stored on the KubeVIRT GitHub repo. #### In scope -- Website: https://Kubevirt.io -- Documentation: https://Kubevirt.io/user-guide -- Website repo: https://github.com/Kubevirt/user-guide +- Website: https://KubeVIRT.io +- Documentation: https://KubeVIRT.io/user-guide +- Website repo: https://github.com/KubeVIRT/user-guide #### Out of scope -- Other Kubevirt 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 Kubevirt +- **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 Kubevirt 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 Kubevirt 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. @@ -81,7 +81,7 @@ 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 -`https://github.com/Kubevirt/Kubevirt/issues`. +`https://github.com/KubeVIRT/KubeVIRT/issues`. ### How to use this document @@ -113,7 +113,7 @@ to legal requirements such as copyright and licensing issues. ## Project documentation -Kubevirt 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. @@ -224,12 +224,12 @@ We evaluate on the following: > AUTHOR NOTE: Pick the CNCF maturity level of the project: -Kubevirt is a **graduated** project of CNCF. This means that the project should +KubeVIRT is a **graduated** project of CNCF. This means that the project should have [_very high_][criteria] standards for documentation. > AUTHOR NOTE: or -Kubevirt 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_][criteria] professional-quality documentation alongside the project code. @@ -314,12 +314,12 @@ We evaluate on the following: > AUTHOR NOTE: Pick the CNCF maturity level of the project: -Kubevirt is a **graduated** project of CNCF. This means that the project should +KubeVIRT is a **graduated** project of CNCF. This means that the project should have [_very high_][criteria] standards for documentation. > AUTHOR NOTE: or -Kubevirt 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_][criteria] professional-quality documentation alongside the project code. @@ -517,10 +517,10 @@ The numeric rating values used in this document are as follows 4. Meets or exceeds standards 5. Exemplary -[criteria]: ../criteria.md + diff --git a/analyses/2026/kubevirt/implementation.md b/analyses/2026/kubevirt/implementation.md index 597aa34..afbeae4 100644 --- a/analyses/2026/kubevirt/implementation.md +++ b/analyses/2026/kubevirt/implementation.md @@ -1,9 +1,9 @@ --- -title: Implementing Kubevirt Doc Improvements -tags: Kubevirt +title: Implementing KubeVIRT Doc Improvements +tags: KubeVIRT created: 2026-05-24 modified: 2026-05-31 -author: @iRaindrop +author: iRaindrop --- @@ -49,4 +49,4 @@ The top-level documentation recommendations for this project are: ### Issue 2 -[rfc-keywords]: https://www.rfc-editor.org/rfc/rfc2119 + diff --git a/analyses/2026/kubevirt/issues-list.md b/analyses/2026/kubevirt/issues-list.md index b712bcf..3eb4d8a 100644 --- a/analyses/2026/kubevirt/issues-list.md +++ b/analyses/2026/kubevirt/issues-list.md @@ -1,9 +1,9 @@ --- -title: Kubevirt Umbrella Issue and Issues List -tags: Kubevirt +title: KubeVIRT Umbrella Issue and Issues List +tags: KubeVIRT created: 2026-05-24 modified: 2026-05-31 -author: @iRaindrop +author: iRaindrop --- ## Overview @@ -48,8 +48,7 @@ website and technical documentation. > in the issue itself. In the GitHub umbrella issue, link to the sub-issue using > a Markdown checkbox as shown below. -- [ ] `https://github.com/_PROJECT_/repo/issues/NNN` + ### Issue: Item 2 -> AUTHOR NOTE: ... and so on. diff --git a/analyses/2026/kubevirt/issues.md b/analyses/2026/kubevirt/issues.md index c3bcf0d..22bf54e 100644 --- a/analyses/2026/kubevirt/issues.md +++ b/analyses/2026/kubevirt/issues.md @@ -1,9 +1,9 @@ --- -title: Kubevirt Issue -tags: Kubevirt +title: KubeVIRT Issue +tags: KubeVIRT created: 2026-05-24 modified: 2026-05-31 -author: @iRaindrop +author: iRaindrop --- > AUTHOR NOTE: This template provides one possible format for the individual From 4122eb4e0ca2b3ab4cc48ff3d9bb911eb46a53ce Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Mon, 1 Jun 2026 22:15:39 -0700 Subject: [PATCH 04/13] more format fixes Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/analysis.md | 1 - analyses/2026/kubevirt/implementation.md | 1 - analyses/2026/kubevirt/issues-list.md | 2 -- analyses/2026/kubevirt/issues.md | 1 - 4 files changed, 5 deletions(-) diff --git a/analyses/2026/kubevirt/analysis.md b/analyses/2026/kubevirt/analysis.md index bfdfd1a..00ecaa7 100644 --- a/analyses/2026/kubevirt/analysis.md +++ b/analyses/2026/kubevirt/analysis.md @@ -1,6 +1,5 @@ --- title: KubeVIRT Documentation Analysis -tags: KubeVIRT created: 2026-05-24 modified: 2026-05-31 author: iRaindrop diff --git a/analyses/2026/kubevirt/implementation.md b/analyses/2026/kubevirt/implementation.md index afbeae4..5f4a6d9 100644 --- a/analyses/2026/kubevirt/implementation.md +++ b/analyses/2026/kubevirt/implementation.md @@ -1,6 +1,5 @@ --- title: Implementing KubeVIRT Doc Improvements -tags: KubeVIRT created: 2026-05-24 modified: 2026-05-31 author: iRaindrop diff --git a/analyses/2026/kubevirt/issues-list.md b/analyses/2026/kubevirt/issues-list.md index 3eb4d8a..1284b55 100644 --- a/analyses/2026/kubevirt/issues-list.md +++ b/analyses/2026/kubevirt/issues-list.md @@ -1,6 +1,5 @@ --- title: KubeVIRT Umbrella Issue and Issues List -tags: KubeVIRT created: 2026-05-24 modified: 2026-05-31 author: iRaindrop @@ -51,4 +50,3 @@ website and technical documentation. ### Issue: Item 2 - diff --git a/analyses/2026/kubevirt/issues.md b/analyses/2026/kubevirt/issues.md index 22bf54e..e4efe4e 100644 --- a/analyses/2026/kubevirt/issues.md +++ b/analyses/2026/kubevirt/issues.md @@ -1,6 +1,5 @@ --- title: KubeVIRT Issue -tags: KubeVIRT created: 2026-05-24 modified: 2026-05-31 author: iRaindrop From 9c6ab5045d2215b401a712f2bf9a90415624e8f1 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Mon, 1 Jun 2026 22:40:53 -0700 Subject: [PATCH 05/13] KubeVirt spelling false hit fix 1 Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/analysis.md | 258 ++------------------------ analyses/2026/kubevirt/issues-list.md | 15 +- 2 files changed, 25 insertions(+), 248 deletions(-) diff --git a/analyses/2026/kubevirt/analysis.md b/analyses/2026/kubevirt/analysis.md index 00ecaa7..8b9d99b 100644 --- a/analyses/2026/kubevirt/analysis.md +++ b/analyses/2026/kubevirt/analysis.md @@ -1,5 +1,5 @@ --- -title: KubeVIRT Documentation Analysis +title: "KubeVirt" Documentation Analysis created: 2026-05-24 modified: 2026-05-31 author: iRaindrop @@ -10,7 +10,7 @@ author: iRaindrop ## Introduction This document is an analyzes the effectiveness and completeness of the -[KubeVIRT](https://KubeVIRT.io) open source software (OSS) project's +["KubeVirt"](https://KubeVIRT.io) 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. @@ -22,7 +22,7 @@ efforts. ### Purpose -This document was written to analyze the current state of KubeVIRT +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](.implementation.md) document outlines an actionable plan for @@ -32,7 +32,7 @@ by contributors to improve the documentation. This document: -- Analyzes the current KubeVIRT 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,12 +40,12 @@ This document: The documentation discussed here includes the entire contents of the website, the technical documentation, and documentation for contributors and users on the -KubeVIRT GitHub repository. +"KubeVirt" GitHub repository. -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 KubeVIRT GitHub repo. +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 "KubeVirt" GitHub repo. #### In scope @@ -55,23 +55,23 @@ code is stored on the KubeVIRT GitHub repo. #### Out of scope -- Other KubeVIRT 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 KubeVIRT +- **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 KubeVIRT 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 KubeVIRT 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. @@ -80,7 +80,7 @@ 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 -`https://github.com/KubeVIRT/KubeVIRT/issues`. +`https://github.com/KubeVirt/KubeVIRT/issues`. ### How to use this document @@ -112,7 +112,7 @@ to legal requirements such as copyright and licensing issues. ## Project documentation -KubeVIRT 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. @@ -221,16 +221,9 @@ We evaluate on the following: ## Contributor documentation -> AUTHOR NOTE: Pick the CNCF maturity level of the project: - -KubeVIRT is a **graduated** project of CNCF. This means that the project should -have [_very high_][criteria] standards for documentation. - -> AUTHOR NOTE: or - -KubeVIRT is an **incubating** project of CNCF. This means that the project -should be [_developing_][criteria] professional-quality documentation alongside -the project code. +"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)] | | ----------------------------------------- | -------------- | @@ -308,218 +301,3 @@ We evaluate on the following: #### New contributor getting started content #### Project governance documentation - -## Website and infrastructure - -> AUTHOR NOTE: Pick the CNCF maturity level of the project: - -KubeVIRT is a **graduated** project of CNCF. This means that the project should -have [_very high_][criteria] standards for documentation. - -> AUTHOR NOTE: or - -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 | [rating (1-5)] | -| Meets min website req. (for maturity level) | [rating (1-5)] | -| Usability, accessibility, and design | [rating (1-5)] | -| Branding and design | [rating (1-5)] | -| Case studies/social proof | [rating (1-5)] | -| SEO, Analytics, and site-local search | [rating (1-5)] | -| Maintenance planning | [rating (1-5)] | -| A11y plan & implementation | [rating (1-5)] | -| Mobile-first plan & impl. | [rating (1-5)] | -| HTTPS access & HTTP redirect | [rating (1-5)] | -| Google Analytics 4 for production only | [rating (1-5)] | -| Indexing allowed for production server only | [rating (1-5)] | -| Intra-site / local search | [rating (1-5)] | -| Account custodians are documented | [rating (1-5)] | - -### Comments - -> AUTHOR NOTE: make any overall comments about the Website and documentation -> infrastructure here. - -The following sections contain brief assessments of each element of the Website -and documentation infrastructure rubric. - -> AUTHOR NOTE: for each heading below, discuss how well the in-scope items meet -> these criteria. Keep in mind that much of the website infrastructure criteria -> depend on the tools (static site generator, website framework and hosting, -> analytics tools, etc.) and processes (project CI, release procedures, -> governance, etc.) used to produce the documentation. (Criteria are copied from -> criteria.md) - -#### Single-source requirement - -Source files for _all website pages_ should reside in a single repo. Among other -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. - -#### 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 - -#### 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? -- Are doc pages readable? -- Are all / most website features accessible from mobile -- such as the top-nav, - site search and in-page table of contents? -- Might a [mobile-first] design make sense for your project? - -[mobile-first]: - https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Responsive/Mobile_first - -Plan for suitable [accessibility][] measures for your website. For example: - -- Are color contrasts significant enough for color-impaired readers? -- Are most website features usable using a keyboard only? -- Does text-to-speech offer listeners a good experience? - -It is up to each project to set their own guidelines. - -[accessibility]: https://developer.mozilla.org/en-US/docs/Web/Accessibility - -#### 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? -- Is the brand used across the website consistently? -- Is the website’s typography clean and well-suited for reading? - -#### 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? -- Are there user testimonials available? -- Is there an active project blog? -- Are there community talks for the project and are they present on the website? -- Is there a logo wall of users/participating organizations? - -#### 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? - - Is analytics disabled for all other deploys? - - If your project used Google Analytics, have you migrated to GA4? - - Can Page-not-found (404) reports easily be generated from you site - analytics? Provide a sample of the site's current top-10 404s. -- Is site indexing supported for the production server, while disabled for - website previews and builds for non-default branches? -- Is local intra-site search available from the website? -- Are the current custodian(s) of the following accounts clearly documented: - analytics, Google Search Console, site-search (such as Google CSE or Algolia) - -#### 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?) -- Are you actively cultivating website maintainers from within the community? -- Are site build times reasonable? -- Do site maintainers have adequate permissions? - -#### Other - -- Is your website accessible via HTTPS? -- Does HTTP access, if any, redirect to HTTPS? - -### Recommendations - -> AUTHOR NOTE: Write general recommendations based on the comments from the -> previous section. - -#### Single-source requirement - -#### Minimal website requirements - -#### Usability, accessibility and devices - -#### Branding and design - -#### Case studies/social proof - -#### SEO, Analytics and site-local search - -#### Maintenance planning - -#### Other - -#### 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 - - diff --git a/analyses/2026/kubevirt/issues-list.md b/analyses/2026/kubevirt/issues-list.md index 1284b55..ffd5712 100644 --- a/analyses/2026/kubevirt/issues-list.md +++ b/analyses/2026/kubevirt/issues-list.md @@ -21,12 +21,11 @@ author: iRaindrop > - The following is boilerplate language to include in the umbrella issue in > the repo: -This issue tracks recommended changes resulting from an analysis of the -_PROJECT_ documentation commissioned by CNCF. The analysis and supporting -documents are here: https://github.com/cncf/techdocs/tree/main/analyses under -`00NN-project`. +This issue tracks recommended changes resulting from an analysis of the KubeVIRT +documentation commissioned by CNCF. The analysis and supporting documents are +here: https://github.com/cncf/techdocs/tree/main/analyses under `2026`. -The CNCF _PROJECT_ documentation effort is tracked in the CNCF Tech Docs repo: +The CNCF KubeVIRT documentation effort is tracked in the CNCF Tech Docs repo: https://github.com/cncf/techdocs/issues ## Umbrella issue @@ -35,10 +34,10 @@ https://github.com/cncf/techdocs/issues ## Issues -This is a list of issues representing the recommended work on the _PROJECT_ +This is a list of issues representing the recommended work on the KubeVIRT website and technical documentation. -> AUTHOR NOTE: Consider using the [issue](issue.md) template. +> AUTHOR NOTE: Consider using the issue.md template. ### Issue: Item 1 @@ -47,6 +46,6 @@ website and technical documentation. > in the issue itself. In the GitHub umbrella issue, link to the sub-issue using > a Markdown checkbox as shown below. - + ### Issue: Item 2 From faceb99f47e18ad34db9d126cfbb020dc4bd5593 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Tue, 2 Jun 2026 12:54:59 -0700 Subject: [PATCH 06/13] digging out Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/analysis.md | 30 ++++++++++++------------ analyses/2026/kubevirt/implementation.md | 4 ++-- analyses/2026/kubevirt/issues-list.md | 10 ++++---- analyses/2026/kubevirt/issues.md | 2 +- 4 files changed, 23 insertions(+), 23 deletions(-) diff --git a/analyses/2026/kubevirt/analysis.md b/analyses/2026/kubevirt/analysis.md index 8b9d99b..8196267 100644 --- a/analyses/2026/kubevirt/analysis.md +++ b/analyses/2026/kubevirt/analysis.md @@ -1,5 +1,5 @@ --- -title: "KubeVirt" Documentation Analysis +title: KubeVirt Documentation Analysis created: 2026-05-24 modified: 2026-05-31 author: iRaindrop @@ -10,7 +10,7 @@ author: iRaindrop ## Introduction This document is an analyzes the effectiveness and completeness of the -["KubeVirt"](https://KubeVIRT.io) open source software (OSS) project's +[KubeVirt](https://KubeVIRT.io) 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. @@ -22,7 +22,7 @@ efforts. ### Purpose -This document was written to analyze the current state of "KubeVirt" +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](.implementation.md) document outlines an actionable plan for @@ -32,7 +32,7 @@ by contributors to improve the documentation. This document: -- Analyzes the current "KubeVirt" 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,12 +40,12 @@ This document: The documentation discussed here includes the entire contents of the website, the technical documentation, and documentation for contributors and users on the -"KubeVirt" GitHub repository. +KubeVirt GitHub repository. -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 "KubeVirt" GitHub repo. +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 KubeVirt GitHub repo. #### In scope @@ -55,23 +55,23 @@ site's code is stored on the "KubeVirt" GitHub repo. #### Out of scope -- Other "KubeVirt" 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 "KubeVirt" +- **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 "KubeVirt" 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 "KubeVirt" 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 -"KubeVirt" 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. @@ -221,7 +221,7 @@ We evaluate on the following: ## Contributor documentation -"KubeVirt" 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. diff --git a/analyses/2026/kubevirt/implementation.md b/analyses/2026/kubevirt/implementation.md index 5f4a6d9..f8fe4bc 100644 --- a/analyses/2026/kubevirt/implementation.md +++ b/analyses/2026/kubevirt/implementation.md @@ -1,5 +1,5 @@ --- -title: Implementing KubeVIRT Doc Improvements +title: Implementing KubeVirt Doc Improvements created: 2026-05-24 modified: 2026-05-31 author: iRaindrop @@ -23,7 +23,7 @@ things. Few recommendations here are meant to be prescriptive. Rather, recommendations are based on documentation best practices as understood by the reviewers. The recommended implementations represent the reviewers' experience with how to apply those best practices. In other words, borrowing terminology -from the lexicon of [RFCs][rfc-keywords], the changes described here should be +from the lexicon of RFCs (rfc-keywords), 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. diff --git a/analyses/2026/kubevirt/issues-list.md b/analyses/2026/kubevirt/issues-list.md index ffd5712..e06198d 100644 --- a/analyses/2026/kubevirt/issues-list.md +++ b/analyses/2026/kubevirt/issues-list.md @@ -1,5 +1,5 @@ --- -title: KubeVIRT Umbrella Issue and Issues List +title: KubeVirt Umbrella Issue and Issues List created: 2026-05-24 modified: 2026-05-31 author: iRaindrop @@ -21,11 +21,11 @@ author: iRaindrop > - The following is boilerplate language to include in the umbrella issue in > the repo: -This issue tracks recommended changes resulting from an analysis of the KubeVIRT +This issue tracks recommended changes resulting from an analysis of the KubeVirt documentation commissioned by CNCF. The analysis and supporting documents are here: https://github.com/cncf/techdocs/tree/main/analyses under `2026`. -The CNCF KubeVIRT documentation effort is tracked in the CNCF Tech Docs repo: +The CNCF KubeVirt documentation effort is tracked in the CNCF Tech Docs repo: https://github.com/cncf/techdocs/issues ## Umbrella issue @@ -34,7 +34,7 @@ https://github.com/cncf/techdocs/issues ## Issues -This is a list of issues representing the recommended work on the KubeVIRT +This is a list of issues representing the recommended work on the KubeVirt website and technical documentation. > AUTHOR NOTE: Consider using the issue.md template. @@ -46,6 +46,6 @@ website and technical documentation. > in the issue itself. In the GitHub umbrella issue, link to the sub-issue using > a Markdown checkbox as shown below. - + ### Issue: Item 2 diff --git a/analyses/2026/kubevirt/issues.md b/analyses/2026/kubevirt/issues.md index e4efe4e..be18ad6 100644 --- a/analyses/2026/kubevirt/issues.md +++ b/analyses/2026/kubevirt/issues.md @@ -1,5 +1,5 @@ --- -title: KubeVIRT Issue +title: KubeVirt Issue created: 2026-05-24 modified: 2026-05-31 author: iRaindrop From 5af478fc6c0e1e7d5fa6ae8fa754e3f5a8106d54 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Tue, 2 Jun 2026 13:16:11 -0700 Subject: [PATCH 07/13] spelling issues fixes Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/analysis.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/analyses/2026/kubevirt/analysis.md b/analyses/2026/kubevirt/analysis.md index 8196267..66c89db 100644 --- a/analyses/2026/kubevirt/analysis.md +++ b/analyses/2026/kubevirt/analysis.md @@ -25,7 +25,7 @@ efforts. 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](.implementation.md) document outlines an actionable plan for +[implementation](implementation.md) document outlines an actionable plan for improvement. A third document is an [issues list](issues-list.md) of issues to be added to the project documentation repository. These issues can be taken up by contributors to improve the documentation. @@ -75,7 +75,7 @@ Each section begins with summary ratings based on a rubric with appropriate - **Recommendations**: suggested changes that would improve the effectiveness of the documentation. -The accompanying [implementation](./implementation.md) document breaks the +The accompanying [implementation](implementation.md) 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 @@ -85,7 +85,7 @@ items are decomposed into a series of issues and entered on GitHub ### How to use this document Readers interested only in actionable improvements should skip this document and -read the [implementation](./implementation.md) plan and +read the [implementation](implementation.md) plan and [issues list](./issues-list.md). Readers interested in the current state of the documentation and the reasoning From e81ca9b4df1e11e12671c59b25cf9bfc903de6b9 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Tue, 2 Jun 2026 13:31:33 -0700 Subject: [PATCH 08/13] spelling extentsions test Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/implementation.md | 2 +- analyses/2026/kubevirt/issues-list.md | 15 ++++++++------- analyses/2026/kubevirt/issues.md | 2 +- 3 files changed, 10 insertions(+), 9 deletions(-) diff --git a/analyses/2026/kubevirt/implementation.md b/analyses/2026/kubevirt/implementation.md index f8fe4bc..ab4a2d4 100644 --- a/analyses/2026/kubevirt/implementation.md +++ b/analyses/2026/kubevirt/implementation.md @@ -1,5 +1,5 @@ --- -title: Implementing KubeVirt Doc Improvements +title: Implementing _PROJECT_ Doc Improvements created: 2026-05-24 modified: 2026-05-31 author: iRaindrop diff --git a/analyses/2026/kubevirt/issues-list.md b/analyses/2026/kubevirt/issues-list.md index e06198d..3c5acdb 100644 --- a/analyses/2026/kubevirt/issues-list.md +++ b/analyses/2026/kubevirt/issues-list.md @@ -1,5 +1,5 @@ --- -title: KubeVirt Umbrella Issue and Issues List +title: _PROJECT_ Umbrella Issue and Issues List created: 2026-05-24 modified: 2026-05-31 author: iRaindrop @@ -21,11 +21,12 @@ author: iRaindrop > - The following is boilerplate language to include in the umbrella issue in > the repo: -This issue tracks recommended changes resulting from an analysis of the KubeVirt -documentation commissioned by CNCF. The analysis and supporting documents are -here: https://github.com/cncf/techdocs/tree/main/analyses under `2026`. +This issue tracks recommended changes resulting from an analysis of the +_PROJECT_ documentation commissioned by CNCF. The analysis and supporting +documents are here: https://github.com/cncf/techdocs/tree/main/analyses under +`2026`. -The CNCF KubeVirt documentation effort is tracked in the CNCF Tech Docs repo: +The CNCF _PROJECT_ documentation effort is tracked in the CNCF Tech Docs repo: https://github.com/cncf/techdocs/issues ## Umbrella issue @@ -34,7 +35,7 @@ https://github.com/cncf/techdocs/issues ## Issues -This is a list of issues representing the recommended work on the KubeVirt +This is a list of issues representing the recommended work on the _PROJECT_ website and technical documentation. > AUTHOR NOTE: Consider using the issue.md template. @@ -46,6 +47,6 @@ website and technical documentation. > in the issue itself. In the GitHub umbrella issue, link to the sub-issue using > a Markdown checkbox as shown below. - + ### Issue: Item 2 diff --git a/analyses/2026/kubevirt/issues.md b/analyses/2026/kubevirt/issues.md index be18ad6..4d91874 100644 --- a/analyses/2026/kubevirt/issues.md +++ b/analyses/2026/kubevirt/issues.md @@ -1,5 +1,5 @@ --- -title: KubeVirt Issue +title: _PROJECT_ Issue created: 2026-05-24 modified: 2026-05-31 author: iRaindrop From f003fba466f0d7d92aa3c1986a2b9d70f29c839f Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Tue, 2 Jun 2026 13:37:14 -0700 Subject: [PATCH 09/13] replaced KubeVirt with _PROJECT_ until fix Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/analysis.md | 34 +++++++++++++++--------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/analyses/2026/kubevirt/analysis.md b/analyses/2026/kubevirt/analysis.md index 66c89db..2b9aa0d 100644 --- a/analyses/2026/kubevirt/analysis.md +++ b/analyses/2026/kubevirt/analysis.md @@ -1,5 +1,5 @@ --- -title: KubeVirt Documentation Analysis +title: _PROJECT_ Documentation Analysis created: 2026-05-24 modified: 2026-05-31 author: iRaindrop @@ -10,7 +10,7 @@ author: iRaindrop ## Introduction This document is an analyzes the effectiveness and completeness of the -[KubeVirt](https://KubeVIRT.io) open source software (OSS) project's +[_PROJECT_](https://_PROJECT_.io) 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. @@ -22,7 +22,7 @@ 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](implementation.md) document outlines an actionable plan for @@ -32,7 +32,7 @@ by contributors to improve the documentation. This document: -- Analyzes the current KubeVirt technical documentation and website +- 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 @@ -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 -KubeVirt GitHub repository. +_PROJECT_ GitHub repository. -The KubeVirt website and documentation are written in Markdown and are compiled +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 KubeVirt GitHub repo. +code is stored on the _PROJECT_ GitHub repo. #### In scope -- Website: https://KubeVIRT.io -- Documentation: https://KubeVIRT.io/user-guide -- Website repo: https://github.com/KubeVIRT/user-guide +- Website: https://_PROJECT_.io +- Documentation: https://_PROJECT_.io/user-guide +- Website repo: https://github.com/_PROJECT_/user-guide #### Out of scope -- Other KubeVirt GitHub repositories besides `user-guide`. +- 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 KubeVirt +- **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 KubeVirt OSS project. + 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 KubeVirt users achieve their goals. + how it does or does not help _PROJECT_ users achieve their goals. - **Recommendations**: suggested changes that would improve the effectiveness of the documentation. @@ -80,7 +80,7 @@ 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 -`https://github.com/KubeVirt/KubeVIRT/issues`. +`https://github.com/_PROJECT_/_PROJECT_/issues`. ### How to use this document @@ -112,7 +112,7 @@ to legal requirements such as copyright and licensing issues. ## Project documentation -KubeVirt is an **incubating** project of CNCF. This means that the project +_PROJECT_ is an **incubating** project of CNCF. This means that the project should be developing professional-quality documentation alongside the project code. @@ -221,7 +221,7 @@ We evaluate on the following: ## Contributor documentation -KubeVirt is an **incubating** project of CNCF. This means that the project +_PROJECT_ is an **incubating** project of CNCF. This means that the project should be developing professional-quality documentation alongside the project code. From a49ddfdbe5fbddff222a3b5577b713e59f38e3b5 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Tue, 2 Jun 2026 13:43:55 -0700 Subject: [PATCH 10/13] link fix Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/analysis.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/analyses/2026/kubevirt/analysis.md b/analyses/2026/kubevirt/analysis.md index 2b9aa0d..486cee9 100644 --- a/analyses/2026/kubevirt/analysis.md +++ b/analyses/2026/kubevirt/analysis.md @@ -9,11 +9,11 @@ author: iRaindrop ## Introduction -This document is an analyzes the effectiveness and completeness of the -[_PROJECT_](https://_PROJECT_.io) 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. +This document is an analyzes the effectiveness and completeness of the _PROJECT_ +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 From d002857067e29f0f398333fbf66ab7fc9062dd03 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Tue, 2 Jun 2026 14:05:39 -0700 Subject: [PATCH 11/13] misc fixes Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/analysis.md | 9 +++++---- analyses/2026/kubevirt/issues.md | 8 -------- 2 files changed, 5 insertions(+), 12 deletions(-) diff --git a/analyses/2026/kubevirt/analysis.md b/analyses/2026/kubevirt/analysis.md index 486cee9..8aa1dc2 100644 --- a/analyses/2026/kubevirt/analysis.md +++ b/analyses/2026/kubevirt/analysis.md @@ -49,9 +49,9 @@ code is stored on the _PROJECT_ GitHub repo. #### In scope -- Website: https://_PROJECT_.io + #### Out of scope @@ -79,8 +79,9 @@ The accompanying [implementation](implementation.md) 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 -`https://github.com/_PROJECT_/_PROJECT_/issues`. +items are decomposed into a series of issues and entered on GitHub. + +(provide link) ### How to use this document diff --git a/analyses/2026/kubevirt/issues.md b/analyses/2026/kubevirt/issues.md index 4d91874..3bd2092 100644 --- a/analyses/2026/kubevirt/issues.md +++ b/analyses/2026/kubevirt/issues.md @@ -5,11 +5,6 @@ modified: 2026-05-31 author: iRaindrop --- -> AUTHOR NOTE: This template provides one possible format for the individual -> issues filed in the Issues of a project repository. Within the CNCF tech docs -> repo, include all issues in one document, `_PROJECT_-issues.md`. See any -> completed analysis for an example. - ## Overview > AUTHOR NOTE: @@ -40,9 +35,6 @@ here: https://github.com/cncf/techdocs/tree/main/analyses under `00NN-project`. Related material in the current doc: -- For example, - `https://github.com/_PROJECT_/website/tree/main/content/en/docs/v3.5/tutorials` - > AUTHOR NOTE: Describe in detail a suggested way to achieve the goals of the > issue. This should be specific enough to provide a contributor with a recipe > for making the change; however, the contributor should feel free to solve the From 4e1bb876870681b709587bbddf2a39febb15cc91 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Tue, 2 Jun 2026 14:46:40 -0700 Subject: [PATCH 12/13] minor edit to rebuild Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/analysis.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/analyses/2026/kubevirt/analysis.md b/analyses/2026/kubevirt/analysis.md index 8aa1dc2..a01f90a 100644 --- a/analyses/2026/kubevirt/analysis.md +++ b/analyses/2026/kubevirt/analysis.md @@ -9,9 +9,9 @@ author: iRaindrop ## Introduction -This document is an analyzes the effectiveness and completeness of the _PROJECT_ -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 +This document is an analyzes 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. From 32176414c01ebcd35b3198c0fda796f128cc9403 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Tue, 2 Jun 2026 15:15:08 -0700 Subject: [PATCH 13/13] minor edit 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 a01f90a..1c05f85 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-05-31 +modified: 2026-06-02 author: iRaindrop ---