Divio Documentation System Overview
The Divio Documentation System presents a structured framework divided into four key quadrants: Tutorials, How-to Guides, Explanation, and Reference. Each serves a unique purpose in the documentation ecosystem, ensuring users find the information they need, whether they are learning a new system, trying to solve a problem, seeking deeper understanding, or searching for specific details.
Tutorials
- Purpose: To onboard new users by teaching them through practical steps and hands-on learning.
- Best Practices: Begin with the basics, gradually increase complexity, provide clear and actionable instructions, and include expected outcomes to guide users through the learning process effectively.
- Reference: Writing Tutorials
How-To's
- Purpose: To help users solve specific problems or accomplish tasks by offering concise, step-by-step instructions.
- Best Practices: Each guide should focus on a single task, avoiding theoretical discussions to maintain practicality and effectiveness in standardizing solutions for common issues or frequent tasks.
- Reference: Writing How To's
Guides (Explanation)
- Purpose: To offer understanding and context, explaining the "why" behind tasks and methodologies.
- Best Practices: Use clear and accessible language to explain complex ideas, and link to relevant guides for deeper insights, supporting informed decision-making and adoption of new technologies or methodologies.
- Reference: Writing Guides
Reference
- Purpose: To serve as an encyclopedic resource, providing detailed and organized information that is easy to search.
- Best Practices: Keep information up-to-date, organized, and detailed, with examples for clarity, making it a go-to resource for technical specifics like API documentation or data models.
- Reference: Writing References