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.

Rules

Below you will find a description of each rule the Umbraco Documentation is currently being checked against.

Punctuation in headings

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:

• ?

• :

• .

Editorializing

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.

• Simple

• Simply

• Just

• Easily

• Actually

Start lists with capital letters

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.

Long sentences

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.

Double spacing

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.

Terms (general)

This rule will give you a warning when using a term that we prefer to avoid in the documentation.

Example: The term blacklist should be avoided and instead replaced with deny list.

For a full list of terms please check the style rule.

Umbraco Terms

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.

Defined acronyms

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:

Names

In order to ensure that markup languages and other names are capitalized correctly a rule has been added to check for this.

The rule will ensure that instances of HTML and CSS are always written using only capital letters. It will also check whether JavaScript is written in full.

Brands

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.

Lists

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.
• 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.

Test the documentation yourself

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.

Visual Studio Code extension

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-vscode and can be downloaded via the Visual Studio Code Marketplace in your editor.

To use it, you will still have to install a Vale Server on 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:

Using Vale locally

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.md the 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.

The Umbraco Documentation uses Markdown for all articles.

In this article you can learn how we Markdown for different elements on our documentation.

Images

Images are linked using relative paths to .md pages.

The following sample adds an image, img.png, located in an images folder:

![My Image Alt Text](images/img.png)

Links

In the following you will find a few examples of different links.

External links

Include either the complete URL, or link using the following syntax:

[yahoo something](https://yahoo.com/something)

Internal links

When linking between pages in the documentation, link using relative paths. The following are examples of linking to an article.

Link to an article in the same directory as the current article:

[Article Title](article.md)

Link to an article in a different directory than the current article:

[Article Title](../../reference/article.md)

Page Links

It is possible to add a page link that spans the entire width of the page. This is generally used for linking to a new subject related to the article at hand.

The following is a page link that links to the "Submit Feedback" article:

{% content-ref url="issues.md" %}

[issues.md](issues.md)

{% endcontent-ref %}

Formatting code

Code formatting comes in 2 variants: inline code and code blocks.

Inline code

Use inline code when referencing file names and paths as well as actual code the does not extend over multiple lines.

Inline code should be wrapped in ` (backtick) characters.

Code Blocks

We follow GitBooks conventions for adding code blocks to our articles.

Adding tips and warnings

Four types of hints can be added to our documentation: info, success, warning and danger.

Learn more about how to use hints in the GitBook Docs.

The articles in the Umbraco Documentation can in most cases benefit from relevant code samples to support the written text.

In this article, you will find guidelines that outline how we recommend formatting and using code samples. We provide definitions and examples of the most used types of code samples in the Umbraco Documentation.

Code Block example

Image here

Good practices

To ensure quality and consistent code samples, follow these best-practices when adding code snippets.

• Define the context

• Add a title (file name)

• Use code comments

• Use real-life samples

• Add correct syntax highlighting

• Add only complete compilable samples (incl. using statements)

• Check for syntax errors

Each of these guidelines is explained in more detail below.

Define the context

Code samples without context, explanations, and instructions can make the reader run into issues when using the snippet.

Make sure to always add a clear description of what the code sample showcases before or after adding the snippet to the article. It should be clear where and when the snippet can be used.

Add a title (file name)

Inform the reader which file or file type a code snippet should be added to.

Aside from mentioning this in the description of the code snippet, it is also recommended to add the file name as a title.

Is the code snippet from a JSON file, add fileName.json as the caption.

Add the file name to the markup around the code block: <div data-gb-custom-block data-tag="code" data-title='fileName.json'></div>

Use code comments

When adding code samples that contain more than a single feature or method, it is recommended that you add inline comments.

By adding inline comments you avoid having too much text surrounding the code sample, and you also help readers understand the code snippet in detail.

The use of code comments does not eliminate the need for a description of the code sample in the surrounding text.

Use real-life samples

The documentation often aims to explain complex scenarios and concepts within Umbraco. This means that code samples can be useful to further the understanding. It is important that the code samples are real-life examples.

For example, using variables such as 'foo' and 'bar' can distract from the intent of the example. Aim to use an example that would make sense to add to a production environment.

Try to use placeholders for names, methods, and the like, in order to keep the code samples as neutral and general as possible.

With Umbraco, often there are often more than one way to achieve a result, depending on context and the skillset of the development team. Having multiple examples - for example, a Modelsbuilder version and a non-Modelsbuilder version - can help prevent readers from mixing techniques in their solution. It is fine to provide multiple examples.

Add correct syntax highlighting

When you add code blocks to an article, make sure that you add the correct syntax highlighting. This will "prettify" the code in the sample based on which language is used.

If you are adding a code sample using a language that isn't supported, it is recommended that you add a none label instead.

Add only complete compilable samples (incl. using statements)

A reader of the Umbraco Documentation should be able to grab code samples in the articles and apply them to their own code solution. While there might be a need for some minor alterations, the code in the sample should compile.

Include any relevant Using statements for namespaces that provide 'extension' methods or key functionality.

Check for syntax errors

When reading any piece of text, there is nothing more frustrating than running into spelling and syntax errors. This also applies to code samples.

Any code that is added to articles in the documentation should be double-checked for syntax errors and typos.

Use File Scoped Namespaces

The use of file-scoped namespaces improves, among other things, the readability of the code samples. Therefore, use file scoped namespaces in the examples. See below how to use file-scoped namespaces:

namespace MyProject;

public class Umbraco
{
}

Instead of:

namespace MyProject
{
    public class Umbraco
    {
    }
}

When to use code samples

Code samples are relevant for most types of articles. Potentially, any topic covered could benefit from a real-life code sample to support the contents of the article.

You might want to base an entire article on one code sample. Alternately, if you're describing a flow or feature, you might want to add smaller code snippets to highlight specific points.

Types of samples

As a basis, we are working with 3 types of code samples in the Umbraco Documentation.

Inline code

Use inline code when you are referencing methods, using the names of the elements or highlighting a certain value.

Example:

Each item is treated as a standard `IPublishedElement entity`, which means you can use all the value converters you are used to using.

The markdown above will output the following:

Smaller code snippets

As part of longer articles or tutorials, we recommend using smaller code snippets to highlight the bits of code that need to be implemented.

These snippets can be added between sections anywhere in an article without breaking focus from the main topic. Keep in mind that adding too many snippets in quick succession can be confusing to the flow of the article.

Example:

@{
    // Perform an null-check on the field with alias 'pageTitle'
    if (Model.HasValue("pageTitle")){
        // Print the value of the field with alias 'pageTitle'
        <p>@(Model.Value("pageTitle"))</p>
    }
}

The Razor snippet above will output the following:

Large code samples

As part of tutorials and longer articles explaining a specific workflow, it might make sense to add a full code sample of the topic covered.

We recommend creating separate articles for these large code samples and using them as references, instead of adding them as part of the actual article. Having long snippets in an article that already contains multiple sections and steps can make the article confusing.

It is highly recommended to use line numbers in large code samples. This will make it easier to reference certain parts of the sample in the surrounding text.

When you a contributing to the Umbraco documentation it can be useful to know how we structure directories, files and images.

In this article you will get an overview of the file structure as well as a few best-practices for naming files.

By product and topic

The overall structure of the Umbraco documentation is divided by product. Each Umbraco product has its own directories with articles and images.

Diving one step deeper, each individual topic is contained in its own directory.

Each directory must have a README.md file which will act as a landing page for that directory. If images are used, these must be in an images directory next to the .md file referencing them using relative paths.

• /topic (directory)

  • README.md

  • another-page.md

  • /images (directory)

    • images.png

  • /subtopic (directory)

    • README.md

    • topic.md

    • another-topic.md

    • /images (directory)

File names

All file and directory names need to be small-caps in order to be synced properly with GitBook.

If an article is not a landing page, we recommend using the title of the article as the file name.

Images

Images are stored and linked using relative paths to .md pages, and should by convention always be in an images directory. To add an image to /documentation/reference/partials/renderviewpage.md you link it like so:

And store the image as /documentation/reference/partials/images/img.png

Images can have a maximum width of 800px. Please always try to use the most efficient compression, gif or png. No bmp, tiff or swf (Flash).