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

Use checklists to review key quality indicators like content structure, accuracy, writing style, clarity, and accessibility.

Quick review

A short review process including the most important standards for good documentation

• Start a review on Phabricator
• See the checklist

Content audit

A complete, detailed process to help you improve documentation content and organization

• Start a review on Phabricator
• See the checklist

Style review

A review process focused on writing and style

• Start a review on Phabricator
• See the checklist
• See the style guide

Use templates to create documentation

Use doc outlines to create quality documentation for different content types.

Templates for standard document types

How-to guide

A how-to guide helps an already-competent user reach a real-world goal, such as performing a technical task correctly or working through a problem.

Tutorial

A tutorial provides a learning experience, in which the the learner follows the close guidance of a teacher.

Introduction or overview

A conceptual overview helps explains a topic through explanation, providing background and context.

API documentation

API documentation is a form of technical reference, that describes the machinery that a user needs to work with.

• API documentation guide
• API documentation Template

Templates for other common document types

Library documentation

Document how users should get started with or contribute to a library.

Tool documentation

Document tools with the essential content for users and developers.

• Tool documentation guide
• Tool documentation template

Templates for navigation pages

Landing page

Create a landing page that helps users navigate information about a specific product or technology. Provide basic context, organize links into meaningful groups, and include a communication process.

Portal page

Create a landing page that helps users navigate a complex topic space that spans multiple products and technologies. Provide a basic orientation to the topic, and contextualized links to more specific landing pages.

Templates for specialized content

Decision records

Document the reasoning behind decisions.

Self-study guides

Self-study guides help readers learn a subject that's already covered in other documentation.

Workshop handbooks

Workshop handbooks instruct readers on how to conduct a workshop on a given subject.

Improve a collection of docs

Follow this process to audit a collection of docs and identify key areas for improvement.

Step 1: Determine documentation goals

Define your audience and scope your topic.

• Step 1

Step 2: Survey

Understand the documentation landscape and how your topic relates to others.

• Step 2

Step 3: Prioritize

Focus and scope your doc improvement work.

• Step 3

Step 4: Assess

Determine the improvements necessary to address information overload, gaps, and doc maintenance challenges.

• Step 4

About this toolkit

The 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

To ask a question or share feedback, leave a comment on the discussion page.