There are a couple of different ways to submit feedback on the documentation, be it the entire platform or a single article. This article will give you an overview of the different feedback channels and how to use them.

Submit feedback for articles

At the right side of each article in our documentation, you have the option to provide feedback for the content.

You can rate the content from one to five stars.

Once you have selected the number of stars, you can write feedback for the page.

Clicking the small square in the feedback window, you can select an element on the page that you want to highlight with your feedback.

Submit a GitHub Issue

The Issue Tracker is a way to keep track of ideas, issues with wrong or outdated documentation, and discussions with other contributors.

Here are a few examples of what the Issue Tracker can be used for:

• You were looking for a specific piece of information, but could not find it.

• You found a broken link in one of the articles.

• You found an article with wrong or outdated information and you do not have the time or knowledge to rewrite it.

• You want to discuss possible improvements or ways to deal with a specific thing in the documentation.

Creating an Issue

You can add issues directly from the Issue Tracker on GitHub.

We have set up a template that we recommend using when creating an Issue on the tracker. The template gives you a few questions to answer, to help you give the best explanation of what you are reporting or want to discuss.

The Umbraco Documentation is presented here on , however, it is also a and is as open source as the .

You can contribute to the documentation if something is missing or outdated. You will need a GitHub account and a fork of the UmbracoDocs GitHub repository.

How to get started

There are many ways in which you can contribute to the Umbraco Documentation. The approach you choose to take depends on what you want to achieve with your contribution.

• Request a quick/minor change to an article by submitting a

• Submit a more extensive update/change by

• Raise a question, start a discussion, or report an issue on the

• Help improve the readability of the documentation by verifying articles against our .

We have a few guidelines to follow when writing documentation and we have some tools you can use for it.

The Umbraco Documentation is written using the MarkDown markup language. We have put together .

Learn how we structure and name files in the Umbraco documentation.

Writing documentation locally

We recommend using a text editor like Visual Studio Code for making changes to the documentation on your local machine. We do not recommend using an Integrated Development Environment (IDE) like Visual Studio, for making changes to the documentation on your local machine. This is because the IDE may create files in the project which are not needed for the document changes to be implemented.

Multi-version documentation

Whenever a new version of an Umbraco product is released, the previous way of doing things may change. This means that there need to be multiple versions of our documentation.

We do this by keeping documentation for each version in separate folders.

In the screenshot above, two versions are available: 10 and 11. Within each of these folders is the documentation for all the versioned products: Umbraco Forms, Umbraco Deploy, Umbraco Workflow, and Umbraco CMS.

Umbraco Cloud and Umbraco Heartcore are not following the same versioning, which is why they are separate from this structure.

Learn more about how we handle the multiple version of our documentation in the article.

Labels

On both Issues and Pull Requests we use labels to categorize the requests and submissions.

Here's a quick explanation of the labels (colors) we use:

• Category (e.g. category/missing-documentation, category/umbraco-cloud, category/pending-release)

• Community (e.g. community/pr, help wanted)

• State (e.g. state/hq-discussion)

• Status (e.g. status/awaiting-feedback, status/idea)

• Type (e.g. type/bug)

Labels will be added to your Pull Request or Issue once it has been reviewed.

Contribution badge

If your Pull Request to any Umbraco repository gets merged, you will receive a Contributor badge on your profile on :

There are 2 scenarios for when you are looking to add a new article to the Umbraco Documentation.

1. You are to the documentation site.

   1. This includes not-before-documented topics and new tutorials.

2. You are updating .

Add new material to the documentation

When you are adding a brand new article to the Umbraco Documentation, there are a few questions that we recommend asking yourself before getting started:

The steps to create, write, and add a brand new article to the Umbraco Documentation are outlined below:

1. Access the repository.

2. Fork the repository.

3. Clone your fork to your local machine.

4. Create a new branch using the following naming convention: productname/topic

   • Branch name example: cms/new-content-app-tutorial

5. Locate the section/folder in the existing structure, where your article fits.

6. Create a new .md file and name it identical to the title you will give the article.

   • The file name needs to be all small caps and use hyphens instead of spaces.

   • File name example: statistics-content-app-tutorial.md.

7. Write the article.

8. Ensure the article lives up to our and follows the outlined .

9. Add a link to the new article in the SUMMARY.md file.

Once you have completed the article, submit the branch to your UmbracoDocs fork and .

Update an article for an upcoming major version

The documentation is versioned using directories in the root of the repository. The major Umbraco CMS version number is used to name the directories, and you will find documentation for each versioned Umbraco product within them.

The following sections of the Umbraco Documentation are following the versioning strategy:

• Umbraco CMS

• Umbraco Forms

• Umbraco Deploy

• Umbraco Workflow

• Umbraco Commerce

• Umbraco UI Builder

The documentation site for an upcoming major version of any of our products will be publicly available with the Release Candidate (RC). At Umbraco HQ we will typically start working with the site 3-4 weeks before, setting up the structure on GitHub.

Once the RC is released, you can find the associated documentation using the version drop-down on the Documentation site.

Update an article for the upcoming release

1. Access the repository.

2. Fork the repository.

3. Clone your fork to your local machine.

4. Create a new branch using the following naming convention: productnameXX/topic

   • Branch name example: cms15/configuration

5. Locate the article you need to make changes to.

6. Make the necessary changes to the article.

After making the changes to the article(s), it needs to be added to the SUMMARY.md file to be published on the documentation site.

Follow the steps below to add the article to the first available SUMMARY.md file by looking upwards in the file structure.

1. Locate the article in the .

2. Copy the line along with any ancestors.

   1. Siblings to the current and any ancestors should be left out unless they have also been updated.

   2. See the image below for an example of what to include.

1. Merge what you have copied with the existing structure in the SUMMARY.md file for version 15.

   1. You might experience that the article is already there. In this case you do not need to do anything further.

With the article(s) added to the SUMMARY.md file, the final steps involve creating a Pull Request.

1. Add and commit the changes.

2. Submit the branch to your UmbracoDocs fork.

3. .

A Pull Request (PR) is a way of submitting changes to an open-source project like the Umbraco documentation.

Let us say you have found a typing or syntax error in one of the articles on the documentation, and you want to correct it. You can do that with a pull request.

There are two ways to create a pull request:

1. You can either edit a file directly on GitHub, or

2. You can create a fork of the GitHub repository.

Option 1: Creating a PR directly on GitHub

GitHub has a functionality that allows you to submit a PR directly from our . There is also a button on the right side of every article title, which allows you to jump straight into GitHub to suggest your changes.

1. Select "Edit on GitHub" from the right-side of the article you want to suggest changes to.

2. Select the pen icon to start editing the article.

3. Make the changes.

4. Add a title and description explaining what changes you have made and why you made them.

5. Select Propose changes.

6. Select Create pull request to preview your PR.

7. Select Create pull request again to create the PR.

This is helpful to fix typing errors or add small things. If you are working on a larger update that includes pictures and editing files then it is not the best way to work. In that case, you will be better off creating a fork. See below for more thorough instructions on this approach.

Options 2: Creating a PR through a fork

There are a lot of great tutorials available online on , but we have also created a guide with instructions.

Step 1: Creating a fork

Once you have set up Git you can create a fork of the .

When you make a fork, you get a copy of the entire repository on your own GitHub profile.

You can create a fork by selecting the Fork option at the top of the screen:

Once the fork has been created you will have your own copy of the Umbraco documentation. If you clone your fork, you will have the files locally which means you can make changes and sync them back up to your fork.

When you are satisfied with the changes you have made, you can submit a pull request to sync your copy with the original repository:

Step 2: Creating a pull request

Once you have made some changes and you are happy with the result, you can create a pull request.

1. Navigate to the Code section on your fork.

2. Select Contribute and then Open pull request to get started.

1. Add a title and description explaining what changes you have made and why you made them.

2. Select Create pull request to create the pull request on the original repository.

Step 3: The review process

Your PR is now subject to review with the Umbraco HQ Documentation team.

We hope to review and resolve all incoming pull requests within a couple of weeks, depending on the extent of the changes.