Restructure Developer Documentation into Diátaxis Framework

[ashmeigh]

We are restructuring the developer documentation into the Diátaxis framework, aiming to organize the developer guide into clearer categories. The documentation should follow the structure used in the Pandas developer docs to improve navigation and maintain consistency for contributors.

Desired Behaviour

The developer guide should be clearly categorized into:

• Tutorials: Practical, beginner-level guides for setting up the environment and making the first contribution.
• How-To Guides: Goal-oriented guides for specific tasks like running tests, debugging, and contributing features.
• Explanations: In-depth content to help developers understand the architecture, coding standards, and design principles.
• Reference: Detailed technical documentation covering APIs, internal libraries, commands, and development tools.

Current Behaviour

Currently, the developer documentation lacks structure, mixing setup guides, contribution information, and technical references, which makes it difficult for contributors to find specific information.

Proposed Plan

1. Audit Developer Documentation

   • Review all .rst files in the developer guide.
   • Classify each file according to the Diátaxis categories (Tutorials, How-To Guides, Explanations, Reference).

2. Restructure Developer-Specific Pages

   • Move files into new directories:
     • /development/tutorials/ for onboarding content.
     • /development/how-to/ for task-based guides.
     • /development/explanations/ for architectural explanations.
     • /development/reference/ for technical references like API docs.

3. Create Missing Content

   • Add new content where needed:
     • Tutorials
     • How-To Guides
     • Explanations
     • Expand references

Expected Outcome

• Better Onboarding: New contributors will have a clear path from environment setup to making their first contribution.
• Task-Focused Documentation: Developers will quickly find how-to guides for specific tasks, reducing confusion.
• Maintainable Structure: Easier to maintain and expand the developer guide in the future.

Tasks

• [ ] Audit Documentation: Review and categorize existing .rst files.
• [ ] Restructure Files: Move .rst files to appropriate categories (Tutorials, How-To Guides, Explanations, References).
• [ ] Create Missing Content: Add tutorials, how-to guides, explanations, and references where gaps exist.
• [ ] Update Navigation: Ensure the TOC and sidebar reflect the new structure and add cross-linking between sections.