[task] Audit and categorize existing documentation using Diátaxis framework #1471

Objective

Perform a comprehensive audit of all existing documentation pages and categorize each one according to the Diátaxis framework (Tutorials, How-To Guides, Reference, Explanation).

Context

This is the foundational step for reorganizing the documentation. Before restructuring, we need a clear map of what content exists and where it should live in the new structure. Part of issue #1433.

Approach

1. Create a spreadsheet or markdown table listing all documentation files in docs/src/content/docs/
2. For each file, determine its primary purpose:
   • Tutorial: Learning-oriented, step-by-step guide for beginners
   • How-To: Task-oriented, solving specific problems
   • Reference: Information-oriented, technical specifications
   • Explanation: Understanding-oriented, conceptual clarity
3. Identify content that mixes multiple types (needs splitting)
4. Note gaps where content is missing

Files to Analyze

• All files in docs/src/content/docs/start-here/
• All files in docs/src/content/docs/guides/
• All files in docs/src/content/docs/reference/
• All files in docs/src/content/docs/samples/
• All files in docs/src/content/docs/tools/

Expected Output

Create a markdown file docs/DIATAXIS_AUDIT.md with:

# Documentation Audit - Diátaxis Categorization

## Current Structure Analysis

### start-here/
- `index.mdx` - Category: [Tutorial/How-To/Reference/Explanation] - Action: [Keep/Move/Split]
- ...

### guides/
- `chatops.md` - Category: How-To - Action: Keep in how-to section
- ...

## Gaps Identified
- Missing: "Your First Workflow" tutorial
- Missing: "How Agentic Workflows Work" explanation
- ...

## Content to Split
- `frontmatter.md` - Contains both Reference and Tutorial content
- ...

Acceptance Criteria

• All existing documentation files are listed
• Each file has a Diátaxis category assigned
• Mixed-content files are identified for splitting
• Documentation gaps are noted
• Audit file is committed to repository
  Related to Simplify docs scaffolding #1433

AI generated by Plan Command