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

edit

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

Content audit

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

Style review

A review process focused on writing and style

Use templates to create documentation

edit

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

Templates for standard document types

edit
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.
A tutorial provides a learning experience, in which the the learner follows the close guidance of a teacher.
A conceptual overview helps explains a topic through explanation, providing background and context.
API documentation is a form of technical reference, that describes the machinery that a user needs to work with.

Templates for other common document types

edit

Document 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

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

edit

Document 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

edit

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 2: Survey

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

Step 3: Prioritize

Focus and scope your doc improvement work.

Step 4: Assess

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


About this toolkit

edit

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

edit

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