Documentation/Toolkit
The documentation toolkit is a set of processes and templates that you can use to create, maintain, and improve Wikimedia technical documentation. The toolkit adopts the Diátaxis approach for documentation types. For more details, about the Diátaxis system and how it is used in this toolkit, see the About section below.
Improve individual docs
editUse checklists to review key quality indicators like content structure, accuracy, writing style, clarity, and accessibility.
A short review process including the most important standards for good documentation
A complete, detailed process to help you improve documentation content and organization
A review process focused on writing and style
Use templates to create documentation
editUse doc outlines to create quality documentation for different content types.
Templates for standard document types
editTemplates for other common document types
editDocument how users should get started with or contribute to a library.
Document tools with the essential content for users and developers.
Templates for navigation pages
editTemplates for specialized content
editDocument the reasoning behind decisions.
Self-study guides help readers learn a subject that's already covered in other documentation.
Workshop handbooks instruct readers on how to conduct a workshop on a given subject.
Improve a collection of docs
editFollow this process to audit a collection of docs and identify key areas for improvement.
Define your audience and scope your topic.
Understand the documentation landscape and how your topic relates to others.
Focus and scope your doc improvement work.
Determine the improvements necessary to address information overload, gaps, and doc maintenance challenges.
About this toolkit
editThe toolkit adopts the Diátaxis approach for documentation types. Diátaxis is a system that defines four key kinds of documentation in particular ways. These are: tutorials, how-to guides, reference material and explanation, each corresponding to a different user need. Once you have a clear picture of what need the documentation is trying to meet, then Diátaxis will help write in the appropriate way:
- someone who needs to learn is served by a tutorial
- someone needs to accomplish a task to or to solve a problem needs a how-to guide
- someone who needs information needs reference material
- someone who needs to understand requires explanation
Templates are provided below corresponding to these types.
Diátaxis doesn't mean that all documentation must be divided into four categories! Rather, it means that when you are writing documentation you should recognise your purpose at that moment, write accordingly. Specifically, if you are writing to:
- provide someone with a learning experience in which they do something practical, to help them acquire a skill, you should write in tutorial mode
- guide someone through a practical situation, so that they can correctly apply their skill and judgement to actual work, that is how-to documentation
- describing facts (a kind of theoretical knowledge) that they can understand and apply to their work, you should be in reference mode
- provide context and background (also a kind of theoretical knowledge) that helps acquire and build understanding, that is explanation
The key is not to muddle them up, or switch between them.
Questions and feedback
editTo ask a question or share feedback, leave a comment on the discussion page.