Merge pull request #399 from paigecalvert/patch-1

HIP Improve the Helm Documentation

Author: scottrigby

hips/README.md

@@ -32,3 +32,4 @@ restricted markdown format and can be found in the
 - [hip-0021: Enhanced logging library for Helm](hip-0021.md)
 - [hip-0022: Wait With kstatus](hip-0022.md)
 - [hip-0023: Utilize Server Side Apply for installs/upgrades](hip-0023.md)
+- [hip:0024: Improve the Helm Documentation](hip-0024.md)

hips/hip-0024.md

@@ -0,0 +1,91 @@
+---
+hip: "0024"
+title: "Improve the Helm Documentation"  
+authors: [ "Paige Calvert <[email protected]>" ]  
+created: "2025-05-07"  
+type: "feature"  
+status: "draft"  
+---
+
+## Abstract
+
+This HIP proposes making a set of improvements to the Helm documentation site (https://helm.sh/docs). The goal of these improvements is to make it easier to use and contribute to the Helm docs, which would ultimately make it easier for users to learn about, use, and contribute to Helm.
+
+This proposal focuses on improvements that can be made to the static site generator, the site's information architecture, and the Helm overview content available in the site.
+
+## Motivation
+
+This proposal identifies the following key areas for improvement in the Helm documentation:
+
+- The functionality of the site is limited and in some cases is broken. For example, top-level pages like https://helm.sh/docs/howto/ are not accessible by clicking on the given heading in the sidebar. As another example, it is difficult for contributors to reorder sidebar content due to the use of weighted page ordering, rather than having a sidebar file where pages can be more easily reordered.
+
+- There is no comprehensive introductory page explaining Helm’s purpose, personas, common use cases, and so on.
+
+-  The Helm docs are currently organized around top-level categories like Introduction, How-To, Topics, Best Practices, and so on. These categories do not reflect the ways that different user personas use Helm (like releasing with Helm, packaging an application with Helm, or installing with Helm). Content also appears to be inconsistently organized under each category. For example, there are only three pages under the How-To section. And, [Chart Development Tips and Tricks](https://helm.sh/docs/howto/charts_tips_and_tricks/) is under How-To, rather than under Best Practices. There are also discrepancies in the description of [How the documentation is organized](https://helm.sh/docs/#how-the-documentation-is-organized) and the top-level categories that actually appear in the live docs site.
+
+## Rationale
+
+The following describes the rationale behind improving each of the key areas listed under Motivation above:
+
+- Modern open-source static site generators (like [Docusaurus](https://docusaurus.io/) or [MkDocs](https://www.mkdocs.org/)) offer easier maintenance, clearer sidebar management, and better support for documentation contributors.
+
+- A lack of clear, complete, and up-to-date Helm overview content leads to confusion for first-time users that want to understand Helm’s goals, features, and common use cases.
+
+- The current information architecture makes it more difficult for users to find the information they are looking for. It also makes it more difficult for contributors to understand how to organize new topics in the sidebar. Redesigning the information architecture would improve discoverability and usability, helping users find relevant content faster.
+
+## Specification
+
+This HIP proposes the following:
+
+1. **Evaluate static site generators and migrate the docs**: Evaluate, select, and migrate the Helm docs to a modern, open-source static site generator (like [Docusaurus](https://docusaurus.io/) or [MkDocs](https://www.mkdocs.org/)) that would improve ease-of-contribution and site functionality.
+1. **Create a Helm overview page**: Add a new page to the introductory section of the docs that describes the Helm project, its goals, core concepts, user personas, and key use cases, clearly addressing the who/what/when/why for Helm.
+1. **Redesign the docs information architecture**: Perform a content audit and design a new information architecture that is more intuitive, reflects common workflows for the different Helm user personas, improves content find-ability, and aligns with tech comm standards.
+
+Each of these items would be presented for review by the Helm community.
+
+These docs improvements could be published alongside the release of Helm 4. Implementations would include:
+- Migrate all the existing docs to the new site.
+   - Create the new sidebar to reorganize the docs.
+- Write the updated Helm overview content.
+- Docs for Helm 4:
+  1. Drafted in a branch initially
+  2. Helm 4 released, merge the Helm 4 docs, and publish the new docs site.
+
+## Backwards compatibility
+
+This change affects only the documentation site and does not impact the Helm CLI, Helm libraries, or chart formats. Legacy URLs will be redirected where necessary to preserve external links and bookmarks.
+
+## Security implications
+
+There are no known security implications from this change, as it would affect only the public documentation and the docs toolchain.
+
+## How to teach this
+
+- Add clear contribution guides and README instructions in the docs repo, including templates and guidelines for docs contributors
+- Promote the new docs structure and toolchain through Helm community channels and other documentation update announcements.
+
+## Reference implementation
+
+No implementation has been made. This proposal recommends evaluating and choosing a new static site generator as part of the implementation process. Additionally, the specific information architecture and overview content improvements will be determined through a content audit and refined with Helm community feedback.
+
+## Rejected ideas
+
+To limit scope, this proposal does not include making any significant changes to the docs content itself (including adding/removing content or making substantial content style improvements). The only exception is adding more complete overview content.
+
+## Open issues
+
+The open issues for this HIP include the specific implementation strategy and timeline for each area for improvement, such as:
+
+- Creation of a roadmap/project plan to track progress  
+- Selection of the static site generator
+- Static site generator migration strategy and timeline
+- The specific information and/or visuals to add to a new overview page
+- Completion of content audit
+- The specific information architecture improvements that should be made, such as the different categories where content should be grouped
+- The strategy and timeline for making information architecture improvements
+
+## References
+
+- [Helm Documentation](https://helm.sh/docs)
+- [Docusaurus](https://docusaurus.io/)
+- [MkDocs](https://www.mkdocs.org/)