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
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.