From 6ef594325e5f92f1c7bbd03dcadabd0c57f2579d Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Mon, 1 Dec 2025 15:21:55 -0700 Subject: [PATCH 1/4] Add Helm documentation analysis (0016-helm) --- analyses/0016-helm/analysis.md | 647 +++++++++++++++++++++++++++ analyses/0016-helm/implementation.md | 49 ++ analyses/0016-helm/index.md | 20 + analyses/0016-helm/issue.md | 61 +++ analyses/0016-helm/issues-list.md | 52 +++ 5 files changed, 829 insertions(+) create mode 100644 analyses/0016-helm/analysis.md create mode 100644 analyses/0016-helm/implementation.md create mode 100644 analyses/0016-helm/index.md create mode 100644 analyses/0016-helm/issue.md create mode 100644 analyses/0016-helm/issues-list.md diff --git a/analyses/0016-helm/analysis.md b/analyses/0016-helm/analysis.md new file mode 100644 index 0000000..9191f7c --- /dev/null +++ b/analyses/0016-helm/analysis.md @@ -0,0 +1,647 @@ +--- +title: Helm Documentation Analysis +tags: [Helm] +created: YYYY-MM-DD +modified: YYYY-MM-DD +author: Paige Calvert (@paigecalvert) +--- + + + +## Introduction + +This document is an analysis of the effectiveness and completeness of the +[Helm][https://helm.sh/] open source software (OSS) project's documentation +and website. It is funded by the 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 Helm +documentation. It aims to provide project leaders with an informed understanding +of potential problems in current project documentation. A second +[implementation] document, , outlines an actionable plan for improvement. A +third document is an [issues list] of issues to be added to the project +documentation repository. These issues can be taken up by contributors to +improve the documentation. + +This document: + +- Analyzes the current Helm 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 +helm-www GitHub repository. + +The Helm website and documentation are written in Markdown and are compiled using the Docusaurus static +site generator with the theme-classic theme and served from the Netlify +platform. The site's code is stored on the helm-www GitHub repo. + +#### In scope + +- Website: https://helm.sh/ +- Documentation: https://helm.sh/docs/ +- Website repo: https://github.com/helm/helm-www + +#### Out of scope + +- [helm/helm](https://github.com/helm/helm), [helm/community](https://github.com/helm/community), and other Helm subrepos + +### How this document is organized + +This document is divided into three sections that represent three major areas of +concern: + +- **Project documentation:** concerns documentation for users of the Helm + software, aimed at people who intend to use the project software +- **Contributor documentation:** concerns documentation for new and existing + contributors to the Helm OSS project +- **Website:** concerns the mechanics of publishing the documentation, and + includes branding, website structure, and maintainability + +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 Helm users achieve their goals. +- **Recommendations**: suggested changes that would improve the effectiveness of + the documentation. + +The accompanying [implementation] document breaks the recommendations down into +concrete actions that can be implemented by project contributors. Its focus is +on drilling down to specific, achievable work that can be completed in +constrained blocks of time. Ultimately, the implementation items are decomposed +into a series of [issues] and entered as GitHub [project-doc-website]/issues. + +### How to use this document + +Readers interested only in actionable improvements should skip this document and +read the **[implementation] plan** and **[issues] list**. + +Readers interested in the current state of the documentation and the reasoning +behind the recommendations should read the section of this document pertaining +to their area of concern: + +- [Project documentation](./?TODO=ADD-URL) +- [Contributor documentation](./?TODO=ADD-URL) +- [Website and documentation infrastructure](./?TODO=ADD-URL) + +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][rfc-spec], 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 + +> AUTHOR NOTE: Pick the CNCF maturity level of the project: + +Helm is a **graduated** project of CNCF. This means that the project should +have [_very high_][criteria] standards for documentation. + +> AUTHOR NOTE: or + +Helm 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)] | +| -------------------------- | -------------- | +| Information architecture | 3 | +| New user content | 3 | +| Content maintainability | 4 | +| Content creation processes | 4 | +| Inclusive language | 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? + - The Helm docs are lacking a high level overview that provides an introduction to the product, its use cases, user personas, and so on. + - The Using Helm page (https://helm.sh/docs/intro/using_helm) does include some conceptual information about the concepts of Helm charts, repositories, and releases + - The existing Introduction section (https://helm.sh/docs/intro/) includes information primarily for users of Helm charts (ie, no info for chart developers). It includes a quickstart guide that walks you through installing an example chart, a page on how to install Helm, a page with info about common Helm tasks like installing, upgrading, and working with repos, and a "cheat sheet" with quick references for common CLI commands. + - There is also some high level conceptual information in the "Topics" section of the docs. For example, Helm Architecture (https://helm.sh/docs/topics/architecture). + +- Is the documentation feature complete? (i.e., each product feature is documented) + - Overall, main Helm features are documented (like variables, template functions, hooks, and the Helm CLI) + - There are several new features/breaking changes that need to be updated for Helm 4. For example: + - kstatus watcher needs to be documented in the SDK docs and likely some user-facing docs needed outside of the SDK docs as well (https://github.com/helm/helm/pull/13604) + - OCI install with digest (https://github.com/helm/helm-www/pull/1629) + - Multi document values files (https://github.com/helm/helm/pull/13655) + - Allow signing multiple charts with single passphrase from stdin (https://github.com/helm/helm/pull/30718) + - Allow post-renderer to process hooks (https://github.com/helm/helm/pull/13154) + +- Are there step-by-step instructions (tasks, tutorials) documented for features? + - Tasks: + - The Helm docs don't really include step-by-step tasks. Instead, they tend to use descriptions of how a given features works, plus examples. For example, see the https://helm.sh/docs/howto/charts_tips_and_tricks/ page, which has information about how to do several tasks with Helm using paragraphs and examples. + - Note: Because Helm charts are highly configurable/customizable, in many cases, it's probably more useful for chart developers to have several examples versus traditional step-by-step instructions + - The page on Installing Helm (https://helm.sh/docs/intro/install) is a good example of documenting one-step procedures + - Syncing Your Chart Reposiotry (https://helm.sh/docs/howto/chart_repository_sync_example) is close to a traditional step-by-step guide. It uses headings rather than numbered steps, but seems like it could easily be converted to a numbered list of steps. It also includes helpful prerequisites and examples. + - Tutorials: + - There are tutorials on creating different types of plugins using the different supported runtimes (eg, https://helm.sh/docs/plugins/developer/tutorial-cli-plugin) + - There are several other pages that use a tutorial-style format that walks users through a specific example in order to explain a given task or feature. For example: + - https://helm.sh/docs/chart_template_guide/accessing_files uses a variety of examples to explain different ways to create and access named templates + - https://helm.sh/docs/chart_template_guide/notes_files walks users through an example of adding a NOTES.txt for a chart + +- Are there any key features which are documented but missing task documentation? + - For the most part, tasks for key features are covered. As mentioned above, at a high level, the Helm docs would likely benefit from including more step-by-step how-tos/tutorials, but seems that the docs do include at least a few examples for each of the key Helm features + +- Is the “happy path”/most common use case documented? + - Helm has a few different happy paths depending on the user persona: + - Chart users needs to understand how to install helm, install/upgrade charts, work with chart repositories, and so on + - Chart developers need to know how to work with features like values files, template functions, chart hooks, and so on + - For chart users, the "happy path" of initializing a chart repository, installing a chart, viewing release info for the chart, then uninstalling is documented in the Quickstart workflow. The Using Helm page also touches on each of the main tasks that a chart user would need to know about + - As a chart developer, it's not very clear from looking at the docs sidebar if there's a most common use case or "happy path" documented. The closest page to this is [Charts](https://helm.sh/docs/topics/charts), which does include lots of helpful info about the chart file structure, working with chart dependencies, templates and values, and more. However, it's a lot of info in one page, and it doesn't necessarily walk developers through how all these pieces should fit together to create a release. + +- Does task and tutorial content demonstrate atomicity and isolation of concerns? (Are tasks clearly named according to user goals?) + - Yes for the most part, tasks are given relevant headings. There are some pages like Using Helm that would probably be better broken down into several smaller pages that users can see from the sidebar + - There are some places where there is extra info under a heading that one might not expect to find. For example, under [Writing a Hook](https://helm.sh/docs/topics/charts_hooks#writing-a-hook), there is conceptual information about how hooks work, like that you can implement multiple hooks in a single resource or that multiple resources can be inplemented as the same type of hook. These are important details about how hooks work, but they are a bit hidden half way down a section whose heading uses a verb phrase. + +- If the documentation does not suffice, is there a clear escalation path for users needing more help? (FAQ, Troubleshooting) + - The community section of the docs (which is pulled in from the Helm community repository) includes most of the helpful info about troubleshooting. For example, https://helm.sh/community/developers/#troubleshooting provides information about working with the community and searching the existing issues in the Helm repo to troubleshoot. + - There are also some minimal FAQs here: https://helm.sh/docs/faq/. They include a few questions about installing and one question about uninstalling. It looks like this information is not really an "FAQ", but rather information about installing/uninstalling Helm that might have been documented under FAQs because it lacks a more permanent home. + +- If the product exposes an API, is there a complete reference? + - Yes, API reference is here: https://pkg.go.dev/helm.sh/helm/v4 + +- Is content up to date and accurate? + - There are several examples throughout the docs that use the Bitnami charts (ex: Quickstart and Using Helm pages). With the recent change from Broadcom, the images for those charts are no longer available free of charge, so these examples will need to be updated with new charts + - For the Helm v4 docs, there is a fair bit of out of date content. Some of the new features haven't been fully doc'd yet + - There's also several warnings "This page has not yet been updated for Helm 4." This content needs to be evaluated and updated + +#### 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.) + - There is an Introduction section and a Quickstart, both of which are labeled for new users + - However, the content in these sections is for chart users and does not include information that would be useful to chart developers just getting started. Would be good to add some getting started content more for the developer user persona + - Could probably use lots of the content in Using Helm to create getting started info for chart developers + +- Is installation documented step-by-step? + - Yes, although the installation steps are really just single comamnds (ie, one-step procedures) for a variety of different install environments. Step-by-step might not be necessary in this case + +- If needed, are multiple OSes documented? + - Yes, see all the different options for installing Helm: https://helm.sh/docs/intro/install + +- Do users know where to go after reading the getting started guide? + - There's no "next steps" info in the quick start guides that explains what the user should do next. In general, there's not a lot of info about the most common use cases for Helm, so it's not clear the user would be able to intuit how they could use Helm (unless they already had some idea about the technology and were just visiting the docs for information about the mechanics of a specific task). + +- Is your new user content clearly signposted on your site’s homepage or at the + top of your information architecture? + - There is Getting Started section on the site homepage. It includes Helm download commands and a link to Artiact Hub where you can find Helm charts. It links users to the docs for more infomation (specifically, it links to the installing Helm and using Helm docs pages). + +- Is there sample code or other example content that can easily be copy-pasted? + - Yes, the Helm docs includes lots of example code blocks. All code blocks have a copy button that allows them to be easily 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? + - Yes, Algolia DocSearch is set up + +- Are you planning for localization/internationalization with regards to site + directory structure? Is a localization framework present? + - Yes, site is localized. Helm.sh uses Docusaurus' built-in localization/translations feature to allow users to toggle between different languages + - Localization process documented here https://helm.sh/community/localization + +- Do you have a clearly documented method for versioning your content? + - Yes, the versioning process is documented in the readme: https://github.com/helm/helm-www/blob/main/README.md#versioning + - Helm.sh releases a new version of the docs with each major release + - Helm.sh uses the version number in the URL path for non-latest versions of the product (the latest version is served at the main /docs/ path with no version number) + - Version labels on the site are updated to use the latest minor/patch version + +#### 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? + - Documentation contribution how-tos are documented in the README + - Also in the Community section (eg https://helm.sh/community/localization) + - However, there isn't an ongoing process defined in terms of how often PRs get reviewed, standardized requirements for docs PR in order to be approved, a style guide, issue triage, etc. + +- Does your code release process account for documentation creation & updates? + - PRs include a checkbox for "this PR includes documentation", if applicable + - There doesn't seem to be a requirement that documentation PR exists (if needed) before a helm/helm PR is approved is merged + +- Who reviews and approves documentation pull requests? + - Maintainers of the helm-www repo + - Core project maintiners + +- Does the website have a clear owner/maintainer? + - Maintainers are listed in the OWNERS file https://github.com/helm/helm-www/blob/main/OWNERS + - Maintiners were recently updated to add/remove as needed, but there is not an ongoing practice around reviewing and updating the list of maintainers + +#### 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? + - No obvious instances of this in the docs themselves. +- Does the project use language like "simple", "easy", etc.? + - Yes, there's some marketing language throughout. Example: https://helm.sh/docs/topics/registries/#migrating-from-chart-repos + +### Recommendations + +> AUTHOR NOTE: Write general recommendations based on the comments from the +> previous section. + +#### Information architecture + +The information architecture could benefit from the following: +- The Introduction, How-to, Topics, Best Practices, Chart Template Guide, and FAQs sections should all be reviewed to see where there is redundant content that can be condensed. With the current naming of these sections, it's not clear to docs users or contributors how the pages are grouped, and what types of info should go where. +- Could consider creating high-level categories based on the major feature area. For example, a section on working with chart registries, plugins, variables/templates, and so on. +- The Chart Template Guide is a better example of having + +#### New user content + +The site could use a more cleraly labeled "getting started" section, with guides for all main user personas (both chart users and chart developers). For example, a quick start that shows how to create and release a simple chart and/or a page that explains that chart dev "happy path", including all the main tasks a chart developer should consider as part of creating and publishing a chart for their app + +#### Content maintainability & site mechanics + +Search, locaization, and versioning functionality all looks good/is useable on the site. + +Helm.sh is in need of a better process for reviewing and accepting localized documentation changes (including adding a new locale). There are several open PRs from people adding translations to the site, but not a good process for determining how those get reviewed, how drift is tracked/updated, and so on. A good example of this is here: https://opentelemetry.io/docs/contributing/localization/. + +#### Content creation processes + +The contributors docs could be better centralized and easier to search, maybe in a "Contribute to the Docs" section. Currently, the contributor info is spread across the readme, the ARCHITECTURE_DECISIONS doc, as well as the community section, which makes it hard to find, and hard to tell when it's out of date. + +Also, the team could make docs more "part of the definition of done" for new features. For example, when a docs update is needed, creating the docs PR could be required before a new feature PR to be merged. This would help ensure that the docs stay up to date. + +#### Inclusive language + +Helm.sh could choose an existing, industry-accepted style guide to point contributors to, including a link to the inclusive language website. This would help maintain inclusive, clear word choice throughout. + +Could also consider adding some of the terms to avoid to the existing `typos` plugin on the site so that these get flagged during the build process. + +## Contributor documentation + +> AUTHOR NOTE: Pick the CNCF maturity level of the project: + +Helm is a **graduated** project of CNCF. This means that the project should +have [_very high_][criteria] standards for documentation. + +> AUTHOR NOTE: or + +Helm 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 | 5 | +| Beginner friendly issue backlog | 3 | +| “New contributor” getting started content | 4 | +| Project governance documentation | 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? + - The community docs are automatically pulled into the site from the helm/community repo and published here https://helm.sh/community + - There's also a community section on the landing page with info about upcoming events, the slack, developer standups, and so on +- Is there a direct link to your GitHub organization/repository? + - There's an edit this page link on every docs page that allows the user to open it in github + - There are also links on the site homepage, in the community section, in the footer, +- Are weekly/monthly project meetings documented? Is it clear how someone can + join those meetings? + - Yes, on the community section on the landing page. And in the https://helm.sh/community section +- Are mailing lists documented? + - Yes: https://helm.sh/community/communication/#mailing-lists + +#### Beginner friendly issue backlog + +We evaluate on the following: + +- Are docs issues well-triaged? + - No, there are about one hundred docs issues, many irrelevant to the new site and not a clear traige plan or timelines in place for getting them reviewed +- Is there a clearly marked way for new contributors to make code or + documentation contributions (i.e. a “good first issue” label)? + - Yes, there's a good first issue label. Could be more regularly applied +- Are issues well-documented (i.e., more than just a title)? + - Yes in general, issues are well-documented. + - There is no issue template +- Are issues maintained for staleness? + - No, see above. + +#### 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? + - Yes, https://helm.sh/community. This is automatically pulled in from the helm/community repo using a plugin +- Is there a document specifically for new contributors/your first contribution? + - This page does a good job of including all the info for first-time contributors: https://helm.sh/community/developers + - This one too https://helm.sh/community/#your-first-contribution +- Do new users know where to get help? + - While there's nothing labeled "get help", it seems there's plenty of places where the slack channels, dev meetings, etc are listed for users + +#### Project governance documentation + +One of the CNCF’s core project values is open governance. + +We evaluate on the following: + +- Is project governance clearly documented? + - Yes https://helm.sh/community/governance/ + +### Recommendations + +> AUTHOR NOTE: Write general recommendations based on the comments from the +> previous section. + +#### Beginner friendly issue backlog + +Improved standards/practices around regular issue triage and maintaining issue freshness could help make the issue backlog a little easier to navigate. + +#### New contributor getting started content + +While new contributor docs are well documented, it also couldn't hurt to add a heading (in the Community docs, perhaps) that includes the terms "troubleshooting" or "get help", in case people search to website for those terms. + +## Website and infrastructure + +Helm is a **graduated** project of CNCF. This means that the project should +have [_very high_][criteria] standards for documentation. + +| 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? + - Yes +- Are doc pages readable? + - Yes +- Are all / most website features accessible from mobile -- such as the top-nav, + site search and in-page table of contents? + - Yes +- 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? + - Yes +- Is the brand used across the website consistently? + - Yes +- Is the website’s typography clean and well-suited for reading? + - Yes + +#### 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? + - Yes +- Are there community talks for the project and are they present on the website? + - ? +- Is there a logo wall of users/participating organizations? + - Yes + +#### 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? + - Yes +- 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-doc-website]: ./?https://helm.sh/docs/ +[project-website]: ./?https://helm.sh/ +[Rating (1-5)]: #rating-values +[rfc-spec]: https://www.rfc-editor.org/rfc/rfc2119 +[website guidelines]: ../../website-guidelines-checklist.md diff --git a/analyses/0016-helm/implementation.md b/analyses/0016-helm/implementation.md new file mode 100644 index 0000000..c4c7f05 --- /dev/null +++ b/analyses/0016-helm/implementation.md @@ -0,0 +1,49 @@ +--- +title: Implementing _PROJECT_ Doc Improvements +tags: [_PROJECT_] +--- + + + +## 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 diff --git a/analyses/0016-helm/index.md b/analyses/0016-helm/index.md new file mode 100644 index 0000000..0865fb0 --- /dev/null +++ b/analyses/0016-helm/index.md @@ -0,0 +1,20 @@ +--- +title: TechDoc Analysis Templates +--- + +# TechDoc Analysis Templates + +This section contains templates for analyzing a CNCF project's documentation. + +Use the templates in this directory to perform a documentation analysis for +CNCF. These materials provide: + +- A relatively objective set of criteria (a "rubric") for evaluating existing + documentation and website content, infrastructure, and support. +- An attempt to make the documentation analysis appropriate to the current (or + proposed) maturity level for the overall project. +- Emphasis on effective documentation that serves all users associated with the + project. + +For guidance in completing a documentation analysis, see +[Analysis how-to](../howto.md) and [criteria](../criteria.md) pages. diff --git a/analyses/0016-helm/issue.md b/analyses/0016-helm/issue.md new file mode 100644 index 0000000..b3da121 --- /dev/null +++ b/analyses/0016-helm/issue.md @@ -0,0 +1,61 @@ +--- +title: _PROJECT_ Issue +tags: [_PROJECT_] +--- + +> 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.) diff --git a/analyses/0016-helm/issues-list.md b/analyses/0016-helm/issues-list.md new file mode 100644 index 0000000..89c251c --- /dev/null +++ b/analyses/0016-helm/issues-list.md @@ -0,0 +1,52 @@ +--- +title: _PROJECT_ Umbrella Issue and Issues List +tags: [_PROJECT_] +--- + +## 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. From db3e7464182a0200bb79f28e1a1dde8e13552ee5 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Wed, 3 Dec 2025 13:09:46 -0700 Subject: [PATCH 2/4] analysis wip --- analyses/0016-helm/analysis.md | 647 ------------------ analyses/0016-helm/helm-analysis.md | 570 +++++++++++++++ ...plementation.md => helm-implementation.md} | 0 .../{issues-list.md => helm-issues-list.md} | 0 4 files changed, 570 insertions(+), 647 deletions(-) delete mode 100644 analyses/0016-helm/analysis.md create mode 100644 analyses/0016-helm/helm-analysis.md rename analyses/0016-helm/{implementation.md => helm-implementation.md} (100%) rename analyses/0016-helm/{issues-list.md => helm-issues-list.md} (100%) diff --git a/analyses/0016-helm/analysis.md b/analyses/0016-helm/analysis.md deleted file mode 100644 index 9191f7c..0000000 --- a/analyses/0016-helm/analysis.md +++ /dev/null @@ -1,647 +0,0 @@ ---- -title: Helm Documentation Analysis -tags: [Helm] -created: YYYY-MM-DD -modified: YYYY-MM-DD -author: Paige Calvert (@paigecalvert) ---- - - - -## Introduction - -This document is an analysis of the effectiveness and completeness of the -[Helm][https://helm.sh/] open source software (OSS) project's documentation -and website. It is funded by the 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 Helm -documentation. It aims to provide project leaders with an informed understanding -of potential problems in current project documentation. A second -[implementation] document, , outlines an actionable plan for improvement. A -third document is an [issues list] of issues to be added to the project -documentation repository. These issues can be taken up by contributors to -improve the documentation. - -This document: - -- Analyzes the current Helm 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 -helm-www GitHub repository. - -The Helm website and documentation are written in Markdown and are compiled using the Docusaurus static -site generator with the theme-classic theme and served from the Netlify -platform. The site's code is stored on the helm-www GitHub repo. - -#### In scope - -- Website: https://helm.sh/ -- Documentation: https://helm.sh/docs/ -- Website repo: https://github.com/helm/helm-www - -#### Out of scope - -- [helm/helm](https://github.com/helm/helm), [helm/community](https://github.com/helm/community), and other Helm subrepos - -### How this document is organized - -This document is divided into three sections that represent three major areas of -concern: - -- **Project documentation:** concerns documentation for users of the Helm - software, aimed at people who intend to use the project software -- **Contributor documentation:** concerns documentation for new and existing - contributors to the Helm OSS project -- **Website:** concerns the mechanics of publishing the documentation, and - includes branding, website structure, and maintainability - -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 Helm users achieve their goals. -- **Recommendations**: suggested changes that would improve the effectiveness of - the documentation. - -The accompanying [implementation] document breaks the recommendations down into -concrete actions that can be implemented by project contributors. Its focus is -on drilling down to specific, achievable work that can be completed in -constrained blocks of time. Ultimately, the implementation items are decomposed -into a series of [issues] and entered as GitHub [project-doc-website]/issues. - -### How to use this document - -Readers interested only in actionable improvements should skip this document and -read the **[implementation] plan** and **[issues] list**. - -Readers interested in the current state of the documentation and the reasoning -behind the recommendations should read the section of this document pertaining -to their area of concern: - -- [Project documentation](./?TODO=ADD-URL) -- [Contributor documentation](./?TODO=ADD-URL) -- [Website and documentation infrastructure](./?TODO=ADD-URL) - -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][rfc-spec], 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 - -> AUTHOR NOTE: Pick the CNCF maturity level of the project: - -Helm is a **graduated** project of CNCF. This means that the project should -have [_very high_][criteria] standards for documentation. - -> AUTHOR NOTE: or - -Helm 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)] | -| -------------------------- | -------------- | -| Information architecture | 3 | -| New user content | 3 | -| Content maintainability | 4 | -| Content creation processes | 4 | -| Inclusive language | 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? - - The Helm docs are lacking a high level overview that provides an introduction to the product, its use cases, user personas, and so on. - - The Using Helm page (https://helm.sh/docs/intro/using_helm) does include some conceptual information about the concepts of Helm charts, repositories, and releases - - The existing Introduction section (https://helm.sh/docs/intro/) includes information primarily for users of Helm charts (ie, no info for chart developers). It includes a quickstart guide that walks you through installing an example chart, a page on how to install Helm, a page with info about common Helm tasks like installing, upgrading, and working with repos, and a "cheat sheet" with quick references for common CLI commands. - - There is also some high level conceptual information in the "Topics" section of the docs. For example, Helm Architecture (https://helm.sh/docs/topics/architecture). - -- Is the documentation feature complete? (i.e., each product feature is documented) - - Overall, main Helm features are documented (like variables, template functions, hooks, and the Helm CLI) - - There are several new features/breaking changes that need to be updated for Helm 4. For example: - - kstatus watcher needs to be documented in the SDK docs and likely some user-facing docs needed outside of the SDK docs as well (https://github.com/helm/helm/pull/13604) - - OCI install with digest (https://github.com/helm/helm-www/pull/1629) - - Multi document values files (https://github.com/helm/helm/pull/13655) - - Allow signing multiple charts with single passphrase from stdin (https://github.com/helm/helm/pull/30718) - - Allow post-renderer to process hooks (https://github.com/helm/helm/pull/13154) - -- Are there step-by-step instructions (tasks, tutorials) documented for features? - - Tasks: - - The Helm docs don't really include step-by-step tasks. Instead, they tend to use descriptions of how a given features works, plus examples. For example, see the https://helm.sh/docs/howto/charts_tips_and_tricks/ page, which has information about how to do several tasks with Helm using paragraphs and examples. - - Note: Because Helm charts are highly configurable/customizable, in many cases, it's probably more useful for chart developers to have several examples versus traditional step-by-step instructions - - The page on Installing Helm (https://helm.sh/docs/intro/install) is a good example of documenting one-step procedures - - Syncing Your Chart Reposiotry (https://helm.sh/docs/howto/chart_repository_sync_example) is close to a traditional step-by-step guide. It uses headings rather than numbered steps, but seems like it could easily be converted to a numbered list of steps. It also includes helpful prerequisites and examples. - - Tutorials: - - There are tutorials on creating different types of plugins using the different supported runtimes (eg, https://helm.sh/docs/plugins/developer/tutorial-cli-plugin) - - There are several other pages that use a tutorial-style format that walks users through a specific example in order to explain a given task or feature. For example: - - https://helm.sh/docs/chart_template_guide/accessing_files uses a variety of examples to explain different ways to create and access named templates - - https://helm.sh/docs/chart_template_guide/notes_files walks users through an example of adding a NOTES.txt for a chart - -- Are there any key features which are documented but missing task documentation? - - For the most part, tasks for key features are covered. As mentioned above, at a high level, the Helm docs would likely benefit from including more step-by-step how-tos/tutorials, but seems that the docs do include at least a few examples for each of the key Helm features - -- Is the “happy path”/most common use case documented? - - Helm has a few different happy paths depending on the user persona: - - Chart users needs to understand how to install helm, install/upgrade charts, work with chart repositories, and so on - - Chart developers need to know how to work with features like values files, template functions, chart hooks, and so on - - For chart users, the "happy path" of initializing a chart repository, installing a chart, viewing release info for the chart, then uninstalling is documented in the Quickstart workflow. The Using Helm page also touches on each of the main tasks that a chart user would need to know about - - As a chart developer, it's not very clear from looking at the docs sidebar if there's a most common use case or "happy path" documented. The closest page to this is [Charts](https://helm.sh/docs/topics/charts), which does include lots of helpful info about the chart file structure, working with chart dependencies, templates and values, and more. However, it's a lot of info in one page, and it doesn't necessarily walk developers through how all these pieces should fit together to create a release. - -- Does task and tutorial content demonstrate atomicity and isolation of concerns? (Are tasks clearly named according to user goals?) - - Yes for the most part, tasks are given relevant headings. There are some pages like Using Helm that would probably be better broken down into several smaller pages that users can see from the sidebar - - There are some places where there is extra info under a heading that one might not expect to find. For example, under [Writing a Hook](https://helm.sh/docs/topics/charts_hooks#writing-a-hook), there is conceptual information about how hooks work, like that you can implement multiple hooks in a single resource or that multiple resources can be inplemented as the same type of hook. These are important details about how hooks work, but they are a bit hidden half way down a section whose heading uses a verb phrase. - -- If the documentation does not suffice, is there a clear escalation path for users needing more help? (FAQ, Troubleshooting) - - The community section of the docs (which is pulled in from the Helm community repository) includes most of the helpful info about troubleshooting. For example, https://helm.sh/community/developers/#troubleshooting provides information about working with the community and searching the existing issues in the Helm repo to troubleshoot. - - There are also some minimal FAQs here: https://helm.sh/docs/faq/. They include a few questions about installing and one question about uninstalling. It looks like this information is not really an "FAQ", but rather information about installing/uninstalling Helm that might have been documented under FAQs because it lacks a more permanent home. - -- If the product exposes an API, is there a complete reference? - - Yes, API reference is here: https://pkg.go.dev/helm.sh/helm/v4 - -- Is content up to date and accurate? - - There are several examples throughout the docs that use the Bitnami charts (ex: Quickstart and Using Helm pages). With the recent change from Broadcom, the images for those charts are no longer available free of charge, so these examples will need to be updated with new charts - - For the Helm v4 docs, there is a fair bit of out of date content. Some of the new features haven't been fully doc'd yet - - There's also several warnings "This page has not yet been updated for Helm 4." This content needs to be evaluated and updated - -#### 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.) - - There is an Introduction section and a Quickstart, both of which are labeled for new users - - However, the content in these sections is for chart users and does not include information that would be useful to chart developers just getting started. Would be good to add some getting started content more for the developer user persona - - Could probably use lots of the content in Using Helm to create getting started info for chart developers - -- Is installation documented step-by-step? - - Yes, although the installation steps are really just single comamnds (ie, one-step procedures) for a variety of different install environments. Step-by-step might not be necessary in this case - -- If needed, are multiple OSes documented? - - Yes, see all the different options for installing Helm: https://helm.sh/docs/intro/install - -- Do users know where to go after reading the getting started guide? - - There's no "next steps" info in the quick start guides that explains what the user should do next. In general, there's not a lot of info about the most common use cases for Helm, so it's not clear the user would be able to intuit how they could use Helm (unless they already had some idea about the technology and were just visiting the docs for information about the mechanics of a specific task). - -- Is your new user content clearly signposted on your site’s homepage or at the - top of your information architecture? - - There is Getting Started section on the site homepage. It includes Helm download commands and a link to Artiact Hub where you can find Helm charts. It links users to the docs for more infomation (specifically, it links to the installing Helm and using Helm docs pages). - -- Is there sample code or other example content that can easily be copy-pasted? - - Yes, the Helm docs includes lots of example code blocks. All code blocks have a copy button that allows them to be easily 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? - - Yes, Algolia DocSearch is set up - -- Are you planning for localization/internationalization with regards to site - directory structure? Is a localization framework present? - - Yes, site is localized. Helm.sh uses Docusaurus' built-in localization/translations feature to allow users to toggle between different languages - - Localization process documented here https://helm.sh/community/localization - -- Do you have a clearly documented method for versioning your content? - - Yes, the versioning process is documented in the readme: https://github.com/helm/helm-www/blob/main/README.md#versioning - - Helm.sh releases a new version of the docs with each major release - - Helm.sh uses the version number in the URL path for non-latest versions of the product (the latest version is served at the main /docs/ path with no version number) - - Version labels on the site are updated to use the latest minor/patch version - -#### 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? - - Documentation contribution how-tos are documented in the README - - Also in the Community section (eg https://helm.sh/community/localization) - - However, there isn't an ongoing process defined in terms of how often PRs get reviewed, standardized requirements for docs PR in order to be approved, a style guide, issue triage, etc. - -- Does your code release process account for documentation creation & updates? - - PRs include a checkbox for "this PR includes documentation", if applicable - - There doesn't seem to be a requirement that documentation PR exists (if needed) before a helm/helm PR is approved is merged - -- Who reviews and approves documentation pull requests? - - Maintainers of the helm-www repo - - Core project maintiners - -- Does the website have a clear owner/maintainer? - - Maintainers are listed in the OWNERS file https://github.com/helm/helm-www/blob/main/OWNERS - - Maintiners were recently updated to add/remove as needed, but there is not an ongoing practice around reviewing and updating the list of maintainers - -#### 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? - - No obvious instances of this in the docs themselves. -- Does the project use language like "simple", "easy", etc.? - - Yes, there's some marketing language throughout. Example: https://helm.sh/docs/topics/registries/#migrating-from-chart-repos - -### Recommendations - -> AUTHOR NOTE: Write general recommendations based on the comments from the -> previous section. - -#### Information architecture - -The information architecture could benefit from the following: -- The Introduction, How-to, Topics, Best Practices, Chart Template Guide, and FAQs sections should all be reviewed to see where there is redundant content that can be condensed. With the current naming of these sections, it's not clear to docs users or contributors how the pages are grouped, and what types of info should go where. -- Could consider creating high-level categories based on the major feature area. For example, a section on working with chart registries, plugins, variables/templates, and so on. -- The Chart Template Guide is a better example of having - -#### New user content - -The site could use a more cleraly labeled "getting started" section, with guides for all main user personas (both chart users and chart developers). For example, a quick start that shows how to create and release a simple chart and/or a page that explains that chart dev "happy path", including all the main tasks a chart developer should consider as part of creating and publishing a chart for their app - -#### Content maintainability & site mechanics - -Search, locaization, and versioning functionality all looks good/is useable on the site. - -Helm.sh is in need of a better process for reviewing and accepting localized documentation changes (including adding a new locale). There are several open PRs from people adding translations to the site, but not a good process for determining how those get reviewed, how drift is tracked/updated, and so on. A good example of this is here: https://opentelemetry.io/docs/contributing/localization/. - -#### Content creation processes - -The contributors docs could be better centralized and easier to search, maybe in a "Contribute to the Docs" section. Currently, the contributor info is spread across the readme, the ARCHITECTURE_DECISIONS doc, as well as the community section, which makes it hard to find, and hard to tell when it's out of date. - -Also, the team could make docs more "part of the definition of done" for new features. For example, when a docs update is needed, creating the docs PR could be required before a new feature PR to be merged. This would help ensure that the docs stay up to date. - -#### Inclusive language - -Helm.sh could choose an existing, industry-accepted style guide to point contributors to, including a link to the inclusive language website. This would help maintain inclusive, clear word choice throughout. - -Could also consider adding some of the terms to avoid to the existing `typos` plugin on the site so that these get flagged during the build process. - -## Contributor documentation - -> AUTHOR NOTE: Pick the CNCF maturity level of the project: - -Helm is a **graduated** project of CNCF. This means that the project should -have [_very high_][criteria] standards for documentation. - -> AUTHOR NOTE: or - -Helm 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 | 5 | -| Beginner friendly issue backlog | 3 | -| “New contributor” getting started content | 4 | -| Project governance documentation | 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? - - The community docs are automatically pulled into the site from the helm/community repo and published here https://helm.sh/community - - There's also a community section on the landing page with info about upcoming events, the slack, developer standups, and so on -- Is there a direct link to your GitHub organization/repository? - - There's an edit this page link on every docs page that allows the user to open it in github - - There are also links on the site homepage, in the community section, in the footer, -- Are weekly/monthly project meetings documented? Is it clear how someone can - join those meetings? - - Yes, on the community section on the landing page. And in the https://helm.sh/community section -- Are mailing lists documented? - - Yes: https://helm.sh/community/communication/#mailing-lists - -#### Beginner friendly issue backlog - -We evaluate on the following: - -- Are docs issues well-triaged? - - No, there are about one hundred docs issues, many irrelevant to the new site and not a clear traige plan or timelines in place for getting them reviewed -- Is there a clearly marked way for new contributors to make code or - documentation contributions (i.e. a “good first issue” label)? - - Yes, there's a good first issue label. Could be more regularly applied -- Are issues well-documented (i.e., more than just a title)? - - Yes in general, issues are well-documented. - - There is no issue template -- Are issues maintained for staleness? - - No, see above. - -#### 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? - - Yes, https://helm.sh/community. This is automatically pulled in from the helm/community repo using a plugin -- Is there a document specifically for new contributors/your first contribution? - - This page does a good job of including all the info for first-time contributors: https://helm.sh/community/developers - - This one too https://helm.sh/community/#your-first-contribution -- Do new users know where to get help? - - While there's nothing labeled "get help", it seems there's plenty of places where the slack channels, dev meetings, etc are listed for users - -#### Project governance documentation - -One of the CNCF’s core project values is open governance. - -We evaluate on the following: - -- Is project governance clearly documented? - - Yes https://helm.sh/community/governance/ - -### Recommendations - -> AUTHOR NOTE: Write general recommendations based on the comments from the -> previous section. - -#### Beginner friendly issue backlog - -Improved standards/practices around regular issue triage and maintaining issue freshness could help make the issue backlog a little easier to navigate. - -#### New contributor getting started content - -While new contributor docs are well documented, it also couldn't hurt to add a heading (in the Community docs, perhaps) that includes the terms "troubleshooting" or "get help", in case people search to website for those terms. - -## Website and infrastructure - -Helm is a **graduated** project of CNCF. This means that the project should -have [_very high_][criteria] standards for documentation. - -| 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? - - Yes -- Are doc pages readable? - - Yes -- Are all / most website features accessible from mobile -- such as the top-nav, - site search and in-page table of contents? - - Yes -- 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? - - Yes -- Is the brand used across the website consistently? - - Yes -- Is the website’s typography clean and well-suited for reading? - - Yes - -#### 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? - - Yes -- Are there community talks for the project and are they present on the website? - - ? -- Is there a logo wall of users/participating organizations? - - Yes - -#### 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? - - Yes -- 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-doc-website]: ./?https://helm.sh/docs/ -[project-website]: ./?https://helm.sh/ -[Rating (1-5)]: #rating-values -[rfc-spec]: https://www.rfc-editor.org/rfc/rfc2119 -[website guidelines]: ../../website-guidelines-checklist.md diff --git a/analyses/0016-helm/helm-analysis.md b/analyses/0016-helm/helm-analysis.md new file mode 100644 index 0000000..e070a55 --- /dev/null +++ b/analyses/0016-helm/helm-analysis.md @@ -0,0 +1,570 @@ +--- +title: Helm Documentation Analysis +tags: [Helm] +created: YYYY-MM-DD +modified: YYYY-MM-DD +author: Paige Calvert (@paigecalvert) +--- + + + +## Introduction + +This document is an analysis of the effectiveness and completeness of the +[Helm][https://helm.sh/] open source software (OSS) project's documentation +and website. It is funded by the 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 Helm +documentation. It aims to provide project leaders with an informed understanding +of potential problems in current project documentation. A second +[implementation] document, , outlines an actionable plan for improvement. A +third document is an [issues list] of issues to be added to the project +documentation repository. These issues can be taken up by contributors to +improve the documentation. + +This document: + +- Analyzes the current Helm 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 +helm-www GitHub repository. + +The Helm website and documentation are written in Markdown and are compiled using the Docusaurus static +site generator with the theme-classic theme and served from the Netlify +platform. The site's code is stored on the helm-www GitHub repo. + +#### In scope + +- Website: https://helm.sh/ +- Documentation: https://helm.sh/docs/ +- Website repo: https://github.com/helm/helm-www + +#### Out of scope + +- [helm/helm](https://github.com/helm/helm), [helm/community](https://github.com/helm/community), and other Helm subrepos + +### How this document is organized + +This document is divided into three sections that represent three major areas of +concern: + +- **Project documentation:** concerns documentation for users of the Helm + software, aimed at people who intend to use the project software +- **Contributor documentation:** concerns documentation for new and existing + contributors to the Helm OSS project +- **Website:** concerns the mechanics of publishing the documentation, and + includes branding, website structure, and maintainability + +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 Helm users achieve their goals. +- **Recommendations**: suggested changes that would improve the effectiveness of + the documentation. + +The accompanying [implementation] document breaks the recommendations down into +concrete actions that can be implemented by project contributors. Its focus is +on drilling down to specific, achievable work that can be completed in +constrained blocks of time. Ultimately, the implementation items are decomposed +into a series of [issues] and entered as GitHub [project-doc-website]/issues. + +### How to use this document + +Readers interested only in actionable improvements should skip this document and +read the **[implementation] plan** and **[issues] list**. + +Readers interested in the current state of the documentation and the reasoning +behind the recommendations should read the section of this document pertaining +to their area of concern: + +- [Project documentation](./?TODO=ADD-URL) +- [Contributor documentation](./?TODO=ADD-URL) +- [Website and documentation infrastructure](./?TODO=ADD-URL) + +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][rfc-spec], 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 + +> AUTHOR NOTE: Pick the CNCF maturity level of the project: + +Helm is a **graduated** project of CNCF. This means that the project should +have [_very high_][criteria] standards for documentation. + +> AUTHOR NOTE: or + +Helm 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)] | +| -------------------------- | -------------- | +| Information architecture | 2 - needs improvement | +| New user content | 2 - needs improvement | +| Content maintainability | 3 - meets standards | +| Content creation processes | 2 - needs improvement | +| Inclusive language | 3 - meets standards | + +### 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 + +**High level conceptual/“About” content** + +The Helm docs in general lack a high level overview that provides an introduction to the product, its use cases, user personas, and so on. + +There is some level of project overview/conceptual content on these pages: +- The Using Helm page (https://helm.sh/docs/intro/using_helm) does include some conceptual information about the concepts of Helm charts, repositories, and releases +- The Introduction section (https://helm.sh/docs/intro/) includes information primarily for users of Helm charts (ie, no info for chart developers). It includes a quickstart guide that walks you through installing an example chart, a page on how to install Helm, a page with info about common Helm tasks like installing, upgrading, and working with repos, and a "cheat sheet" with quick references for common CLI commands. +- There is also some high level conceptual information in the "Topics" section of the docs. For example, Helm Architecture (https://helm.sh/docs/topics/architecture). + +**Feature complete docs** + +Overall, main Helm features are documented (like variables, template functions, hooks, and the Helm CLI). + +But, there are several new features/breaking changes that need to be updated for Helm 4. For example: +- kstatus watcher needs to be documented in the SDK docs and likely some user-facing docs needed outside of the SDK docs as well (https://github.com/helm/helm/pull/13604) +- OCI install with digest (https://github.com/helm/helm-www/pull/1629) +- Multi document values files (https://github.com/helm/helm/pull/13655) +- Allow signing multiple charts with single passphrase from stdin (https://github.com/helm/helm/pull/30718) +- Allow post-renderer to process hooks (https://github.com/helm/helm/pull/13154) + + +**Step-by-step instructions** + +The Helm docs don't really include tasks in the recommended "step-by-step" format. Instead, they tend to use descriptions of how a given features works, plus examples. For example, see the https://helm.sh/docs/howto/charts_tips_and_tricks/ page, which has information about how to do several tasks with Helm using paragraphs and examples. For example: + - The page on Installing Helm (https://helm.sh/docs/intro/install) is a good example of documenting one-step procedures + - Syncing Your Chart Reposiotry (https://helm.sh/docs/howto/chart_repository_sync_example) is close to a traditional step-by-step guide. It uses headings rather than numbered steps, but seems like it could easily be converted to a numbered list of steps. It also includes helpful prerequisites and examples. + + Note: While it's important for the Helm docs to use a step-by-step format for procedures where appropriate, because Helm charts are highly configurable/customizable, in many cases, it's probably more useful for chart developers to have several examples versus traditional step-by-step instructions + +The Helm docs include some tutorials on workflows like creating different types of plugins using the different supported runtimes (eg, https://helm.sh/docs/plugins/developer/tutorial-cli-plugin). There are several other pages that use a tutorial-style format that walks users through a specific example in order to explain a given task or feature. For example: +- https://helm.sh/docs/chart_template_guide/accessing_files uses a variety of examples to explain different ways to create and access named templates +- https://helm.sh/docs/chart_template_guide/notes_files walks users through an example of adding a NOTES.txt for a chart + +Tasks for key features are generally well-documented. As mentioned above, at a high level, the Helm docs would likely benefit from including more step-by-step how-tos/tutorials, but seems that the docs do include at least a few examples for each of the key Helm features. + +For the most part, tasks demonstrate atomicity and isolation of concerns, and are given relevant headings. There are some pages like "Using Helm" that would probably be better broken down into several smaller pages that users can see from the sidebar. Also, there are some places where there is extra info under a heading that one might not expect to find there. For example, under [Writing a Hook](https://helm.sh/docs/topics/charts_hooks#writing-a-hook), there is conceptual information about how hooks work, like that you can implement multiple hooks in a single resource or that multiple resources can be inplemented as the same type of hook. These are important details about how hooks work, but they are a bit hidden half way down a section whose heading uses a verb phrase. + +**Happy path/common use cases** + +Helm has a few different happy paths depending on the user persona: +- Chart users needs to understand how to install helm, install/upgrade charts, work with chart repositories, and so on +- Chart developers need to know how to work with features like values files, template functions, chart hooks, and so on + +For chart users, the "happy path" of initializing a chart repository, installing a chart, viewing release info for the chart, then uninstalling is documented in the Quickstart workflow. The Using Helm page also touches on each of the main tasks that a chart user would need to know about + +As a chart developer, it's not very clear from looking at the docs sidebar if there's a most common use case or "happy path" documented. The closest page to this is [Charts](https://helm.sh/docs/topics/charts), which does include lots of helpful info about the chart file structure, working with chart dependencies, templates and values, and more. However, it's a lot of info in one page, and it doesn't necessarily walk developers through how all these pieces should fit together to create a release. + +**Clear escalation path to get more help** + +If the docs do not suffice, there are a couple places where an escalation path is documented for users that need more help: + - The community section of the docs (which is pulled in from the Helm community repository) includes most of the helpful info about troubleshooting. For example, https://helm.sh/community/developers/#troubleshooting provides information about working with the community and searching the existing issues in the Helm repo to troubleshoot. + - There are also some minimal FAQs here: https://helm.sh/docs/faq/. They include a few questions about installing and one question about uninstalling. It looks like this information is not really an "FAQ", but rather information about installing/uninstalling Helm that might have been documented under FAQs because it lacks a more permanent home. + +The Helm docs lack clear troubleshooting steps for different common tasks. + +**API reference** + +API reference is here: https://pkg.go.dev/helm.sh/helm/v4 + +**Content accuracy** + +In general, content is accurate. The main concern in terms of accuracy would be content that is out-of-date, particular when it comes to the latest Helm v4 docs. For example: +- There are several examples throughout the docs that use the Bitnami charts (ex: Quickstart and Using Helm pages). With the recent change from Broadcom, the images for those charts are no longer available free of charge, so these examples will need to be updated with new charts +- For the Helm v4 docs, there is a fair bit of out of date content. Some of the new features haven't been fully doc'd yet +- There's also several warnings "This page has not yet been updated for Helm 4." This content needs to be evaluated and updated + +#### New user content + +**Getting started content** + +There is Getting Started section on the site homepage. It includes Helm download commands and a link to Artiact Hub where you can find Helm charts. It links users to the docs for more infomation (specifically, it links to the installing Helm and using Helm docs pages). + +In terms of “getting started” docs that are clearly labeled as such, there is both an "Introduction" section and a page named "Quickstart". However, the content in these sections is for chart users and does not include information that would be useful to chart developers just getting started. + +After completing the quickstart or reading the introduction section, there's no clear info about what the user should do next. In general, there's not a lot of info about the most common use cases for Helm, so it's not clear the user would be able to intuit how they could use Helm (unless they already had some idea about the technology and were just visiting the docs for information about the mechanics of a specific task). + +**Step-by-step install procedures** + +The installation steps for Helm are really just single comamnds (ie, one-step procedures) for a variety of different install environments: https://helm.sh/docs/intro/install + +These install docs include code blocks that have a "copy" button which allows them to be easily copy-pasted. + +#### Content maintainability & site mechanics + +**Search** + +The documentation is searchable (it uses Algolia DocSearch). + +**Localization/i18n** + +The Helm website is localized. Helm.sh uses Docusaurus' built-in localization/translations feature to allow users to toggle between different languages. The localization process documented here: https://helm.sh/community/localization. + +**Versioning** + +The versioning process for the Helm website is documented in the readme: https://github.com/helm/helm-www/blob/main/README.md#versioning: + - Helm.sh releases a new version of the docs with each major release + - Helm.sh uses the version number in the URL path for non-latest versions of the product (the latest version is served at the main /docs/ path with no version number) + - Version labels on the site are updated to use the latest minor/patch version + +#### Content creation processes + +**Contribution process for documentation** + +Documentation contribution how-tos are documented in the helm-www README and in the Community section (eg https://helm.sh/community/localization) + +However, there isn't a clearly documented ongoing process for how often PRs/issues get reviewed, requirements for docs PRs in order to be approved, a style guide, issue triage plan, etc. + +**Code release process** + +The code release process does account for documentation creation and updates in that PR include a checkbox for "this PR includes documentation", if applicable. + +However, there doesn't seem to be a requirement that a documentation PR exists for a code change (if needed) before a code change is approved is merged. + +**Docs PR review/approval** + +Maintainers of the helm-www repo and core project maintainers can review and approve docs PRs. + +**Website owners** + +Maintainers are clearly listed in the OWNERS file https://github.com/helm/helm-www/blob/main/OWNERS. Maintiners were recently updated to add/remove as needed, but there is not an ongoing process for reviewing and updating the list of maintainers. + +#### Inclusive language + +There do not appear to be 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. + +The docs do occassionally use language like "simple", "easy", etc. Example: https://helm.sh/docs/topics/registries/#migrating-from-chart-repos + +### Recommendations + +> AUTHOR NOTE: Write general recommendations based on the comments from the +> previous section. + +#### Information architecture + +The information architecture could benefit from the following: +- The Introduction, How-to, Topics, Best Practices, Chart Template Guide, and FAQs sections should all be reviewed to see where there is redundant content that can be condensed. With the current naming of these sections, it's not clear to docs users or contributors how the pages are grouped, and what types of info should go where. +- Could consider creating high-level categories based on the major feature area. For example, a section on working with chart registries, plugins, variables/templates, and so on. +- The Chart Template Guide is a better example of having + +#### New user content + +The site could use a more cleraly labeled "getting started" section, with guides for all main user personas (both chart users and chart developers). For example, a quick start that shows how to create and release a simple chart and/or a page that explains that chart dev "happy path", including all the main tasks a chart developer should consider as part of creating and publishing a chart for their app. Could probably use lots of the content in Using Helm to create getting started info for chart developers + +#### Content maintainability & site mechanics + +Search, locaization, and versioning functionality all looks good/is useable on the site. + +Helm.sh is in need of a better process for reviewing and accepting localized documentation changes (including adding a new locale). There are several open PRs from people adding translations to the site, but not a good process for determining how those get reviewed, how drift is tracked/updated, and so on. A good example of this is here: https://opentelemetry.io/docs/contributing/localization/. + +#### Content creation processes + +The contributors docs could be better centralized and easier to search, maybe in a "Contribute to the Docs" section. Currently, the contributor info is spread across the readme, the ARCHITECTURE_DECISIONS doc, as well as the community section, which makes it hard to find, and hard to tell when it's out of date. + +Also, the team could make docs more "part of the definition of done" for new features. For example, when a docs update is needed, creating the docs PR could be required before a new feature PR to be merged. This would help ensure that the docs stay up to date. + +#### Inclusive language + +Helm.sh could choose an existing, industry-accepted style guide to point contributors to, including a link to the inclusive language website. This would help maintain inclusive, clear word choice throughout. + +Could also consider adding some of the terms to avoid to the existing `typos` plugin on the site so that these get flagged during the build process. + +## Contributor documentation + +> AUTHOR NOTE: Pick the CNCF maturity level of the project: + +Helm is a **graduated** project of CNCF. This means that the project should +have [_very high_][criteria] standards for documentation. + +> AUTHOR NOTE: or + +Helm 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 | 3 - meets standards | +| Beginner friendly issue backlog | 2 - needs improvement | +| “New contributor” getting started content | 3 - meets standards | +| Project governance documentation | 3 - meets standards | + +### 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 + +**Slack and dev meetings** + +The Helm Slack channels are prominently linked in the Join the Community section on the landing page. This section also has info about upcoming events, weekly developer standups (with info on how to join), and more. Additionally, the Community section of the website (https://helm.sh/community) also includes this information. + +**GitHub links** + +Users can find direct links to the Helm GitHub organization/repositories in a couple ways: +- There are links on the site homepage, in the community section, and in the footer to the main Helm github +- There's an edit this page link on every docs page that allows the user to open it in the helm-www repo in github + +**Mailing lists** + +Mailing lists are documented here: https://helm.sh/community/communication/#mailing-lists + +#### Beginner friendly issue backlog + +Docs issues are not very well triaged. There are nearly 100 open docs issues, many irrelevant to the new site. There is also no clear traige plan or timelines in place for addressing issues or reviewing them for freshness. + +There is a “good first issue” label, which new contributors can use to make code or documentation contributions. + +In general, issues are well-documented and include helpful descriptions beyond just a title. There doesn't seem to be an issue template. + +#### New contributor getting started content + +**Community docs** + +The website has a community section here: https://helm.sh/community. This is automatically pulled in from the helm/community repo using a plugin. + +**Docs for first-time contributors** + +Helm.sh has the following content that does a good job of providing info for first-time contributors: +- https://helm.sh/community/developers +- https://helm.sh/community/#your-first-contribution + +Also, while there's nothing specifically labeled "get help" on the site, there's plenty of places where the slack channels, dev meetings, etc are listed for users + +#### Project governance documentation + +Is Project governance clearly is documented here: https://helm.sh/community/governance/ + +### Recommendations + +> AUTHOR NOTE: Write general recommendations based on the comments from the +> previous section. + +#### Beginner friendly issue backlog + +Improved standards/practices around regular issue triage and maintaining issue freshness could help make the issue backlog a little easier to navigate. + +#### New contributor getting started content + +While new contributor docs are well documented, it also couldn't hurt to add a heading (in the Community docs, perhaps) that includes the terms "troubleshooting" or "get help", in case people search to website for those terms. + +## Website and infrastructure + +Helm is a **graduated** project of CNCF. This means that the project should +have [_very high_][criteria] standards for documentation. + +| Criterion | [Rating (1-5)] | +| ------------------------------------------- | -------------- | +| Single-source for all files | 3 - meets standards | +| Meets min website req. (for maturity level) | 3 - meets standards | +| Usability, accessibility, and design | 3 - meets standards | +| Branding and design | 3 - meets standards | +| Case studies/social proof | 1 - not present | +| SEO, Analytics, and site-local search | 3 - meets standards | +| Maintenance planning | 3 - meets standards | +| A11y plan & implementation | 3 - meets standards | +| Mobile-first plan & impl. | 3 - meets standards | +| HTTPS access & HTTP redirect | 3 - meets standards | +| Google Analytics 4 for production only | 1 - not present | +| Indexing allowed for production server only | 3 - meets standards | +| Intra-site / local search | 3 - meets standards | +| Account custodians are documented | 2 - needs improvement | + +### 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 + +Nearly all website pages reside in a single repo (helm/helm-www). The exception to this is the Community section of the website, which pulls in docs from the helm/community repo using a plugin. This is documented in the readme: https://github.com/helm/helm-www?tab=readme-ov-file#community-documentation. Additionally, the "Edit this page" link at the bottom of the community pages properly sends users to the page source in the helm/community repo to prevent users from accidentally editing the wrong source. + +The way the community section is set up, there is no need for maintainers to keep multiple versions of the community docs up-to-date/in sync. And, Helm maintainers have indicated that pulling in the community doc in this way is useful for making the information more findable for users. + +#### 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 + +**Usability / mobile experience** + +The website usable from mobile (doc pages are readable, and all website features are accessible from mobile including the top-nav, site search and in-page table of contents) + +**Accessibility** + +A Chrome Lighthouse audit on the helm.sh site gives a score of 94/100 for accessibility. It reports that the light blue link color (such as for the word Kubernetes on the landing page subtitle) is not high enough contrast for color-impaired readers. It also reports that there are some links that use only color to differentiate them from the surrounding text. + +Did not test the text-to-speech, but the amount of code and special characters in the text generally means that text-to-speech is not likely to be a good experience for users. + +#### Branding and design + +There is an easily recognizable brand for the project (logo + color scheme) that is used across the website consistently. The website's typography is consistent and easy to read. The only exception is that the font used for headings can be somewhat difficult to read for some of the letters. + +#### Case studies/social proof + +There is a logo wall of participating organizations featured at the bottom of the landing page (called "Supporters"). There is not a list of Helm users, but perhaps the supporters are also the users that would be listed + +There do not appear to be any case studies or testimonials available for the project that are documented on the website. I do see Helm case studies on the CNCF website, but not sure how recent or relevant these are: https://www.cncf.io/case-studies/?_sft_lf-project=helm + +#### SEO, Analytics and site-local search + +**Analytics** + +Analytics is not set up for the site. + +**SEO, Indexing, and Search** + +Local intra-site search is available from the website. Search is powered by Algolia DocSearch. The production site is well-indexed thanks to a built-in Algolia config for Docusaurus site, and is reindexed daily (this schedule is controlled by an algolia crawler setting). + +**Account custodians** + +The current custodian(s) of the following Algolia account is not specifically documented, but the repo does have an OWNERS file. + +#### Maintenance planning + +**Website tooling** + +The website uses Docusaurus, which has a robust open source community and is actively maintained. Before Helm.sh was migrated to Docusaurus, the migration and tooling was discussed with the CNCF tech docs team to make sure it was recommended. + +**Website maintainers** + +There is no indication that the project is actively cultivating website maintainers from the community. + +**Build times** + +Build times can be quite long (10+ mins). This is because Docusaurus builds a separate site for each locale, and Helm.sh has several locales. There is a script in the repo that is designed to use the Docusaurus cache to reduce build times (particularly useful for more quickly generating previews on PRs). This script tends to have varied results, but can reduce build times down to a reasonable 1-3 mins. + +#### Other + +The website is accessible via HTTPS and requests using HTTP are properly redirected to the HTTPS URLs. + +### Recommendations + +> AUTHOR NOTE: Write general recommendations based on the comments from the +> previous section. + +#### Single-source requirement + +No recommendations + +#### Minimal website requirements + +#### Usability, accessibility and devices + +No recommendations + +#### Branding and design + +No recommendations + +#### Case studies/social proof + +Could add a link to case studies on the landing page and/or prioritize writing and publishing case studies in the blog + +#### SEO, Analytics and site-local search + +Add analytics to the production server (could use Google Analytics (GA) 4), and ensure that 404 reports are collected and tracked using the analytics service. + +#### Maintenance planning + +Consider troubleshooting the existing script to see why it inconsistently reduces build times. + +#### Other + +No recommendations + +#### 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-doc-website]: ./?https://helm.sh/docs/ +[project-website]: ./?https://helm.sh/ +[Rating (1-5)]: #rating-values +[rfc-spec]: https://www.rfc-editor.org/rfc/rfc2119 +[website guidelines]: ../../website-guidelines-checklist.md diff --git a/analyses/0016-helm/implementation.md b/analyses/0016-helm/helm-implementation.md similarity index 100% rename from analyses/0016-helm/implementation.md rename to analyses/0016-helm/helm-implementation.md diff --git a/analyses/0016-helm/issues-list.md b/analyses/0016-helm/helm-issues-list.md similarity index 100% rename from analyses/0016-helm/issues-list.md rename to analyses/0016-helm/helm-issues-list.md From 22cbcb75966833fb32a92f1d39225e7a1470c09e Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Wed, 3 Dec 2025 18:29:36 -0700 Subject: [PATCH 3/4] implemntation details wip --- analyses/0016-helm/helm-analysis.md | 26 ++---- analyses/0016-helm/helm-implementation.md | 98 +++++++++++++++++++++-- 2 files changed, 97 insertions(+), 27 deletions(-) diff --git a/analyses/0016-helm/helm-analysis.md b/analyses/0016-helm/helm-analysis.md index e070a55..199d6cb 100644 --- a/analyses/0016-helm/helm-analysis.md +++ b/analyses/0016-helm/helm-analysis.md @@ -218,7 +218,9 @@ There is Getting Started section on the site homepage. It includes Helm download In terms of “getting started” docs that are clearly labeled as such, there is both an "Introduction" section and a page named "Quickstart". However, the content in these sections is for chart users and does not include information that would be useful to chart developers just getting started. -After completing the quickstart or reading the introduction section, there's no clear info about what the user should do next. In general, there's not a lot of info about the most common use cases for Helm, so it's not clear the user would be able to intuit how they could use Helm (unless they already had some idea about the technology and were just visiting the docs for information about the mechanics of a specific task). +After completing the quickstart or reading the introduction section, there's no clear info about what the user should do next. In general, it's hard to grock the most common use cases for Helm from looking at the docs table of contents, so it's not clear the user would be able to intuit how they could use Helm. + +This Next Steps page in the Chart Template Guide does provide a good example of pointing chart developers to more information about chart development: https://helm.sh/docs/chart_template_guide/wrapping_up **Step-by-step install procedures** @@ -301,9 +303,9 @@ Also, the team could make docs more "part of the definition of done" for new fea #### Inclusive language -Helm.sh could choose an existing, industry-accepted style guide to point contributors to, including a link to the inclusive language website. This would help maintain inclusive, clear word choice throughout. +Review the docs for terms like "simply" and "easy" and remove them. -Could also consider adding some of the terms to avoid to the existing `typos` plugin on the site so that these get flagged during the build process. +Helm.sh could also choose an existing, industry-accepted style guide to point contributors to, including a link to the inclusive language website. This would help maintain inclusive, clear word choice throughout. ## Contributor documentation @@ -518,20 +520,6 @@ The website is accessible via HTTPS and requests using HTTP are properly redirec > AUTHOR NOTE: Write general recommendations based on the comments from the > previous section. -#### Single-source requirement - -No recommendations - -#### Minimal website requirements - -#### Usability, accessibility and devices - -No recommendations - -#### Branding and design - -No recommendations - #### Case studies/social proof Could add a link to case studies on the landing page and/or prioritize writing and publishing case studies in the blog @@ -544,10 +532,6 @@ Add analytics to the production server (could use Google Analytics (GA) 4), and Consider troubleshooting the existing script to see why it inconsistently reduces build times. -#### Other - -No recommendations - #### References and notes ##### Rating values diff --git a/analyses/0016-helm/helm-implementation.md b/analyses/0016-helm/helm-implementation.md index c4c7f05..24b1f3e 100644 --- a/analyses/0016-helm/helm-implementation.md +++ b/analyses/0016-helm/helm-implementation.md @@ -34,16 +34,102 @@ The top-level documentation recommendations for this project are: > of independent changes. For examples, see a completed implementation plan such > as 0008-Backstage or 0010-etcd. -## High-level action 1 +## Reorganize the main docs sidebar -### Issue 1 +Here is a proposed sidebar: -### Issue 2 +- Docs Home +- Helm 4 + - What's New? (https://helm.sh/docs/overview) + - [Full Changelog](https://helm.sh/docs/changelog) +- Introduction + - Overview (A new Helm Overview page. Use the existing content in [Helm Architecture](https://helm.sh/docs/topics/architecture) and add content from [Three Big Concepts](https://helm.sh/docs/intro/using_helm#three-big-concepts) in _Using Helm_) + - Installing Helm + - Kubernetes Distribution Guide + - Glossary +- Install and Use Charts + - Quickstart + - Using Helm + - [Cheat Sheet](https://helm.sh/docs/intro/CheatSheet) + - [Advanced Helm Techniques](https://helm.sh/docs/topics/advanced) + - Configure Storage Backends (from https://helm.sh/docs/topics/advanced#storage-backends) + - Permissions management for SQL storage backend + - [Helm Provenance and Integrity](https://helm.sh/docs/topics/provenance) + - Role-based Access Control +- Develop Charts + - Charts (eventually, this page could be broken out into smaller pages) + - Library Charts + - Chart Values and Templates + - [most of the existing pages under [Chart Template Guide](https://helm.sh/docs/chart_template_guide/)] + - Chart Hooks + - Chart Tests + - Chart Releaser Action to Automate GitHub Page Charts + - [The .helmignore file](https://helm.sh/docs/chart_template_guide/helm_ignore_file) + - [Creating a NOTES.txt File](https://helm.sh/docs/chart_template_guide/notes_files) + - Chart Development Best Practices + - [Chart Development Tips and Tricks](https://helm.sh/docs/howto/charts_tips_and_tricks) + - [other existing bets practices pages] +- Use Chart Repositories + - The Chart Repository Guide + - Use OCI-based registries + - Syncing Your Chart Repository +- Use and Develop Plugins + - Overview + - Using Plugins + - Developing Plugins +- Helm Commands +- Go SDK +- Policies + - Release Schedule Policy + - Helm Version Support Policy -## High-level action 2 +## Add a technical/conceptual overview of Helm -### Issue 1 +Put architecture, operating principles, and other conceptual explanations in the technical overview. -### Issue 2 +## Prune out-of-date content + +There are several pages in the docs that are likely out-of-date or otherwise no longer relevant. For example: +- "FAQs" https://helm.sh/docs/faq/installing and https://helm.sh/docs/faq/uninstalling +- Best practices section: https://helm.sh/docs/chart_best_practices/ +- Tips and tricks: https://helm.sh/docs/howto/charts_tips_and_tricks + +For each of these pages/section, if possible, prefer distributing the content across other existing pages so that these pages might be deleted. For example, could the RBAC best practices listed at https://helm.sh/docs/chart_best_practices/rbac be instead incorporated into the existing page on [Role-Based Access Control](https://helm.sh/docs/topics/rbac)? + +Alternatively, if the content is still important and doesn't fit well elsewhere in the docs, make the necessary updates so that it is up-to-date and accurate. + +## Finish the Helm v4 docs + +### Document all the new features, improvements, and fixes released with Helm 4 + +### Review and update all the pages with the "This page has not yet been updated for Helm 4" warning + +This warning was added to several pages in the Helm 4 docs to indicate that they've not yet been updated: + +"This page has not yet been updated for Helm 4. Some of the content might be inaccurate or not applicable to Helm 4. For more information about the Helm 4 new features, improvements, and breaking changes, see Helm 4 Overview." + +## Rewrite tasks as step-by-step procedures + +CNCF strongly recommends that tasks and procedures are written as step-by-step instructions. For example: + +```mdx +To do [task]: +1. Do the first step. +1. Do the second step. +``` + +This is also an industry-standard for technical documentation (See the Google Developer Docs style guide https://developers.google.com/style/procedures) + +The Helm docs tend not to use step-by-step instructions for tasks and procedures. This is not ideal because it can cause conpetual/procedural/reference content to be inadvertently blended together, which makes information less findable to users. For users looking to accomplish a task, it can be challenging to weed through paragraphs. + +To improve the docs user experience, all tasks that are documented in the Helm docs should be reformatted or rewritten so that they use numbered steps. For example, each of the headings in https://helm.sh/docs/howto/chart_repository_sync_example could be converted to a numbered step in an ordered list. Assigning numbers to each item would make it immediately clearer that this is a prcedure that can be followed in order. + +## Improve docs contribution processes + +### Create and publish a clear process for adding and maintaining localized documentation + +### Create and publish a clear process for triaging the issue backlog and reviewing PRs + +### Incorporate documentation into the code change workflow [rfc-keywords]: https://www.rfc-editor.org/rfc/rfc2119 From 5699c4b10ca2623c9e16267a9e061b5db4883f0e Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Wed, 3 Dec 2025 19:10:20 -0700 Subject: [PATCH 4/4] add more implementation details --- analyses/0016-helm/helm-implementation.md | 86 +++++++++++++++-------- 1 file changed, 57 insertions(+), 29 deletions(-) diff --git a/analyses/0016-helm/helm-implementation.md b/analyses/0016-helm/helm-implementation.md index 24b1f3e..cd2830a 100644 --- a/analyses/0016-helm/helm-implementation.md +++ b/analyses/0016-helm/helm-implementation.md @@ -36,56 +36,67 @@ The top-level documentation recommendations for this project are: ## Reorganize the main docs sidebar -Here is a proposed sidebar: +As is, it is difficult for users to find information in the main docs sidebar. Some of the categories seek to group information by content type (How-To and Topics), while other categories group content by the specific product area (Chart Template Guide and Plugins). This inconsistency makes it difficult to intuit where the info you want might be located. It also makes it harder for docs contributors to decide where to situate a new page. -- Docs Home +The overall organization could be much improved by following a more consistent pattern: +- Include clearly labeled intro/new user content at the top +- At the highest level, group content by product area (for example, some product areas might be plugins, charts, and chart repositories) +- Within each product area, add concepts and tasks for the different user personas/use cases. For example, for charts, there need to be docs for users installing and using charts, as well as for users developing and releasing charts +- Consider pulling out reference material like CLI docs or info about policies to the top level, unassociated with a specific product area + +Here is a proposed sidebar based on the above (note that this proposal attempts to keep existing pages intact as much as possible to make this easier to implement): + +- [Docs Home](https://helm.sh/docs/) - Helm 4 - What's New? (https://helm.sh/docs/overview) - [Full Changelog](https://helm.sh/docs/changelog) - Introduction - Overview (A new Helm Overview page. Use the existing content in [Helm Architecture](https://helm.sh/docs/topics/architecture) and add content from [Three Big Concepts](https://helm.sh/docs/intro/using_helm#three-big-concepts) in _Using Helm_) - - Installing Helm - - Kubernetes Distribution Guide - - Glossary + - [Quickstart](https://helm.sh/docs/intro/quickstart) + - [Installing Helm](https://helm.sh/docs/intro/install) + - [Kubernetes Distribution Guide](https://helm.sh/docs/topics/kubernetes_distros) + - [Glossary](https://helm.sh/docs/glossary/) - Install and Use Charts - - Quickstart - - Using Helm + - [Using Helm](https://helm.sh/docs/intro/using_helm) - [Cheat Sheet](https://helm.sh/docs/intro/CheatSheet) - - [Advanced Helm Techniques](https://helm.sh/docs/topics/advanced) + - Post Rendering (from https://helm.sh/docs/topics/advanced#post-rendering. Recommend breaking up "Advanced Helm Techniques" into two pages: Post-Rendering and Configure Store Backends. The title "Advanced Helm Techniques" makes it hard for users to guess what might be in it) - Configure Storage Backends (from https://helm.sh/docs/topics/advanced#storage-backends) - - Permissions management for SQL storage backend + - [Permissions management for SQL storage backend](https://helm.sh/docs/topics/permissions_sql_storage_backend) - [Helm Provenance and Integrity](https://helm.sh/docs/topics/provenance) - - Role-based Access Control + - [Role-based Access Control](https://helm.sh/docs/topics/rbac) - Develop Charts - - Charts (eventually, this page could be broken out into smaller pages) - - Library Charts + - [Charts](https://helm.sh/docs/topics/charts) (eventually, this page could probably be broken out into smaller pages) + - [Chart Hooks](https://helm.sh/docs/topics/charts_hooks) + - [Chart Tests](https://helm.sh/docs/topics/chart_tests) + - [Library Charts](https://helm.sh/docs/topics/library_charts) - Chart Values and Templates - [most of the existing pages under [Chart Template Guide](https://helm.sh/docs/chart_template_guide/)] - - Chart Hooks - - Chart Tests - - Chart Releaser Action to Automate GitHub Page Charts - [The .helmignore file](https://helm.sh/docs/chart_template_guide/helm_ignore_file) - [Creating a NOTES.txt File](https://helm.sh/docs/chart_template_guide/notes_files) - Chart Development Best Practices - [Chart Development Tips and Tricks](https://helm.sh/docs/howto/charts_tips_and_tricks) - [other existing bets practices pages] -- Use Chart Repositories - - The Chart Repository Guide - - Use OCI-based registries - - Syncing Your Chart Repository +- Release Charts + - [The Chart Repository Guide](https://helm.sh/docs/topics/chart_repository) + - [Use OCI-based registries](https://helm.sh/docs/topics/registries) + - [Syncing Your Chart Repository](https://helm.sh/docs/howto/chart_repository_sync_example) + - [Chart Releaser Action to Automate GitHub Page Charts](https://helm.sh/docs/howto/chart_releaser_action) - Use and Develop Plugins - - Overview - - Using Plugins - - Developing Plugins -- Helm Commands -- Go SDK + - [Overview](https://helm.sh/docs/plugins/overview) + - [Using Plugins](https://helm.sh/docs/plugins/user/) + - [Developing Plugins](https://helm.sh/docs/plugins/developer/) + - [existing tutorials] +- [Helm Commands](https://helm.sh/docs/helm/) +- [Go SDK](https://helm.sh/docs/sdk/) - Policies - - Release Schedule Policy - - Helm Version Support Policy + - [Release Schedule Policy](https://helm.sh/docs/topics/release_policy) + - [Helm Version Support Policy](https://helm.sh/docs/topics/version_skew) ## Add a technical/conceptual overview of Helm -Put architecture, operating principles, and other conceptual explanations in the technical overview. +Put architecture, operating principles, and other conceptual explanations in a high-level technical overview. + +There is some existing content in the site that can probably be used to build this overview, particularly in [Helm Architecture](https://helm.sh/docs/topics/architecture). The goal of this new overview would be to give new users a good foundation to get started with Helm, including an understanding of the most common use cases, the typical user personas, and the primary concepts/terms to know. ## Prune out-of-date content @@ -100,7 +111,14 @@ Alternatively, if the content is still important and doesn't fit well elsewhere ## Finish the Helm v4 docs -### Document all the new features, improvements, and fixes released with Helm 4 +### Document all the new features released with Helm 4 + +Make sure that all the Helm 4 features, improvements, and fixes are documented. For example: +- kstatus watcher needs to be documented in the SDK docs and likely some user-facing docs needed outside of the SDK docs as well (https://github.com/helm/helm/pull/13604) +- OCI install with digest (https://github.com/helm/helm-www/pull/1629) +- Multi document values files (https://github.com/helm/helm/pull/13655) +- Allow signing multiple charts with single passphrase from stdin (https://github.com/helm/helm/pull/30718) +- Allow post-renderer to process hooks (https://github.com/helm/helm/pull/13154) ### Review and update all the pages with the "This page has not yet been updated for Helm 4" warning @@ -108,6 +126,8 @@ This warning was added to several pages in the Helm 4 docs to indicate that they "This page has not yet been updated for Helm 4. Some of the content might be inaccurate or not applicable to Helm 4. For more information about the Helm 4 new features, improvements, and breaking changes, see Helm 4 Overview." +Review all the pages where this warning appears, and review them to make any necessary updates. Then, remove the warning. + ## Rewrite tasks as step-by-step procedures CNCF strongly recommends that tasks and procedures are written as step-by-step instructions. For example: @@ -128,8 +148,16 @@ To improve the docs user experience, all tasks that are documented in the Helm d ### Create and publish a clear process for adding and maintaining localized documentation +There is not currently a process for adding a new locale to the docs, maintaining/tracking drift in existing locales, or reviewing PRs to localized content. + +This has led to several locales which are minimally translated and are lacking a plan or committment from community members for ongoing maintenance. It has also led to several localization PRs and issues sitting open and unreviewed indefinitely, without contributors understanding what they need to do to get them merged. + +The CNCF docs team has share the following guidance that the OpenTelemetry project uses for localizing their docs: https://opentelemetry.io/docs/contributing/localization/ + +The Helm docs maintainers should review these guidelines and make a plan for rolling out similar processes. + ### Create and publish a clear process for triaging the issue backlog and reviewing PRs -### Incorporate documentation into the code change workflow +Similar to above, the helm-www repo should have clearer processes for triaging issues and reviewing/merging PRs. As is, there are dozens of open issues and PRs that are not regularly reviewed for freshness or otherwise responded to by maintainers. Agreeing on and publishing a set of processes could make it easier for maintainers and contributors to understand how to review issues/PRs, and how long it should take for issues/PRs to be reviewed. [rfc-keywords]: https://www.rfc-editor.org/rfc/rfc2119