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.

Review template
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 that need to be merged or marked as obsolete?



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



'''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?



What are the most impactful changes that can be made to improve the collection?



Content types
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.
 * 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.

Landing page
Landing pages are link hubs that help the reader find information. This includes landing pages for a collection as well as cross-collection landing pages. Landing pages are navigation oriented.

Checklist

 * 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.
 * 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.

Cross-collection landing page
Cross-collection landing pages help readers find information across topics. They are focused on a theme or group of topics.

Checklist

 * 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.
 * Managed choice: 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.

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.

Checklist

 * "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 review for accuracy.

Tutorial
Tutorials are lessons that take the reader by the hand through a series of steps to complete a project. Tutorials are learning oriented.

Checklist

 * 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 review for accuracy.

Explanation
Explanations are discussions that clarify and illuminate a particular topic. Explanations are understanding oriented.

Checklist

 * "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.

Reference
References are technical descriptions of a system and how to operate it. Reference documentation is information oriented.

Checklist

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