Documentation/Toolkit

The documentation toolkit is a set of processes and templates that you can use to create, maintain, and improve Wikimedia technical documentation.

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 common document types

How-to or basic user guide

Write a how-to guide that describes the steps to use a technology or to solve a real-world problem. Ensure that headings are task-oriented and examples are tested for accuracy.

Tutorial

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

Introduction or overview

Write a conceptual doc that helps users understand how a product or technology works, or explains key concepts users should understand about a topic.

API documentation

Create documentation for REST APIs.

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.

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

Questions and feedback

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