Documentation/Tools/Linting/Linter rule reference

This page contains a full reference of linter rules developed as part of task T388109. These rules are based on Documentation/Style guide. Rule implementation is available in the linter-quickstart repository on Wikimedia GitLab.

Wikimedia.AltText

Message: Consider expanding this alt text: [alt text].

How to fix

Set the alt text to "" for a decorative image, or write a longer description in the alt text field for an informative image.

Explanation

This rule detects single-word alt text for an image. Single-word alt text is rarely helpful for users of assistive technologies. Decorative images should have alt text set to an empty value (alt=""). Informative images should have longer alt text with a 1-2 sentence description of the content of the image. For example:

"Overview of the production deployment pipeline, which starts with code and configuration files in a GitLab repository, and ends with deployment of an application on Wikimedia production clusters. The pipeline uses GitLab CI, Kokkuri, Blubber, and Helm to deploy applications to production."
"Participants of the Wikimedia Hackathon 2024".

Don't try to describe every detail depicted in the image; focus on elements necessary for readers to understand the main point of the image.

More information:

https://webaim.org/techniques/alttext/

Wikimedia.Ampersands

Message: Use 'and' instead of '&'.

How to fix

Replace the occurrence of & with an 'and'.

Explanation

This rule detects use of ampersands in regular text. Ampersands are common in programming language syntax, but in formal writing, using "and" is more readable and accessible.

Wikimedia.Annotations

Message: '[FIXME or TODO]' left in text.

How to fix

Make the changes required to remove the occurrence of FIXME or TODO from the documentation.

Explanation

This rule detects FIXME and TODO in text to remind you of any unfinished documentation you might have committed or published.

Wikimedia.CurlyPunctuation

Message: Use neutral quotes ([quote]) instead of curly quotes ([curly quote]).

How to fix

Replace the curly quote with the suggested neutral quote.

Explanation

Code often uses neutral or straight quotation marks. To keep typography and style consistent, use the same quotation marks in the documentation.

Note that word processors, for example Google Docs, often automatically replace neutral punctuation with curly punctuation. Pay attention to this when copying docs from such applications.

Wikimedia.Dates

Message: Consider reformatting '[your date]' to YYYY-MM-DD or similar.

How to fix

Change the format of the date to similar to the one listed. Start with a four-digit year, follow it with month, and then day. You can also reformat the date by using a full word for the month alongside a four-digit year.

Explanation

Short, numerical formats of dates can be ambiguous, and may be interpreted differently in different locales. For example, 22-01-23 can mean 22 January, 2023; or 23 January, 2022. Using four digits for the year makes this easier but can still be confusing. Using the ISO 8601 international standard removes this ambiguity.

More information:

Wikimedia.Ellipses

Message: Avoid '…' outside code samples.

How to fix

Remove the ellipsis from regular text.

Explanation

This rule identifies ellipses used in regular text. Ellipses are useful for building suspense in prose but have little use in technical documentation. It's also typically not necessary to include ellipses when describing user interface elements that contain them. For example, you can refer to a button with a label that reads "More..." with "press the More button".

Wikimedia.FreeOfFrustration

Message: Avoid terms like '[term]' which can be frustrating for readers.

How to fix

Remove or replace the term listed in the message. Rewrite the sentence if necessary.

Explanation

This rule identifies terms that imply an activity should be easy to perform. Since ease or simplicity is subjective and contextual, using terms like this can be frustrating or condescending. Avoid such judgements in technical documentation.

Wikimedia.Gender

Message: Use a gender-neutral word instead of '[term]'.

How to fix

Replace the term in the message with a gender-neutral word, such as "they" or "the user". Consider if the content could instead address the reader directly, as "you".

Explanation

This rule identifies instances of gendered language in your documentation and prompts you to use a gender-neutral term instead. This is to ensure that your documentation is inclusive of all gender identities.

More information:

Wikimedia.HeadingArticles

Message: Avoid using articles at the beginning of a heading.

How to fix

Remove the article from the start of the heading.

Explanation

This rule identifies instances of articles ("the", "a", "an") at the beginning of a heading. These articles provide no informative value and can make headings more difficult to skim, which reduces documentation readability.

Wikimedia.HeadingPunctuation

Message: "Don't use end punctuation in headings."

How to fix

Remove trailing punctuation in the heading.

Explanation

This rule identifies instances of trailing punctuation in headings. Trailing punctuation can be distracting and lower readability if applied inconsistently.

Wikimedia.InclusiveLanguage

Message: "Use any of the following: '[term]' instead of '[term]'."

How to fix

Replace the identified term with the suggested term.

Explanation

This rule identifies uses of terms that reinforce inappropriate stereotypes or harmful language, and suggests replacement terms instead.

In some cases, you might not be able to replace a given term because doing so would make the documentation incorrect or unclear. For example, when explaining how to contribute to a given project, you might have to use the term "master" if that's the main branch used in that project. Such situations are unavoidable; you should use terms that guarantee documentation correctness instead of attempting a workaround that might produce less useful documentation.

Wikimedia.Jargon

Message: Avoid jargon like '[term or phrase]'.

How to fix

Replace the term or phrase with a term or phrase that's easier to understand and doesn't rely on familiarity with terminology used by your team or organization.

Term	Suggestion
in maintenance mode	Be specific about the types of maintenance offered.
sunset	Use literal terms such as undeployed or removed.

Explanation

Jargon terms and phrases can be difficult to understand, for example due to cultural differences or lack of context. It's best to avoid jargon entirely and aim for plain language instead.

More information:

en:Curse_of_knowledge

Wikimedia.Latin

Use '[English term or phrase]' instead of '[Latin term or phrase]'.

How to fix

Replace the Latin term with the suggested English term.

Explanation

This rule identifies common Latin terms and abbreviations used in English text and recommends replacing them with English terms. Terms in plain English are easier to understand and make documentation more readable.

Wikimedia.MovementCase

Message: Use lowercase 'movement' for the Wikimedia movement.

How to fix

If the text in your documentation refers to the Wikimedia movement, use the lowercase spelling of that word.

Explanation

Per en:Wikimedia_movement and meta:Glossary#Wikimedia_movement, the word "movement" isn't capitalized.

Wikimedia.OptionalPlurals

Message: Use a regular plural instead of '[term with optional plural]'.

How to fix

Replace a word with an optional plural, for example "connection(s)" with a regular plural "connections".

Explanation

This rule identifies instances of optional plurals and suggests replacing them with regular plurals. Optional plurals make the text less readable, harder to translate, and more difficult to read out loud, so it's best to avoid them.

Wikimedia.Passive

Message: '[text]' looks like passive voice. Consider using active voice instead.

How to fix

Rewrite the sentence or phrase to use active voice instead.

Explanation

This rule identifies instances of passive voice in documentation text and suggests a change to active voice. Passive voice is useful when it's not necessary to explicitly state the actor that performs an action. However, it also produces sentences that might be more complicated, convoluted, and less clear. This makes documentation more difficult to understand. One or two instances of passive voice on a page of documentation aren't a problem. More than that usually requires fixes to improve readability.

More information:

Documentation/Style guide#Voice and tone

Wikimedia.Repetition

Message: '[text]' has a repeated word.

How to fix

Remove one of the instances of the repeated word.

Explanation

This rule tracks repetitions of individual words in documentation text. You can usually remove the repeated word.

Wikimedia.SentenceLength

Message: Shorten or split this sentence to under 33 words to improve readability.

How to fix

Split the clauses in the sentence into separate sentences and rewrite them if necessary. One way to do this is to replace commas, semicolons, and parentheses with periods, and adjust the phrasing in the new sentences. At times, this might still be difficult. If your sentence is only slightly longer than recommended, it's safe to ignore this rule.

Explanation

This rule identifies sentences with 33 words or more. Long sentences, especially with many clauses or with specialized terminology, are often difficult to follow. Splitting such sentences into shorter ones encourages you to restate the subject and the object, making the resulting text more readable.

Wikimedia.SerialComma

Message: Use a serial comma in '[text]'.

How to fix

Add a comma before the final 'and' or 'or' in a series of items indicated in the recommendation.

Explanation

This rule identifies when the final comma is missing in the list of three or more items. Add this final comma to ensure clarity, consistency, and readability of longer series.

Wikimedia.Spacing

Message: Use one space instead of two in '[text]'.

How to fix

Remove the extra space in the indicated location.

Explanation

This rule identifies places in text with double spaces. Using two spaces after final sentence punctuation is an outdated practice. There's no reason to introduce extra spaces in documentation.

Wikimedia.Structure

Message: The document contains no headings or too few headings. Try adding headings to improve readability. Aim for at least one heading per 15 sentences.

How to fix

Introduce extra headings in your documentation.

Explanation

This rule counts the number of headings and the number of sentences and reports the recommendation when the number of headings is below one per 15 sentences. This is to make sure that documentation content is split into sections and properly structured. Headings make documentation easier to scan and introduce natural breaks that improve the reading experience. They also make it easier to link to specific content from other documentation pages.

To create well-structured content, consider adding:

headings that describe steps or tasks
headings like "Prerequisites" and "See also", for sections with additional information
headings like "Background" or "History", for sections with project background information

Note that the calculation behind this rule doesn't necessarily mean that adding a few headings always increases readability, and removing one or two decreases it. Rather, this rule aims to call attention to proper structuring of content, so if you get this recommendation, you might want to look into the page structure more.

More information:

Documentation/Style guide#Structuring pages

Wikimedia.Terms

Message: Use '[correct term capitalization]' instead of '[incorrect capitalization]'.

How to fix

Replace the incorrect capitalization with the correct one recommended in the message.

Explanation

This rule checks for common errors in capitalization of terms such as Wikipedia, Wikimedia, MediaWiki, and Wikitech.

More information:

meta:Glossary