Content Organization Approach

This document outlines the approach for organizing documentation content for optimal readability and navigation.

Overview

In addition to our basic directory structure pattern with index.md and inventory.md files, we've identified the need to break down large documentation pages into smaller, more focused subsections. This approach improves readability, makes navigation more intuitive, and allows users to find specific information more quickly.

Content Organization Pattern

For comprehensive documentation sections, we follow this organization pattern:

1. Section Overview Page
2. A high-level introduction to the topic area
3. Summary of key concepts and subtopics
4. Links to detailed subtopic pages

5. Serves as the entry point for the section

6. Dedicated Subdirectory

7. Create a subdirectory named after the section
8. Place all subtopic files in this directory

9. Include index.md and inventory.md in the subdirectory

10. Individual Topic Pages

11. Create separate markdown files for each subtopic
12. Focus each file on a specific aspect of the larger topic
13. Keep files focused and concise (typically under 300 lines)

14. Use consistent naming conventions (e.g., scaling.md, security.md)

15. Redirect Pattern

16. Keep the original section file as a redirect page
17. Include a note about reorganization
18. Provide links to all subtopic pages
19. Ensures backward compatibility with existing links

Navigation Structure

In the MkDocs navigation:

# Example navigation structure
- Section Name:
  - Overview: section/index.md
  - Directory Contents: section/inventory.md
  - Subtopic Group A:
    - First Subtopic: section/subtopic1.md
    - Second Subtopic: section/subtopic2.md
  - Subtopic Group B:
    - Third Subtopic: section/subtopic3.md
    - Fourth Subtopic: section/subtopic4.md

Implementation Examples

We have successfully applied this pattern to the following sections:

1. Deployment Scenarios
2. Created scenarios subdirectory
3. Broke down into individual scenario files (enterprise.md, development.md, etc.)
4. Added comprehensive index.md and inventory.md files

5. Updated navigation with logical grouping

6. Advanced Deployment Topics

7. Created advanced-topics subdirectory
8. Split into focused topic files (scaling.md, security.md, etc.)
9. Created detailed cross-references between related topics

10. Maintained the original file as a redirect

11. Scanning Approaches

12. Created dedicated subdirectories for each approach:
    • kubernetes-api/ - For the Kubernetes API approach
    • debug-container/ - For the Debug Container approach
    • sidecar-container/ - For the Sidecar Container approach
    • helper-scripts/ - For the Helper Scripts documentation
13. Implemented focused topic files for each aspect (implementation, limitations, security, etc.)
14. Created comprehensive index.md and inventory.md files for each approach
15. Updated navigation with logical grouping by approach
16. Improved cross-references between related approaches

When to Apply This Approach

Consider breaking down content into subtopics when:

1. The content exceeds 300 lines in a single file
2. The section covers multiple distinct concepts or approaches
3. Users would likely be interested in specific subsections rather than the entire content
4. The content would benefit from a hierarchical organization
5. Different user personas would be interested in different subsections

Implementation Process

To implement this approach for a section:

1. Analyze Content
2. Review existing content and identify logical divisions
3. Plan the subdirectory and file structure

4. Identify connections between subtopics

5. Create Directory Structure

6. Create a subdirectory named after the section

7. Plan file names that reflect their content

8. Create Content Files

9. Start with index.md for the section overview
10. Create individual files for each subtopic
11. Ensure each file is focused and comprehensive

12. Add cross-references between related subtopics

13. Update Original File

14. Convert the original file to a redirect page
15. Include a note about reorganization

16. List links to all new subtopic pages

17. Update Navigation

18. Update mkdocs.yml to reflect the new structure
19. Group related subtopics under appropriate headings

20. Ensure logical navigation flow

21. Test and Validate

22. Verify all pages are accessible
23. Check for proper rendering
24. Test navigation flow and usability

Sections to Apply This Pattern

Based on our analysis, the following sections should be considered for this reorganization approach:

Section	Current Status	Priority	Notes
Approaches	✅ Completed	High	Split scanning approaches into individual directories with focused files
Security	✅ Completed	High	Created dedicated subdirectories for principles, risk, compliance, threat-model, and recommendations
Helm Charts	✅ Completed	High	Reorganized into overview/, scanner-types/, infrastructure/, usage/, security/, and operations/ subdirectories
Configuration	📅 Planned	Medium	Separate by configuration target
Architecture	📅 Planned	Medium	Split by architectural component
Integration	📅 Planned	Medium	Separate by integration platform

Expected Benefits

Implementing this organization pattern will:

1. Improve Readability: Smaller, focused files are easier to read and understand
2. Enhance Navigation: Logical hierarchy makes information easier to find
3. Facilitate Maintenance: Smaller files are easier to update and maintain
4. Support Collaboration: Multiple contributors can work on different subtopics
5. Reduce Cognitive Load: Users only need to focus on relevant subtopics

Related Documents

• Documentation Structure Reorganization Progress
• Documentation Entry Point Refactoring
• Documentation Review Plan