Skip to content

Helm Charts Documentation Reorganization Summary

Overview

This document summarizes the reorganization of the Helm Charts documentation section, which was completed on March 25, 2025. The reorganization follows the content organization pattern established in our Content Organization Approach document.

Reorganization Structure

The Helm Charts documentation has been reorganized from a flat structure into a logical hierarchy of subdirectories, each with focused content files. The new structure is as follows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
docs/helm-charts/
├── index.md                # Main overview with redirects
├── inventory.md            # Directory listing 
├── overview/               # Overview subdirectory
│   ├── index.md            # High-level overview
│   ├── inventory.md        # Directory listing
│   └── architecture.md     # Architecture diagrams and explanations
├── scanner-types/          # Scanner types subdirectory
│   ├── index.md            # Introduction to scanner types
│   ├── inventory.md        # Directory listing
│   ├── common-scanner.md   # Common scanner documentation
│   ├── standard-scanner.md # Standard scanner (Kubernetes API)
│   ├── distroless-scanner.md # Distroless scanner (Debug Container)
│   └── sidecar-scanner.md  # Sidecar scanner documentation
├── infrastructure/         # Infrastructure subdirectory
│   ├── index.md            # Infrastructure overview
│   ├── inventory.md        # Directory listing
│   ├── rbac.md             # RBAC configurations
│   ├── service-accounts.md # Service account setup
│   └── namespaces.md       # Namespace configuration
├── usage/                  # Usage and customization subdirectory
│   ├── index.md            # Usage overview
│   ├── inventory.md        # Directory listing
│   ├── customization.md    # Customization guide
│   ├── configuration.md    # Configuration reference
│   └── values.md           # Values file documentation
├── security/               # Security subdirectory
│   ├── index.md            # Security overview
│   ├── inventory.md        # Directory listing
│   ├── best-practices.md   # Security best practices
│   ├── rbac-hardening.md   # RBAC hardening guide
│   └── risk-assessment.md  # Risk assessment by chart
└── operations/             # Operations subdirectory
    ├── index.md            # Operations overview
    ├── inventory.md        # Directory listing
    ├── troubleshooting.md  # Troubleshooting guide
    ├── performance.md      # Performance optimization
    └── maintenance.md      # Maintenance procedures

Content Transformation

The content from the original files was extracted and distributed into focused files within the new structure. Key transformations include:

  1. overview.md → Split into overview/index.md and overview/architecture.md
  2. architecture.md → Moved to overview/architecture.md with component details extracted to scanner-types/* files
  3. scanner-infrastructure.md → Split across infrastructure/* files
  4. common-scanner.md, standard-scanner.md, distroless-scanner.md, sidecar-scanner.md → Moved to scanner-types/* with additional content extracted to usage/configuration.md
  5. customization.md → Moved to usage/customization.md with configuration details extracted to usage/configuration.md
  6. security.md → Split across security/* files
  7. troubleshooting.md → Moved to operations/troubleshooting.md with additional performance and maintenance content extracted to operations/performance.md and operations/maintenance.md

The navigation in mkdocs.yml was updated to reflect the new structure, with logical grouping of related topics:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
- Helm Charts:
  - Introduction: helm-charts/index.md
  - Directory Contents: helm-charts/inventory.md
  - Overview:
    - Introduction: helm-charts/overview/index.md
    - Directory Contents: helm-charts/overview/inventory.md
    - Architecture: helm-charts/overview/architecture.md
  - Scanner Types:
    - Introduction: helm-charts/scanner-types/index.md
    - Directory Contents: helm-charts/scanner-types/inventory.md
    - Common Scanner: helm-charts/scanner-types/common-scanner.md
    - Kubernetes API Scanner: helm-charts/scanner-types/standard-scanner.md
    - Debug Container Scanner: helm-charts/scanner-types/distroless-scanner.md
    - Sidecar Container Scanner: helm-charts/scanner-types/sidecar-scanner.md
  - Infrastructure:
    - Overview: helm-charts/infrastructure/index.md
    - Directory Contents: helm-charts/infrastructure/inventory.md
    - RBAC Configuration: helm-charts/infrastructure/rbac.md
    - Service Accounts: helm-charts/infrastructure/service-accounts.md
    - Namespaces: helm-charts/infrastructure/namespaces.md
  - Usage & Customization:
    - Overview: helm-charts/usage/index.md
    - Directory Contents: helm-charts/usage/inventory.md
    - Customization Guide: helm-charts/usage/customization.md
    - Configuration Reference: helm-charts/usage/configuration.md
    - Values Files: helm-charts/usage/values.md
  - Security:
    - Overview: helm-charts/security/index.md
    - Directory Contents: helm-charts/security/inventory.md
    - Best Practices: helm-charts/security/best-practices.md
    - RBAC Hardening: helm-charts/security/rbac-hardening.md
    - Risk Assessment: helm-charts/security/risk-assessment.md
  - Operations:
    - Overview: helm-charts/operations/index.md
    - Directory Contents: helm-charts/operations/inventory.md
    - Troubleshooting: helm-charts/operations/troubleshooting.md
    - Performance: helm-charts/operations/performance.md
    - Maintenance: helm-charts/operations/maintenance.md

Benefits of Reorganization

The Helm Charts documentation reorganization provides several benefits:

  1. Improved Readability: Smaller, focused files are easier to read and understand
  2. Enhanced Navigation: Logical hierarchy makes information easier to find
  3. Topic Separation: Clear separation of concerns between different aspects of Helm chart documentation
  4. Consistent Structure: Follows the same pattern as other reorganized sections
  5. Maintainability: Smaller files are easier to update and maintain
  6. Comprehensive Coverage: New structure ensures all aspects of Helm charts are documented

Next Steps

With the completion of the Helm Charts reorganization, we can now focus on:

  1. Reorganizing the Configuration section
  2. Reorganizing the Architecture section
  3. Reorganizing the Integration section
  4. Continuing the Phase 4 (review and refinement) of documentation refactoring