We propose transitioning Mantid Imaging's documentation to the Diataxis framework, supplemented by Docusaurus as the platform for content management. The Diataxis framework divides documentation into four purpose-driven categories, ensuring users efficiently find the information they need tailored to their specific context.
Categories in Diataxis Framework:
Tutorials: Hands-on guides that help beginners achieve specific goals through a learning-by-doing approach.
How-to Guides: Practical, task-focused instructions designed for users looking to solve specific problems.
Reference: Detailed descriptions providing deep technical information about the software's functionality.
Explanation: In-depth discussions that clarify and contextualize the software principles and concepts.
Benefits of Adopting the Diataxis Framework:
User-Centric Organization: By categorizing content into Tutorials, How-to Guides, Reference, and Explanations, users can more easily navigate the documentation based on their immediate needs.
Enhanced Clarity and Accessibility: This structured approach helps in reducing information overload. Users are not bombarded with details irrelevant to their current task.
Improved Learning Curve: New users find it easier to get started with the software using clear, goal-oriented tutorials, while advanced users can directly access technical details or contextual explanations as needed.
Efficient Maintenance and Scalability: Standardizing the types of content makes the documentation easier to update and expand as the software evolves. It ensures consistency across all documents.
Action Items:
Review Current Documentation:
Assess and categorize existing content into the Diataxis framework.
Categorize Existing Content:
Utilize Docusaurus to reorganize and present the documentation according to the new framework.
Create Missing Content:
Identify and develop content to fill gaps in each of the four categories.
Update Documentation Structure:
Implement changes on the documentation site to reflect the new structure, ensuring ease of navigation.
Consistent Referencing:
Standardize reference formats across all types of documentation.
Issue Description
We propose transitioning Mantid Imaging's documentation to the Diataxis framework, supplemented by Docusaurus as the platform for content management. The Diataxis framework divides documentation into four purpose-driven categories, ensuring users efficiently find the information they need tailored to their specific context.
Categories in Diataxis Framework:
Benefits of Adopting the Diataxis Framework:
Action Items:
Resources: