[task] Reorganize documentation sidebar to follow Diátaxis framework #1450

Objective

Restructure the documentation sidebar in docs/astro.config.mjs to follow the Diátaxis framework, organizing content into four clear quadrants: Tutorials, How-To Guides, Reference, and Explanation.

Context

The scout research report (#1433) identified that the current documentation structure mixes tutorials, task-oriented guides, and reference material. Adopting the Diátaxis framework will make it easier for users to discover the resources they need when they need them. This approach has been successfully used by Cloudflare, Gatsby, and Replit.

Approach

1. Update docs/astro.config.mjs sidebar configuration to create four main sections:

   • 🎓 Tutorials (Learning-oriented)
   • 📋 How-To Guides (Task-oriented)
   • 📖 Reference (Information-oriented)
   • 💡 Explanation (Understanding-oriented)

2. Map existing content to appropriate quadrants:

   • Tutorials: Create new directory for step-by-step learning paths
   • How-To Guides: Move task-oriented content from current "Guides"
   • Reference: Keep current "reference" directory with better organization
   • Explanation: Create new directory for conceptual explanations

3. Improve information scent by using task-oriented labels instead of generic ones

Files to Modify

• Update: docs/astro.config.mjs - Restructure sidebar configuration
• Create: docs/src/content/docs/tutorials/ directory
• Create: docs/src/content/docs/how-to/ directory
• Create: docs/src/content/docs/explanation/ directory
• Update: Content organization across existing directories

Acceptance Criteria

• Sidebar uses Diátaxis four-quadrant structure
• All existing documentation pages are categorized into appropriate quadrants
• Navigation labels are task-oriented and descriptive
• Build completes successfully without broken links
• Documentation site renders correctly with new structure

Related to

Issue #1433
Related to #1433

AI generated by Plan Command