From 7503f86a0c549a57c5e57dfcae7e047fc5fcabb8 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Thu, 4 Dec 2025 09:40:24 -0700 Subject: [PATCH 1/4] Add Helm tech doc analysis Signed-off-by: Paige Calvert --- analyses/0016-helm/helm-analysis.md | 554 ++++++++++++++++++++++ analyses/0016-helm/helm-implementation.md | 163 +++++++ 2 files changed, 717 insertions(+) create mode 100644 analyses/0016-helm/helm-analysis.md create mode 100644 analyses/0016-helm/helm-implementation.md diff --git a/analyses/0016-helm/helm-analysis.md b/analyses/0016-helm/helm-analysis.md new file mode 100644 index 0000000..3fd5e2d --- /dev/null +++ b/analyses/0016-helm/helm-analysis.md @@ -0,0 +1,554 @@ +--- +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 | 4 - meets or exceeds 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, 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** + +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 + +Review the docs for terms like "simply" and "easy" and remove them. + +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 + +> 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 | 4 - meets or exceeds standards | +| Branding and design | 4 - meets or exceeds 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. + +#### 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. + +#### 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 \ No newline at end of file diff --git a/analyses/0016-helm/helm-implementation.md b/analyses/0016-helm/helm-implementation.md new file mode 100644 index 0000000..f8d4dab --- /dev/null +++ b/analyses/0016-helm/helm-implementation.md @@ -0,0 +1,163 @@ +--- +title: Implementing Helm Doc Improvements +tags: [Helm] +--- + + + +## Introduction + +This document provides actionable suggestions for improving the Helm +technical documentation. + +For an analysis and general discussion of recommendations on Helm technical +documentation, see [analysis.md](helm-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. + +## Reorganize the main docs 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. + +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_) + - [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 + - [Using Helm](https://helm.sh/docs/intro/using_helm) + - [Cheat Sheet](https://helm.sh/docs/intro/CheatSheet) + - 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](https://helm.sh/docs/topics/permissions_sql_storage_backend) + - [Helm Provenance and Integrity](https://helm.sh/docs/topics/provenance) + - [Role-based Access Control](https://helm.sh/docs/topics/rbac) +- Develop 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/)] + - [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] +- 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](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](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 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 + +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 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 + +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." + +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: + +```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 + +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 + +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 \ No newline at end of file From 82962ee579963949e8f3b5439b294185ec79cc21 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Thu, 4 Dec 2025 10:24:01 -0700 Subject: [PATCH 2/4] Edit links and add issues list doc Signed-off-by: Paige Calvert --- analyses/0016-helm/helm-analysis.md | 85 ++++++-------------------- analyses/0016-helm/helm-issues-list.md | 52 ++++++++++++++++ 2 files changed, 70 insertions(+), 67 deletions(-) create mode 100644 analyses/0016-helm/helm-issues-list.md diff --git a/analyses/0016-helm/helm-analysis.md b/analyses/0016-helm/helm-analysis.md index 3fd5e2d..90ec096 100644 --- a/analyses/0016-helm/helm-analysis.md +++ b/analyses/0016-helm/helm-analysis.md @@ -1,7 +1,7 @@ --- title: Helm Documentation Analysis tags: [Helm] -created: YYYY-MM-DD +created: 2025-12-04 modified: YYYY-MM-DD author: Paige Calvert (@paigecalvert) --- @@ -11,7 +11,7 @@ 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 +[Helm][project-website] 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. @@ -25,7 +25,7 @@ efforts. 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 +[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. @@ -80,20 +80,20 @@ 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. +into a series of [issues] and entered as GitHub [issues](https://github.com/helm/helm-www/issues). ### How to use this document Readers interested only in actionable improvements should skip this document and -read the **[implementation] plan** and **[issues] list**. +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) +- [Project documentation](#project-documentation) +- [Contributor documentation](#contributor-documentation) +- [Website and documentation infrastructure](#website-and-infrastructure) Examples of CNCF documentation that demonstrate the analysis criteria are linked from the [criteria] specification. @@ -112,17 +112,9 @@ 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 | @@ -133,15 +125,9 @@ the project code. ### 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** @@ -275,15 +261,13 @@ The docs do occassionally use language like "simple", "easy", etc. Example: http ### 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 +It will be helpful to find greater specificity in the naming strategy for categories. With the current naming of the sections in the sidebar, it's not clear to docs users or contributors how the pages are grouped, and what types of info should go where. Many sections are named by content type (how-to, topics, faqs, best practices). This is fine, but can be challenging to maintain and find content when it's not clear what qualifies as each content type (for example, Topics has become a large catch-all category). By using more specific categories that align with a given product area or use case, it'll be more obvious where info can be found. + +Additionally, content throughout should be reviewed to see where there is redundant content that can be condensed. For example, lots of the pages in Topics, FAQs, Introduction, Best Practices feels out-of-date or redundant with other pages + +Finally, procedures should be converted to step-by-step instructions for better readability. #### New user content @@ -297,7 +281,7 @@ Helm.sh is in need of a better process for reviewing and accepting localized doc #### 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. +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, [CONTRIBUTING](https://github.com/paigecalvert/helm-www/blob/main/CONTRIBUTING.md), and the Community section, which makes it a bit harder to find, and harder 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. @@ -309,17 +293,9 @@ Helm.sh could also choose an existing, industry-accepted style guide to point co ## 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 | @@ -329,17 +305,9 @@ the project code. ### 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** @@ -384,9 +352,6 @@ Is Project governance clearly is documented here: https://helm.sh/community/gove ### 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. @@ -419,19 +384,9 @@ have [_very high_][criteria] standards for documentation. ### 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. @@ -456,7 +411,6 @@ only two levels for which a tech docs analysis can be requested.) -[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 @@ -517,9 +471,6 @@ The website is accessible via HTTPS and requests using HTTP are properly redirec ### Recommendations -> AUTHOR NOTE: Write general recommendations based on the comments from the -> previous section. - #### 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 @@ -545,10 +496,10 @@ The numeric rating values used in this document are as follows 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/ +[implementation]: ./helm-implementation.md +[issues list]: ./helm-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 \ No newline at end of file diff --git a/analyses/0016-helm/helm-issues-list.md b/analyses/0016-helm/helm-issues-list.md new file mode 100644 index 0000000..89c251c --- /dev/null +++ b/analyses/0016-helm/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 0b0060417510218bc190eaa3db7827c9950cb46d Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Mon, 8 Dec 2025 14:49:44 -0700 Subject: [PATCH 3/4] update proposed sidebar & typo and md formatting fixes Signed-off-by: Paige Calvert --- analyses/0016-helm/helm-analysis.md | 579 +++++++++++++++------- analyses/0016-helm/helm-implementation.md | 217 +++++--- 2 files changed, 555 insertions(+), 241 deletions(-) diff --git a/analyses/0016-helm/helm-analysis.md b/analyses/0016-helm/helm-analysis.md index 90ec096..25e8947 100644 --- a/analyses/0016-helm/helm-analysis.md +++ b/analyses/0016-helm/helm-analysis.md @@ -4,6 +4,7 @@ tags: [Helm] created: 2025-12-04 modified: YYYY-MM-DD author: Paige Calvert (@paigecalvert) +cSpell:ignore: paigecalvert subrepos kstatus Bitnami --- @@ -23,8 +24,8 @@ 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 +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 @@ -33,18 +34,20 @@ 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 +- 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 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. +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 @@ -54,12 +57,13 @@ platform. The site's code is stored on the helm-www GitHub repo. #### Out of scope -- [helm/helm](https://github.com/helm/helm), [helm/community](https://github.com/helm/community), and other Helm subrepos +- [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: +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 @@ -73,19 +77,20 @@ Each section begins with summary ratings based on a rubric with appropriate - **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. +- **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 [issues](https://github.com/helm/helm-www/issues). +into a series of [issues] and entered as GitHub +[issues](https://github.com/helm/helm-www/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 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 @@ -95,8 +100,8 @@ to their area of concern: - [Contributor documentation](#contributor-documentation) - [Website and documentation infrastructure](#website-and-infrastructure) -Examples of CNCF documentation that demonstrate the analysis criteria are linked -from the [criteria] specification. +Examples of CNCF documentation that demonstrate the analysis criteria are +linked from the [criteria] specification. #### Recommendations, requirements, and best practices @@ -105,23 +110,23 @@ 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. +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 Helm is a **graduated** project of CNCF. This means that the project should have [_very high_][criteria] standards for documentation. -| Criterion | [Rating (1-5)] | -| -------------------------- | -------------- | -| Information architecture | 2 - needs improvement | -| New user content | 2 - needs improvement | +| Criterion | [Rating (1-5)] | +| -------------------------- | ------------------------------ | +| Information architecture | 2 - needs improvement | +| New user content | 2 - needs improvement | | Content maintainability | 4 - meets or exceeds standards | -| Content creation processes | 2 - needs improvement | -| Inclusive language | 3 - meets standards | +| Content creation processes | 2 - needs improvement | +| Inclusive language | 3 - meets standards | ### Comments @@ -130,178 +135,340 @@ Documentation rubric. #### Information architecture -**High level conceptual/“About” content** +##### 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. +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** +- 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 -Overall, main Helm features are documented (like variables, template functions, hooks, and the Helm CLI). +- 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. -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) +- 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 -**Step-by-step instructions** +Overall, main Helm features are documented (like variables, template functions, +hooks, and the Helm CLI). -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. +But, there are several new features/breaking changes that need to be updated +for Helm 4. For example: - 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 +- 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) -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 +- OCI install with digest (https://github.com/helm/helm-www/pull/1629) -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. +- Multi document values files (https://github.com/helm/helm/pull/13655) -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. +- Allow signing multiple charts with single passphrase from stdin + (https://github.com/helm/helm/pull/30718) -**Happy path/common use cases** +- 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 Repository + (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 +implemented 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 +- 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 -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. +If the docs do not suffice, there are a couple places where an escalation path +is documented for users that need more help: -**Clear escalation path to get 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. -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. +- 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 API reference is here: https://pkg.go.dev/helm.sh/helm/v4 -**Content accuracy** +##### 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 +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** +##### 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). +There is Getting Started section on the site homepage. It includes Helm +download commands and a link to Artifact Hub where you can find Helm charts. It +links users to the docs for more information (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. +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, 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. +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 scan to +the docs to quickly learn the most common use cases for Helm, 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 +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** +##### 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 +The installation steps for Helm are really just single commands (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. +These install docs include code blocks that have a "copy" button which allows +them to be easily copy-pasted. #### Content maintainability & site mechanics -**Search** +##### Search The documentation is searchable (it uses Algolia DocSearch). -**Localization/i18n** +##### 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: -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. +- Helm.sh releases a new version of the docs with each major release -**Versioning** +- 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) -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 +- Version labels on the site are updated to use the latest minor/patch version #### Content creation processes -**Contribution process for documentation** +##### 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) +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. +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** +##### 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. +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. +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** +##### Docs PR review/approval -Maintainers of the helm-www repo and core project maintainers can review and approve docs PRs. +Maintainers of the helm-www repo and core project maintainers can review and +approve docs PRs. -**Website owners** +##### 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. +Maintainers are clearly listed in the OWNERS file +https://github.com/helm/helm-www/blob/main/OWNERS. Maintainers 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. +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 +The docs do occasionally use language like "simple", "easy", etc. Example: +https://helm.sh/docs/topics/registries/#migrating-from-chart-repos ### Recommendations #### Information architecture -It will be helpful to find greater specificity in the naming strategy for categories. With the current naming of the sections in the sidebar, it's not clear to docs users or contributors how the pages are grouped, and what types of info should go where. Many sections are named by content type (how-to, topics, faqs, best practices). This is fine, but can be challenging to maintain and find content when it's not clear what qualifies as each content type (for example, Topics has become a large catch-all category). By using more specific categories that align with a given product area or use case, it'll be more obvious where info can be found. +It will be helpful to find greater specificity in the naming strategy for +categories. With the current naming of the sections in the sidebar, it's not +clear to docs users or contributors how the pages are grouped, and what types +of info should go where. Many sections are named by content type (how-to, +topics, FAQs, best practices). This is fine, but can be challenging to maintain +and find content when it's not clear what qualifies as each content type (for +example, Topics has become a large catch-all category). By using more specific +categories that align with a given product area or use case, it'll be more +obvious where info can be found. -Additionally, content throughout should be reviewed to see where there is redundant content that can be condensed. For example, lots of the pages in Topics, FAQs, Introduction, Best Practices feels out-of-date or redundant with other pages +Additionally, content throughout should be reviewed to see where there is +redundant content that can be condensed. For example, lots of the pages in +Topics, FAQs, Introduction, Best Practices feels out-of-date or redundant with +other pages. -Finally, procedures should be converted to step-by-step instructions for better readability. +Finally, procedures should be converted to step-by-step instructions for better +readability. #### 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 +The site could use a more clearly 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. +Search, localization, 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/. +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, [CONTRIBUTING](https://github.com/paigecalvert/helm-www/blob/main/CONTRIBUTING.md), and the Community section, which makes it a bit harder to find, and harder to tell when it's out of date. +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, +[CONTRIBUTING](https://github.com/paigecalvert/helm-www/blob/main/CONTRIBUTING.md), +and the Community section, which makes it a bit harder to find, and harder 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. +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 Review the docs for terms like "simply" and "easy" and remove them. -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. +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 Helm is a **graduated** project of CNCF. This means that the project should have [_very high_][criteria] standards for documentation. -| Criterion | [Rating (1-5)] | -| ----------------------------------------- | -------------- | -| Communication methods documented | 3 - meets standards | +| 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 | +| "New contributor" getting started content | 3 - meets standards | +| Project governance documentation | 3 - meets standards | ### Comments @@ -310,77 +477,102 @@ Contributor Documentation rubric. #### Communication methods documented -**Slack and dev meetings** +##### 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. +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 stand-ups (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** +##### 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 +Users can find direct links to the Helm GitHub organization/repositories in a +couple ways: -**Mailing lists** - -Mailing lists are documented here: https://helm.sh/community/communication/#mailing-lists +- 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. +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 triage 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. +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. +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** +##### 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. +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** +##### Docs for first-time contributors + +Helm.sh has the following content that does a good job of providing info 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 +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/ +Is Project governance clearly is documented here: +https://helm.sh/community/governance/ ### Recommendations #### 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. +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. +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 | +| 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 | 4 - meets or exceeds standards | | Branding and design | 4 - meets or exceeds 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 | +| 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 @@ -389,15 +581,24 @@ and documentation infrastructure rubric. #### 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. +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. +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.) +[maturity level][maturity-level], either incubating or graduated. (These are +the only two levels for which a tech docs analysis can be requested.) @@ -417,71 +618,104 @@ only two levels for which a tech docs analysis can be requested.) #### Usability, accessibility and devices -**Usability / mobile experience** +##### 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) +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** +##### 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. +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. +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. +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 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 +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 -Analytics is not set up for the site. +Analytics is not set up for the site. -**SEO, Indexing, and Search** +##### 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). +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** +##### Account custodians -The current custodian(s) of the following Algolia account is not specifically documented, but the repo does have an OWNERS file. +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** +##### 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. +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** +##### Website maintainers -There is no indication that the project is actively cultivating website maintainers from the community. +There is no indication that the project is actively cultivating website +maintainers from the community. -**Build times** +##### 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. +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. +The website is accessible via HTTPS and requests using HTTP are properly +redirected to the HTTPS URLs. ### 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 +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. +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. +Consider troubleshooting the existing script to see why it inconsistently +reduces build times. #### References and notes @@ -498,8 +732,7 @@ The numeric rating values used in this document are as follows [criteria]: ../criteria.md [implementation]: ./helm-implementation.md [issues list]: ./helm-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 \ No newline at end of file +[website guidelines]: ../../website-guidelines-checklist.md diff --git a/analyses/0016-helm/helm-implementation.md b/analyses/0016-helm/helm-implementation.md index f8d4dab..99cda79 100644 --- a/analyses/0016-helm/helm-implementation.md +++ b/analyses/0016-helm/helm-implementation.md @@ -1,14 +1,15 @@ --- title: Implementing Helm Doc Improvements tags: [Helm] +cSpell:ignore: kstatus unreviewed --- ## Introduction -This document provides actionable suggestions for improving the Helm -technical documentation. +This document provides actionable suggestions for improving the Helm technical +documentation. For an analysis and general discussion of recommendations on Helm technical documentation, see [analysis.md](helm-analysis.md). @@ -28,136 +29,216 @@ 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. - ## Reorganize the main docs 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. +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. + +The overall organization could be much improved by following a more consistent +pattern: -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): +- At the highest level, group content by product area (for example, some product + areas might be plugins, charts, sdk) + +- Within each product area, add concepts and tasks for the different user + personas/use cases (chart users, developers, and distributors) + +- Reference material like CLI docs can be at 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_) + - 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_) - [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) + - Kubernetes Compatibility + - [Supported Kubernetes Distributions](https://helm.sh/docs/topics/kubernetes_distros) + - [Supported Kubernetes Versions](from + https://helm.sh/docs/topics/version_skew) - [Glossary](https://helm.sh/docs/glossary/) -- Install and Use Charts - - [Using Helm](https://helm.sh/docs/intro/using_helm) - - [Cheat Sheet](https://helm.sh/docs/intro/CheatSheet) - - 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](https://helm.sh/docs/topics/permissions_sql_storage_backend) - - [Helm Provenance and Integrity](https://helm.sh/docs/topics/provenance) - - [Role-based Access Control](https://helm.sh/docs/topics/rbac) -- Develop 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/)] - - [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] -- 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 +- Charts + - Overview (main overview of Helm charts) + - Installing Charts (topics for the chart user persona) + - [Using Helm](https://helm.sh/docs/intro/using_helm) + - [Cheat Sheet](https://helm.sh/docs/intro/CheatSheet) + - 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) + - [Helm Provenance and Integrity](https://helm.sh/docs/topics/provenance) + - [Role-based Access Control](https://helm.sh/docs/topics/rbac) + - Developing 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/)] + - [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] + - Distributing Charts + - [info for chart distributors] +- Plugins - [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] +- Storage + - Overview (overview of storage) + - Packaging + - [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) + - Release Data + - Configure Storage Backends (from + https://helm.sh/docs/topics/advanced#storage-backends) + - [Permissions management for SQL storage backend](https://helm.sh/docs/topics/permissions_sql_storage_backend) - [Helm Commands](https://helm.sh/docs/helm/) - [Go SDK](https://helm.sh/docs/sdk/) -- Policies - - [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 a high-level 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. +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 -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 +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)? +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. +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 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) +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 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 -This warning was added to several pages in the Helm 4 docs to indicate that they've not yet been updated: +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." +"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. +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: +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) +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. +The Helm docs tend not to use step-by-step instructions for tasks and +procedures. This is not ideal because it can cause +conceptual/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. +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 procedure that can be followed in order. ## Improve docs contribution processes ### 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. +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. +This has led to several locales which are minimally translated and are lacking a +plan or commitment 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 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. +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 -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. +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 \ No newline at end of file +[rfc-keywords]: https://www.rfc-editor.org/rfc/rfc2119 From 78740435f19be2d10f2b93c3a9ff7d9234e9df47 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Mon, 8 Dec 2025 15:19:54 -0700 Subject: [PATCH 4/4] remove unedited issues list file Signed-off-by: Paige Calvert --- analyses/0016-helm/helm-issues-list.md | 52 -------------------------- 1 file changed, 52 deletions(-) delete mode 100644 analyses/0016-helm/helm-issues-list.md diff --git a/analyses/0016-helm/helm-issues-list.md b/analyses/0016-helm/helm-issues-list.md deleted file mode 100644 index 89c251c..0000000 --- a/analyses/0016-helm/helm-issues-list.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -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.