Documentation/Style guide/Style checklist

Style checklist for documentation based on the Wikimedia technical documentation style guide


 * 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.
 * Grade level: A test using Expresso shows a grade level of 8 or lower. Note that specialized terms like "Wikimedia" may inflate grade level scores.
 * Positive language: Avoid using negative sentence constructions. Use nouns as nouns, verbs as verbs. Use the primary meaning of a word. Avoid contractions.
 * Active voice: Use active voice, except when diplomacy calls for passive voice.
 * Inclusive language: Use non-gendered language, and avoid the terms listed in the inclusive language guide.
 * Accessibility: The page complies with the accessibility guide for developers.
 * 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.
 * Imperative mood: Uses an imperative mood for most documentation focused on goals or process.
 * Date format: Either write out the complete date (September 1, 2021) or use YYYY-MM-DD format (2021-09-01).
 * 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.
 * Section headings: Section headings use sentence case. Headings should use h2, h3, and h4 styles.
 * 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).
 * 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.