User:SRodlund (WMF)/Document review checklist staging/short

From mediawiki.org

Document review[edit]

Maintainer outreach[edit]

Before you begin reviewing the document, you should learn about the recent activity and who may be an active maintainer of the page. These are people who may be able to help guide content updates, review your changes, or make relevant changes in the future.


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 you need to discuss potential changes with the maintainer(s)?

  • ...

Initial grade level check[edit]

Begin your review with a general grade level check to see find out the readability of the page. Strive for a grade level of 8 or lower — though it is important to note that some specialized terms like "Wikimedia" may inflate grade level scores.

A test using Expresso will help you evaluate the grade level as well as hightlight areas where you can improve readability. You can use this tool throughout your review process to help guage how the readability of the document has improved.

Content review[edit]

The content review is key to understanding who the page is for and what it is about. During the content review, you evaluate the document to determine if the content is appropriate and provide suggestions to make the content more useful and focused on the audience.

Start the content review by answering the following questions, then follow the content review checklists for all documents, as well as the checklist for the specific content type you are are working with.

What is the content type of this page?

  • ...

What concept or topic is this page trying to explain?

  • ...

Who is the main audience(s) for this page?

  • ...

Does any information need to be added, removed, clarified or updated to make the page more accurate and useful to its intended audience?

  • ...

Content checklist for all pages[edit]

The following checklist will help you to identify, add, and improve content related elements that should be present on all documentation pages.

  • {{{2}}} Title and section heading style: Are titles and section headings specific and meaningful? This helps visitors decide whether they would want to use the page. For example: "Accessing Instances on Cloud VPS" is much better than "Instances".
  • {{{2}}} Introduction: Include a short introduction as the first text on the page following the title that includes 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.
  • {{{2}}} 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).
  • {{{2}}} Code samples: Code samples should use template:Codesample and include a filename if appropriate.
  • {{{2}}} Links: Links go to existing, non-obsolete pages. Link text is descriptive and does not include any wiki prefixes. Special:MyLanguage links are used whenever possible.
  • {{{2}}} Status: There are no draft or outdated banners are present.
  • {{{2}}} Feedback and communication: The page explicitly 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.

Content checklist by content type[edit]

The following checklists can help you identify elements that should be present on pages that represent content types.

Content checklist for landing pages[edit]

  • {{{2}}} 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.
  • {{{2}}} 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].
  • {{{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.
  • {{{2}}} Small groups: When linking to other documentation pages, a landing page should organize links into groups of no more than six.[3]
  • {{{2}}} 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.
  • {{{2}}} 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.
  • {{{2}}} 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.

Content checklist for cross-collection landing pages[edit]

  • {{{2}}} 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.
  • {{{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.
  • {{{2}}} Small groups: When linking to other documentation pages, a landing page should organize links into groups of no more than six.[3]
  • {{{2}}} 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.

Content checklist for how-to guides[edit]

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

Content checklist for tutorials[edit]

  • {{{2}}} 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.
  • {{{2}}} Prerequisites: The page should include a "Prerequisites" section that describes the required tools, knowledge, or other prerequisites required to complete the tutorial.
  • {{{2}}} Numbered steps: Section headings should be numbered and represent a clear sequence of steps.
  • {{{2}}} Working examples: Commands and examples should be tested or review for accuracy.

Content checklist for explanations[edit]

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

Content checklist for reference docs[edit]

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

Style review[edit]

A style review should take place only after the content of the page has been reviewed and changes have been finalized. The style review helps to improve readability and keep the page in compliance with the Wikimedia technical documentation style guide.

General formatting[edit]

  • {{{2}}} Title and section headings: These are formatted in title case. Headings should use h2, h3, and h4 styles.
  • {{{2}}} Date format: Either write out the complete date (September 1, 2021) or use YYYY-MM-DD format (2021-09-01).
  • {{{2}}} Code samples: Code samples should use template:Codesample and include a filename if appropriate.
  • {{{2}}} 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.
  • {{{2}}} Status: No draft or outdated banners are present.
  • {{{2}}} Mobile: The page is readable on mobile, with all important information visible.
  • {{{2}}} Accessibility: The page complies with the accessibility guide for developers.

Language[edit]

  • {{{2}}} 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.
  • {{{2}}} Positive language: Avoid using negative sentence constructions. Use nouns as nouns, verbs as verbs. Use the primary meaning of a word. Avoid contractions.
  • {{{2}}} Inclusive language: Use non-gendered language, and avoid the terms listed in the inclusive language guide.

Voice and mood[edit]

  • {{{2}}} Active voice: Use active voice, except when diplomacy calls for passive voice.
  • {{{2}}} Second person point of view: Uses second person ("You" or assumed "You") when addressing your audience. Avoid first person ("I"), unless the page is an FAQ with questions asked from the first person perspective.
  • {{{2}}} Imperative mood: Uses an imperative mood for most documentation focused on goals or process.

Finishing touches[edit]

  • {{{2}}} Grammar and usage The page has been reviewed for any grammar and usage issues.
  • {{{2}}} Grade level check The grade level improved after the document review.
  • {{{2}}} Translation: If translation is available and the content of the page is stable, the page is marked for translation.

Content types[edit]

Content types create structure and consistency across documentation pages.

  • 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.[4]
  • Tutorial: Tutorials are lessons that take the reader by the hand through a series of steps to complete a project. Tutorials are learning oriented.[5]
  • Explanation: Explanations are discussions that clarify and illuminate a particular topic. Explanations are understanding oriented.[6]
  • Reference: References are technical descriptions of a system and how to operate it. Reference documentation is information oriented.[7]

To do[edit]

  • Do we have a resource on how to create strong titles and section headings?
  1. ↑ Manual:Table_of_contents
  2. ↑ Template:Pagelang
  3. ↑ 3.0 3.1 https://www.livescience.com/2493-mind-limit-4.html
  4. ↑ https://diataxis.fr/how-to-guides/
  5. ↑ https://diataxis.fr/tutorials/
  6. ↑ https://diataxis.fr/explanation/
  7. ↑ https://diataxis.fr/reference/
Retrieved from "https://www.mediawiki.org/w/index.php?title=User:SRodlund_(WMF)/Document_review_checklist_staging/short&oldid=5092677"