Documentation/Toolkit/Usability review

This page provides two review checklists you can use to review technical documentation for style, formatting, and other usability criteria.

Quick review

Use doc linting tools to help you review the style of the page for compliance with the Wikimedia technical documentation style guide:

Plain language: The language used on the page is clear and concise. It is free of jargon, idioms, and other ambiguous or confusing elements. Sentences are not more than 30 words in length.
Positive language: Avoid using negative sentence constructions.
Inclusive language: Use non-gendered language, and avoid the terms listed in the inclusive language guide.
Active voice: Use active voice, except when diplomacy calls for passive voice.
Second person point of view: Uses second person ("You" or assumed "You") when addressing your audience. Avoid first person ("I", "we", "our"), unless the page is an FAQ with questions asked from the first person perspective.
Imperative mood: Uses an imperative mood for most documentation focused on goals or process. Avoid future tense ("will").
Typos: Fix any typos or confusing phrases.
Date format: Either write out the complete date (September 1, 2021) or use YYYY-MM-DD format (2021-09-01).

In addition to what the linting tool helps you find, also check the following:

Title style: Uses sentence case for titles. The title should be descriptive and specific. This helps visitors decide whether they would want to use the page. For example: "Accessing Instances on Cloud VPS" is more descriptive and specific than "Instances".
Section headings: Section headings use sentence case. Headings use h2, h3, and h4 styles. Ensure the sections are numbered consecutively, not skipping any levels from sections to sub-subsections.
Mobile: The page is readable on mobile, with all important information visible.
Accessibility: The page complies with the accessibility guide for developers. (You can use the WAVE tool to check for critical issues.)

In-depth review

Make docs more succinct

To help you make tech docs shorter, try to find and remove these types of content:

Information that is "nice to know" but not absolutely necessary: Consider the type of document and its intended audience: what is the minimum amount of information the audience needs to get from this page? Use documentation templates to get ideas for what content to include in a given type of document.
Overwhelming lists of links: Check the number of links in the "See Also" or "Additional information" sections, if they are present. Are all the links really useful, or are they linking to duplicate, outdated, or unnecessary information? Try to limit links in these sections to 3-8 of the most relevant and related resources. Remove links to archived or obsolete pages, or put them in a separate section that is clearly labeled "Historical" or "Background information".
Duplicate information in prose and code samples: If the page contains code samples, is any of the information in the code samples duplicated in the text? If so, could one or the other be removed? Check the length of code samples: Do they include non-essential information that makes them longer than necessary? Could you make them more concise or break them into smaller sections?
Duplicate information on related pages: Use Special:WhatLinksHere to find pages that link to your page, and also follow the links your page provides to other pages. On those incoming and outgoing linked pages: look for sections that cover the same content. Then, attempt to determine which page location makes the most sense for the information. Consolidate information about the same topic or process in one place, and replace duplicated information with cross-references or transcluded content instead.

Refine page structure

To align your page structure with best practices, check the following:

Quantity and depth of headings:
- Could any sections benefit from more (or fewer) subheadings? Generally, you should aim for at least one heading per 15 sentences.
- Is the page structure too deep? Generally headings should not go below ==== Heading 4 ==== (or "Subheading 2" in VisualEditor).
Avoid large, undifferentiated sections of text:
- Look for opportunities to use formatting or templates to present different types of information in a way that also provides visual differentiation and breaks up the content on the page.
- If the page is a landing page or navigation-focused page: use layout templates to create meaningful groupings of related links.