Documentation Framework
The EBRAINS Handbook uses the Diátaxis framework to structure its documentation. Diátaxis organizes content into four distinct types, each serving a different purpose.
The Four Pillars
TutorialsLearning-oriented guides that teach through hands-on practice. For newcomers learning by doing with step-by-step instructions and complete examples.
How-To GuidesTask-oriented guides for solving specific problems. Focuses on practical steps to achieve a goal for users who know what they want to accomplish.
ExplanationsUnderstanding-oriented content that explores concepts and decisions. Discusses principles, trade-offs, and context for users who need to understand the 'why'.
ReferenceInformation-oriented material for looking up technical details. Organized for quick lookup of precise, comprehensive information.
Why We Use Diátaxis
Documentation that mixes tutorials, guides, explanations, and reference in the same place becomes difficult to navigate and use. Diátaxis helps us:
- Improve findability: Users know where to look based on their needs
- Serve different audiences: Beginners get tutorials, experienced users get how-tos, everyone finds what they need
- Guide contributors: Clear structure for where and how to document new features
- Maintain quality: Each content type has clear characteristics and standards
Contributing Documentation
When adding content, identify which pillar fits your purpose:
- Teaching someone new? Write a Tutorial
- Solving a specific task? Write a How-To Guide
- Explaining concepts or decisions? Write an Explanation
- Documenting technical details? Write Reference material
One topic may span multiple pillars. For example, Forms Builder has tutorials for learning, how-to guides for specific tasks, explanations of validation principles, and API reference documentation.
Learn more at diataxis.fr or join #handbook to discuss documentation questions.