diff --git a/analyses/2026/kubevirt/analysis.md b/analyses/2026/kubevirt/analysis.md new file mode 100644 index 0000000..1c05f85 --- /dev/null +++ b/analyses/2026/kubevirt/analysis.md @@ -0,0 +1,304 @@ +--- +title: _PROJECT_ Documentation Analysis +created: 2026-05-24 +modified: 2026-06-02 +author: iRaindrop +--- + + + +## Introduction + +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. + +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](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 _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](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. + +(provide link) + +### 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 + +_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 + +> 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 + +_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 + +> 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 diff --git a/analyses/2026/kubevirt/implementation.md b/analyses/2026/kubevirt/implementation.md new file mode 100644 index 0000000..ab4a2d4 --- /dev/null +++ b/analyses/2026/kubevirt/implementation.md @@ -0,0 +1,51 @@ +--- +title: Implementing _PROJECT_ Doc Improvements +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 + + diff --git a/analyses/2026/kubevirt/issues-list.md b/analyses/2026/kubevirt/issues-list.md new file mode 100644 index 0000000..3c5acdb --- /dev/null +++ b/analyses/2026/kubevirt/issues-list.md @@ -0,0 +1,52 @@ +--- +title: _PROJECT_ Umbrella Issue and Issues List +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 +`2026`. + +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.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. + + + +### Issue: Item 2 diff --git a/analyses/2026/kubevirt/issues.md b/analyses/2026/kubevirt/issues.md new file mode 100644 index 0000000..3bd2092 --- /dev/null +++ b/analyses/2026/kubevirt/issues.md @@ -0,0 +1,55 @@ +--- +title: _PROJECT_ Issue +created: 2026-05-24 +modified: 2026-05-31 +author: iRaindrop +--- + +## 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: + +> 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.)