Documentation/Toolkit/Style review


This checklist is a tool to help review a documentation page. It is written in Remarkup for use in a Phabricator task, not in wikitext. For more information about review checklists, see https://www.mediawiki.org/wiki/Documentation/Toolkit.

Page: <Add link to page>

Review the style of the page for compliance with the Wikimedia technical documentation style guide (https://www.mediawiki.org/wiki/Documentation/Style_guide). Using a writing analysis tool (like Expresso: https://www.expresso-app.org/) 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 (https://www.mediawiki.org/wiki/Inclusive_language?).
  • [] 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: Fix any typos or confusing phrases.
  • [] (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.}}