Help us keep the Umbraco documentation accessible and readable by following our style guide which is defined in this article.
To ensure that the documentation is readable and has a similar style throughout we have defined a set of guidelines to follow. Most of the guidelines outlined here are set up with an automatic style linter called Vale. Additionally, we have a GitHub bot that will check PRs for broken rules and advise you on what to change.
Below you will find a description of each rule the Umbraco Documentation is currently being checked against.
Try to not use any kind of punctuation in headings and headlines. These should act as titles, and no punctuation is necessary.
For consistency, this rule will give a warning if you end headings with either of these punctuation symbols:
The words in the list below will cause a warning when they are included in your contribution.
Try not to use any of the mentioned words, as they are often opinionated. What may be 'easy' for you, might not be easy for another user reading the article.
In most cases, these words can be removed entirely whereas a rephrasing might be necessary in other cases.
To ensure consistency with grammar and sentences, this rule will give an error if you have a list that starts with uncapitalized words.
An exception to this rule would be when listing items or names that use camelcase.
This rule will give a warning if you have a sentence with more than 25 words.
The rule is added in order to improve the readability of the documentation.
In order to ensure readability and consistency, this rule will warn you if you have more than 1 space in a row in your text.
This rule will give you a warning when using a term that we prefer to avoid in the documentation.
Example: The term
blacklistshould be avoided and instead replaced with
This rule is added in order to ensure that Umbraco-specific terms and names are spelled consistently throughout the documentation.
The list of Umbraco Terms includes, but is not limited to Umbraco, backoffice, Document Type, and Umbraco Forms.
All first-time uses of an acronym in the documentation need to be accompanied by a definition of that acronym. If an acronym is not defined on its first use in an article, the checker will give a warning.
Acronyms should be defined using either a parenthesis or a colon followed by the definition.
Examples of the use of acronyms:
Do not do this: "Members will only have access to CDN endpoints."
Do this: "Members will only have access to Content Delivery Network (CDN) endpoints."
Do not do this: YSOD (.Net error page)
Do this: YSOD: Yellow Screen of Death, .NET error page
In order to ensure that markup languages and other names are capitalized correctly a rule has been added to check for this.
In some cases, throughout our documentation, we refer to other software providers or brands. We have added a rule to ensure that the most commonly used brand names are spelled and capitalized correctly.
The rule will, as an example, ensure that the names Microsoft and Slack are always capitalized.
There are two types of commonly used lists in the Umbraco documentation: ordered lists and unordered lists.
We recommend using ordered lists for sequential task steps and unordered lists for sets of options, notes, criteria, and the like.
In order to keep lists short and to the point, we recommend that you follow these guidelines:
- Start each item on the list with the action word.
- Do not do this: "The next thing to do, is to navigate to the Content section"⛔
- Do this: "Navigate to the Content section"✅
- Add a maximum of two actions per item list.
- Keep each list item short and to the point.
- Add additional information in one or more sub-list items.
One of the big strengths of Vale is that it is possible for a contributor to run the tests locally before you create a PR. Below are a couple of options on how to test the documentation.
There is an extension for Visual Studio Code that allows you to use Vale as you are writing documentation. It can also be used to run checks on existing articles and find where potential changes are needed.
The extension is called
vale-vscodeand can be downloaded via the Visual Studio Code Marketplace in your editor.
To use it, you will still have to install a
Vale Serveron your computer. For more information, see the official Vale installation article.
Once the tools have been installed, a check of the complete repository of articles can be done using the terminal within Visual Studio Code.
Run the following command:
vale --glob='*.md' .
The Vale extension will also run automatically when you are viewing Markdown files. It will present warnings directly in the document as you write, based on the style rules set for the project. It will look similar to this:
Example of the extension
The first step to running Vale locally is to install it following Vale's Installation documentation.
Next, you can open a command line tool in the documentation repository and run the following command:
vale --glob='*.md' .
This tells Vale to test all markdown files (.md) in the current directory (.). The output will look something like this:
It will show you what file has issues. In the case above the
v8documentation.mdthe article broke the HeadingsPunctuation rule, and it did so in the following places:
- Line 15, column 36
- Line 59, column 15
- Line 64, column 12
When the check has run you will get the total amount of errors, warnings, and suggestions including how many files have been checked.