Documentation/Review template

This page is a guide to reviewing Wikimedia technical documentation. Technical writers and developers can use this guide to create and maintain accurate, consistent, and inclusive documentation.

Basic review

Simplified review process:

• Typos: The page has been reviewed for typos.
• Inclusive language: The page uses non-gendered language and avoids the terms listed in the inclusive language guide.
• Working examples: Commands and examples have been tested or reviewed for accuracy.
• Links: Links on the page work.

When doing a basic review, make a note in the task of any structural or content improvements. These improvements can be opened as separate tasks or defined as outreach program projects.

Quickstart: Expand and copy the Basic Review checklist into a Phabricator task
- [] **Typos**: The page has been reviewed for typos. - [] **Inclusive language**: The page uses non-gendered language and avoids the terms listed in the [[inclusive language]] guide. - [] **Working examples**: Commands and examples have been tested or reviewed for accuracy. - [] **Links**: Links on the page work.

Full review

Content types

Content types create structure and consistency across documentation pages. Checklists in the following sections reference the following types:

• Landing page: Landing pages are link hubs that help the reader find information. Landing pages are navigation oriented.
  • Cross-collection landing page: Cross-collection landing pages help readers find information across topics. They are focused on a theme or group of topics.
• How-to guide: How-to guides are directions that take the reader through the steps required to solve a real-world problem. How-to guides are goal oriented.
• Tutorial: Tutorials are lessons that take the reader by the hand through a series of steps to complete a project. Tutorials are learning oriented.
• Explanation: Explanations are discussions that clarify and illuminate a particular topic. Explanations are understanding oriented.
• Reference: References are technical descriptions of a system and how to operate it. Reference documentation is information oriented.

Quickstart: Expand and copy into a Phabricator task (work in progress)

//This task is part of a project to establish a [formal review process](https://www.mediawiki.org/wiki/Documentation/Review_template) and set of standards for Wikimedia technical documentation. For more information, visit the project page on [mediawiki.org](https://www.mediawiki.org/wiki/Developer_Advocacy/Developer_Portal)// ## Page Link: ## Content review **What is the topic of the page?** * ... **Does the page fit into to a defined content type?** * ... **What information is included on the page?** * ... **Who is the audience (or audiences) of the page? Is the content of the page suitable for that audience?** * ... **Are there any duplicate pages or overlapping content that needs to be merged or marked as obsolete?** * ... **How is the page linked to related pages? What categories does the page belong to? Is it part of a clearly defined collection of pages? Check Special:PrefixIndex for subpages.** * ... ### Content checklist - [] **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 much better than "Instances". - [] **Introduction**: For search optimization and page previews, include a short introduction as the first text on the page following the title. This should briefly introduce the content type, purpose of the page, general audience, and topic with the goal of providing enough information to be meaningful in a set of search results. - [] **Table of contents**: MediaWiki automatically creates a table of contents when a page has more than three headings.[1] Use template:TOC to limit the heading levels displayed in the table of contents so that it is meaningful and concise. To save space, a table of contents can be opposite the title (right-aligned in LTR languages). - [] **Section headings**: Section headings use sentence case. Headings should use h2, h3, and h4 styles. - [] **Code samples**: Code samples should use template:Codesample and include a filename if appropriate. - [] **Links**: Links on the page go to existing, non-obsolete pages (unless for historical reasons). Link text is descriptive and does not include any wiki prefixes. Special:MyLanguage links are used whenever possible. - [] **Lists**: Do not use bulleted list items to complete an introductory sentence fragment. - [] **Status**: No draft or outdated banners are present. - [] **Feedback and communication**: The page prompts readers to share feedback or ask a question. It indicates where readers can go to get updates or connect with others, if appropriate. A talk page exists (or redirects to a central talk page) with at least a welcome post. - [] **Translation**: If translation is available and the content of the page is stable, the page is marked for translation. - [] **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](http://wave.webaim.org/) to check for critical issues.) - [] **Date format**: Either write out the complete date (September 1, 2021) or use YYYY-MM-DD format (2021-09-01). //If the page is a cross-collection landing page, add these lines to the checklist, otherwise delete// - [] **Descriptive title**: Because landing pages help organize and contextualize other pages, the title of a landing page should be descriptive enough to make sense when viewed directly from a search engine. - [] **Image**: If possible, include an image relevant to the topic, such as a project logo. The image can be centered or aligned opposite the title (right-aligned in LTR languages) using [[File:Example|{{dir|{{pagelang}}|left|right}}|30x30px]][2]. - [] **Topic overview**: To provide context, a landing page should include a section that introduces the topic or theme of the page. For example, a landing page for Toolforge should include a section that describes what Toolforge is, what is does, and who uses it. This can be under an "About Toolforge" section or, if it makes sense with the layout of the page, in the first section under the title. - [] **Small groups**: When linking to other documentation pages, a landing page should organize links into groups of no more than six.[3] - [] **Link hub layout**: When linking to other documentation pages, present groups of links in a way that is easy to navigate, such as Template:ContentGrid, Template:Colored box, Template:Contribution, Template:Portal list item on Wikitech, or a sidebar. Avoid organizing links with tables or headings. - [] **Maintainer resources**: Landing pages help facilitate the maintenance of a set of documentation. If possible, include ways for people to participate by subscribing to updates, watching pages, joining editathons, etc. Be explicit about which pages to watch to help answer questions and monitor edits. - [] **Navigation between subpages**: A landing page should include a navigation element that allows readers to move between pages within the collection, such as a sidebar, navigation box, or set of tabs. If the collection is organized using subpages, include a prefix search box. //If the page is a landing page, add these lines to the checklist, otherwise delete// - [] **Descriptive title**: Because landing pages help organize and contextualize other pages, the title of a landing page should be descriptive enough to make sense when viewed directly from a search engine. - [] **Image**: If possible, include an image relevant to the topic, such as a project logo. The image can be centered or aligned opposite the title (right-aligned in LTR languages) using `[[File:Example|{{dir|{{pagelang}}|left|right}}|30x30px]]` ([source](https://www.mediawiki.org/wiki/Template:Pagelang)) - [] **Topic overview**: To provide context, a landing page should include a section that introduces the topic or theme of the page. For example, a landing page for Toolforge should include a section that describes what Toolforge is, what is does, and who uses it. This can be under an "About Toolforge" section or, if it makes sense with the layout of the page, in the first section under the title. - [] **Small groups**: When linking to other documentation pages, a landing page should organize links into groups of no more than six. - [] **Link hub layout**: When linking to other documentation pages, present groups of links in a way that is easy to navigate, such as Template:ContentGrid, Template:Colored box, Template:Contribution, Template:Portal list item on Wikitech, or a sidebar. Avoid organizing links with tables or headings. - [] **Maintainer resources**: Landing pages help facilitate the maintenance of a set of documentation. If possible, include ways for people to participate by subscribing to updates, watching pages, joining editathons, etc. Be explicit about which pages to watch to help answer questions and monitor edits. - [] **Navigation between subpages**: A landing page should include a navigation element that allows readers to move between pages within the collection, such as a sidebar, navigation box, or set of tabs. If the collection is organized using subpages, include a prefix search box. ## Recommendations In addition to addressing any outstanding items in the checklist, what are the most impactful changes that can be made to improve the page? If the page is part of a collection, what are the most impactful changes that can be made to improve the collection as a whole? ## Maintainer outreach **Is there anything notable in the recent activity? Check page views, talk page posts, and recent edits.** * ... **Who seems to be active on or knowledgeable about the page?** * ... **Do the recommendations from this review include changes to the page title or other significant content changes and should be discussed with a maintainer?** * ... ## Writing style review Review the style of the page for compliance with the [[Documentation/Style guide|Wikimedia technical documentation style guide]]. Using a writing analysis tool (like [https://www.expresso-app.org/ Expresso]) can help you identify ways to improve readability, sentence length, and other aspects of plain language. - [] **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](https://www.mediawiki.org/wiki/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](https://en.wikipedia.org/wiki/Imperative_mood) for most documentation focused on goals or process. Avoid future tense ("will"). - [] **Typos**: The page has been reviewed for typos. - [] **(Optional) Grade level check**: Use a writing analysis tool (like [Expresso](https://www.expresso-app.org/)) to check the grade level of the page (sometimes called a readability score). Strive to keep documentation under an eighth grade reading level.

Process overview

Option A: make changes as you do review

This process may be better for doc updates that don't require lots of maintainer outreach (for example, if you or someone you work with is the maintainer). In this version of the process, you make changes as you go through the content and style review checklists, instead of writing down your recommended changes and then implementing them later.

1. Check the Documentation Review workboard in Phabricator for a task tracking the review for the specific doc.
2. Assign the task to yourself and change its status "In Progress".
3. Before you start making changes based on your review: add {{DoNotTranslate}}, {{Draft}} or {{Work in progress]} to discourage translation or other major edits while you're changing the doc.
4. Do Content review. Make content changes and update the corresponding checklist in the Phabricator task to indicate what you did.
5. Do Style review: make style changes and update the corresponding checklist in Phabricator.
6. (optional) If the page was previously marked for translation, mark your revised version for translation.
7. Mark the Phabricator task as Resolved.

Option B: make changes all at once after collaborative review

This process may be better for doc updates that require lots of maintainer outreach or collaboration to agree on and finalize the doc changes. In this version of the process, you identify and document all your intended changes (both content and style) before you make them.

1. Check the Documentation Review workboard in Phabricator for a task tracking the review for the specific doc.
2. Assign the task to yourself and change its status "In Progress".
3. Do Content review, adding your comments about necessary improvements in the Phabricator task, but not changing the wiki page (yet).
4. Do Maintainer outreach. Discuss your recommendations for improving the page, and agree on which content you'll change (and how). Maybe the maintainer would like to complete the rest of the process?
5. Before you start making changes based on your review: add {{DoNotTranslate}}, {{Draft}} or {{Work in progress]} to discourage translation or other major edits while you're changing the doc.
6. After the content is updated, do Style review of the revised page. Update the corresponding checklist in the Phabricator task and making your changes in the wiki page.
7. (optional) If the page was previously marked for translation, mark your revised version for translation.
8. Mark the Phabricator task as Resolved!

Content review

What is the topic of the page?

• ...

Does the page fit into to a defined content type?

• ...

What information is included on the page?

• ...

Who is the audience (or audiences) of the page? Is the content of the page suitable for that audience?

• ...

Are there any duplicate pages or overlapping content that needs to be merged or marked as obsolete?

• ...

How is the page linked to related pages? What categories does the page belong to? Is it part of a clearly defined collection of pages? Check Special:PrefixIndex for subpages.

• ...

Checklist for all pages

• 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 much better than "Instances".
• Introduction: For search optimization and page previews, include a short introduction as the first text on the page following the title. This should briefly introduce the content type, purpose of the page, general audience, and topic with the goal of providing enough information to be meaningful in a set of search results.
• Table of contents: MediaWiki automatically creates a table of contents when a page has more than three headings. Use template:TOC to limit the heading levels displayed in the table of contents so that it is meaningful and concise. To save space, a table of contents can be opposite the title (right-aligned in LTR languages).
• Section headings: Section headings use sentence case. Headings should use h2, h3, and h4 styles.
• Code samples: Code samples should use template:Codesample and include a filename if appropriate.
• Links: Links on the page go to existing, non-obsolete pages (unless for historical reasons). Link text is descriptive and does not include any wiki prefixes. Special:MyLanguage links are used whenever possible.
• Lists: Do not use bulleted list items to complete an introductory sentence fragment.
• Status: No draft or outdated banners are present.
• Feedback and communication: The page prompts readers to share feedback or ask a question. It indicates where readers can go to get updates or connect with others, if appropriate. A talk page exists (or redirects to a central talk page) with at least a welcome post.
• Translation: If translation is available and the content of the page is stable, the page is marked for translation.
• 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.)
• Date format: Either write out the complete date (September 1, 2021) or use YYYY-MM-DD format (2021-09-01).
• Broken section links: After making larger changes to the page structure (removing sections), check for broken anchor links ([[pagename#section]]) via Special:WhatLinksHere (See task T293776#7565176)

Checklist for landing pages

• Descriptive title: Because landing pages help organize and contextualize other pages, the title of a landing page should be descriptive enough to make sense when viewed directly from a search engine.
• Image: If possible, include an image relevant to the topic, such as a project logo. The image can be centered or aligned opposite the title (right-aligned in LTR languages) using [[File:Example|{{dir|{{pagelang}}|left|right}}|30x30px]].
• Topic overview: To provide context, a landing page should include a section that introduces the topic or theme of the page. For example, a landing page for Toolforge should include a section that describes what Toolforge is, what is does, and who uses it. This can be under an "About Toolforge" section or, if it makes sense with the layout of the page, in the first section under the title.
• Small groups: When linking to other documentation pages, a landing page should organize links into groups of no more than six.
• Link hub layout: When linking to other documentation pages, present groups of links in a way that is easy to navigate, such as Template:ContentGrid, Template:Colored box, Template:Contribution, Template:Portal list item on Wikitech, or a sidebar. Avoid organizing links with tables or headings.
• Maintainer resources: Landing pages help facilitate the maintenance of a set of documentation. If possible, include ways for people to participate by subscribing to updates, watching pages, joining editathons, etc. Be explicit about which pages to watch to help answer questions and monitor edits.
• Navigation between subpages: A landing page should include a navigation element that allows readers to move between pages within the collection, such as a sidebar, navigation box, or set of tabs. If the collection is organized using subpages, include a prefix search box.

Checklist for cross-collection landing pages

• Descriptive title: Because landing pages help organize and contextualize other pages, the title of a landing page should be descriptive enough to make sense when viewed directly from a search engine.
• Topic overview: To provide context, a landing page should include a section that introduces the topic or theme of the page. For example, a landing page for Toolforge should include a section that describes what Toolforge is, what is does, and who uses it. This can be under an "About Toolforge" section or, if it makes sense with the layout of the page, in the first section under the title.
• Small groups: When linking to other documentation pages, a landing page should organize links into groups of no more than six.
• Link hub layout: When linking to other documentation pages, present groups of links in a way that is easy to navigate, such as Template:ContentGrid, Template:Colored box, Template:Contribution, Template:Portal list item on Wikitech, or a sidebar. Avoid organizing links with tables or headings.

Checklist for how-to guides

• "How to..." title: Title starts with "How to..."
• Introduction: The first section under the title should introduce the topic and audience of the page.
• Section headings: Sections should be organized by task. Headings should use verb phrases where possible.
• Working examples: Commands and examples should be tested or reviewed for accuracy.

Checklist for tutorials

• Introduction: The first section under the title should introduce the topic and audience of the page and provide a clear description of the outcome of the tutorial.
• Prerequisites: The page should include a "Prerequisites" section that describes the required tools, knowledge, or other prerequisites required to complete the tutorial.
• Numbered steps: Section headings should be numbered and represent a clear sequence of steps.
• Working examples: Commands and examples should be tested or reviewed for accuracy.

Checklist for explanations

• "About..." title: Title starts with "About..."
• Context: Explanations are situated in a particular point in the development process. The page should provide context about the time period the explanation describes.

Checklist for reference docs

• Working examples: Commands and examples should be tested or reviewed for accuracy.
• Requirements: Required parameters or other elements are clearly labelled.
• Automated: If possible, reference documentation should be automatically generated.

Recommendations

In addition to addressing any outstanding items in the checklist, what are the most impactful changes that can be made to improve the page? If the page is part of a collection, what are the most impactful changes that can be made to improve the collection as a whole?

• ...

Maintainer outreach

Is there anything notable in the recent activity? Check page views, talk page posts, and recent edits.

• ...

Who seems to be active on or knowledgeable about the page? Who created the page?

• ...

Do the recommendations from this review include changes to the page title or other significant content changes and should be discussed with a maintainer?

• ...

Writing style review

Review the style of the page for compliance with the Wikimedia technical documentation style guide. Using a writing analysis tool (like Expresso) can help you identify ways to improve readability, sentence length, and other aspects of plain language.

• 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: The page has been reviewed for typos.
• (Optional) Grade level check: Use a writing analysis tool (like Expresso) to check the grade level of the page (sometimes called a readability score). Strive to keep documentation under an eighth grade reading level.