This topic describes different ways to resolve common messages that the documentation linter produces.
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
These tips can help you improve your documentation and remove documentation linter messages.
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.
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.
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.
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.
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.
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.
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.
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.
as a result
for the most part
have a tendency to
point in time
whether or not
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 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.
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.
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.
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 -->
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
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 -->
© 2010–2023 Google, Inc.
Licensed under the Creative Commons Attribution License 4.0.