Resolve documentation linter messages

This topic describes different ways to resolve common messages that the documentation linter produces.

Anatomy of a documentation linter message

This is an example of a message produced by the documentation linter.

A documentation linter message contains these elements. Starting from the top line:

  • The severity. One of these icons indicates the severity of the message:

    • Error (A red x in a circle) Errors must be corrected before the file can be merged.

    • Warning (A yellow exclamation mark in a triangle) Warnings should be corrected before the file is merged.

    • Info (A blue lower-case i in a circle) Informational messages should be corrected before the file is merged.

  • The style rule message. The style rule message in this example is:

    Did you really mean 'sdfdsfsdfdfssd'? It wasn't found in our dictionary.
  • The style reference. Some references are linked to a style guide topic that explains the rule. The style reference in this example is:

  • The location of the problem text in the document identified by source line and column as precisely as possible. Some messages might not have the exact location of the text that triggered the message. The location in this example is:

    [Ln 8, Col 1]
  • The style test definition file that produced the message, which is linked to the file. The style test definition in this example is:

    Angular_Spelling.yml[Ln 1, Col 1]: View rule

Strategies to improve your documentation

These tips can help you improve your documentation and remove documentation linter messages.

Refer to the style guides

The lint tool tests against the styles found in these style guides. Most style tests include links to relevant sections in these documents for more information.

Not every style mentioned in the style guides has a test. Style guides and the style tests can change.

Split up long sentences

Generally, shorter sentences are easier to read than longer ones. Long sentences can occur when you try to say too much at once. Long sentences, as well as the use of parentheses, semicolons, or words identified as too-wordy, generally require rethinking and rewriting.

Consider restructuring a long sentence to break its individual ideas into distinct sentences or bullet points.

Use lists and tables

Sentences that contain comma-separated lists might be clearer if presented as a bulleted-list or table.

Consider changing a comma-separated list of items in a sentence to a list of bullets to make those list items easier to read.

Use more common words

Shorter, more common words are generally easier to read than longer ones. This does not mean you need to write down to the audience. Technical docs should still be precise. Angular docs are read by many people around the world and should use language that the most people can understand.

If you think a specific term is required even though it has been flagged as uncommon, try to include a short explanation of the term. Also, try adding some context around its first mention.

Linking a term to another section or topic is also an option, but consider the disruption that causes to the reader before you use it. If you force a reader to go to another page for a definition, they might lose their concentration on the current topic and their primary goal.

Use fewer words

If you can remove a word and not lose the meaning of the sentence, leave it out.

One common place where removing words can help is in a list of examples with more than two or three items. Before you place the items in a bullet list, consider if only one of the items can convey the desired meaning. Another option might be to replace a list of items with a single term that describes all the elements in your list.

More about specific documentation linter messages

Most documentation linter messages are self-explanatory and include a link to supplementary documentation. Some messages identify areas in that the documentation might need more thought. The following types of messages often occur in areas of the text that should be reconsidered and rewritten to improve the text and remove the message.

A word is too-wordy or should be replaced by another

Generally, technical documentation should use a simple and consistent vocabulary to be understood by a wide audience. Words that trigger this message are usually words for which there's a simpler way to convey the same thought.

Angular.WriteGood_TooWordy - See if you can rewrite the sentence...

Words identified by this style test can usually be replaced by simpler words. If not, sentences with these words should be revised to use simpler language and avoid the word in the message.

The following table has some common words detected by this type of message and simpler words to try in their place.

Too-wordy word Simpler replacement
accelerate speed up
accomplish perform or finish
acquire get
additional more
adjustment change
advantageous beneficial
consequently as a result
designate assign
equivalent the same
exclusively only
for the most part generally
have a tendency to tend to
in addition furthermore
modify change or update
monitor observe
necessitate require
one particular one
point in time moment
portion part
similar to like
validate verify
whether or not whether

WordList messages

The messages about words detected by these style tests generally suggest a better alternative. While the word you used would probably be understood, it most likely triggered this message for one of the following reasons:

  • The suggested works better in a screen-reader context
  • The word that you used could produce an unpleasant response in the reader
  • The suggested word is simpler, shorter, or easier for more people to understand
  • The word you used has other possible variations. The suggested word is the variation to use in the documentation to be consistent.

Proselint messages

The Proselint style tests test for words that are jargon or that could be offensive to some people.

Rewrite the text to replace the jargon or offensive language with more inclusive language.

Starting a sentence messages

Some words, such as so and there is/are, aren't necessary at the beginning of a sentence. Sentences that start with the words identified by this message can usually be made shorter, simpler, and clearer by rewriting them without those openings.


Cliches should be replaced by more literal text.

Cliches make it difficult for people who don't understand English to understand the documentation. When cliches are translated by online tools such as Google Translate, they can produce confusing results.

If all else fails

The style rules generally guide you in the direction of clearer content, but sometimes you might need to break the rules. If you decide that the best choice for the text conflicts with the linter, mark the text as an exception to linting.

The documentation linter checks only the content that is rendered as text. It does not test code-formatted text. One common source of false problems is code references that are not formatted as code.

If you use these exceptions, please limit the amount of text that you exclude from analysis to the fewest lines possible.

When necessary, you can apply these exceptions to your content.

  1. General exception

    A general exception allows you to exclude the specified text from all lint testing.

    To apply a general exception, surround the text that you do not want the linter to test with the HTML comment elements shown in this example.

    <!-- vale off -->
    Text the linter does not check for any style problem.
    <!-- vale on -->

    Be sure to leave a blank line before and after each comment.

  2. Style exception

    A style exception allows you to exclude text from an individual style test.

    To apply a style exception, surround the text that you do not want the linter to test with these HTML comment elements. Between these comments, the linter ignores the style test in the comment, but still tests for all other styles that are in use.

    <!-- vale Style.Rule = NO -->
    <!-- vale Style.Rule = YES -->

    Replace Style.Rule in the comments with the style rule reference from the problem message displayed in the IDE. For example, imagine that you got this problem message and you want to use the word it identified as a problem.

    Did you really mean 'inlines'?  It was not found in our dictionary. Vale(Angular.Angular_Spelling) [Ln 24, Col 59]
    Angular_Spelling.yml[Ln 1, Col 1]: View rule

    The Style.Rule for this message is the text inside the parentheses: Angular.Angular_Spelling in this case. To turn off that style test, use the comments shown in this example.

    <!-- vale Angular.Angular_Spelling = NO -->
    'inlines' does not display a problem because this text is not spell-checked.
    Remember that the linter does not check any spelling in this block of text.
    The linter continues to test all other style rules.
    <!-- vale Angular.Angular_Spelling = YES -->
Last reviewed on Wed Oct 12 2022

© 2010–2023 Google, Inc.
Licensed under the Creative Commons Attribution License 4.0.