Documentation/Toolkit/Content audit

This page provides two review checklists you can use to review technical documentation for outdated information, and improve their accuracy and relevance for technical audiences.

Quick review

• Title content: 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".
• Introduction: Include a short introduction as the first text on the page following the title, before the first heading. This should briefly introduce the purpose of the page, its audience, and topic. Intro sections help readers build a mental model of the content they can expect to find on the page.
• 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.
• 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.
  • If the page documents a specific product or technology: it should contain contact information for an owner, maintainer, or code steward. This could be a team or an individual, or a link to an issue tracker.
• 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.
• Broken section links: If you restructure a page as part of a content audit, check for broken anchor links (`pagename#section`) via Special:WhatLinksHere.

In-depth review

Note: In-depth review of page content may require the input and collaboration of subject matter experts. Without that expertise, it can be difficult to identify missing or inaccurate information. If you're not a subject matter expert in the domain covered by a page, you may need to find a collaborator to complete parts of this review.

• Cover essential information: Use the templates in the Documentation Toolkit to help you identify key pieces of information that different types of pages should cover.
• Provide useful content for technical audiences: code samples and links to code are good basics to start with, when they're applicable and relevant.

• Look for missing information:
  • Before you try to expand the content on a page, check if a different, more popular page already covers the information. Would it be better to consolidate information than to add more content to this page?
  • Read comments on the Talk page to identify missing information. But proceed with caution, since comments may be outdated. If you're not a subject matter expert in the domain this page covers, you may have to get input from a collaborator who has the expertise to identify missing or inaccurate information.

Technical content

Code samples

If the page does not contain any code samples: consider the type of document, its purpose, and audience.

• Navigation pages or overviews should generally not contain code samples. A low technical content score for those types of pages is okay!
• Technical user guides that include development tasks like using a command-line tool, querying a database, or interacting with an API should probably contain code samples.
• Tutorials should probably contain code samples, though this depends on the topic.

If the page does contain code samples, check the following:

• Are the code samples correct, or have they diverged from the code in production?
• Do they use or function with the most recent stable version of the language (for example: Python 3 compatible)?
• Do they follow relevant coding conventions?
• Do they use descriptive class, method, and variable names?
• Do they use proper formatting to distinguish code from other content?

Links to code

If the page does not contain links to code:

• If the page is about a specific technical product, component, or software: can you add a link to the primary source code repository? Use templates for MediaWiki core and Git source. Templates for specific types of projects often include fields for linking to source code. For example: Template:Extension, wikitech:Template:Tool, and meta:Template:Research_project.

If the page does contain links to code:

• Check if the links point to active repositories and valid code files.
• If the link points to a specific line in a file: does the link reference a specific commit, to ensure the link remains valid even if the relevant line number changes as the code in that file evolves over time?
• Follow tips for creating permanent links to files and repositories:
  • Gerrit
  • GitLab