You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Whether you've found a broken link or want to add a new article to the Umbraco
4
-
documentation, this article will guide you on your way.
3
+
Whether you've found a broken link or want to add a new article, this guide
4
+
will help you contribute to the Umbraco documentation.
5
5
---
6
6
7
-
# How to contribute
7
+
# How to Contribute
8
8
9
-
The Umbraco Documentation is presented here on [GitBook](https://docs.umbraco.com), however, it is also a [GitHub repository](https://github.com/umbraco/UmbracoDocs) and is as opensource as the [Umbraco CMS](https://github.com/umbraco/Umbraco-CMS).
9
+
The Umbraco Documentation is presented here on [GitBook](https://docs.umbraco.com). The documentation is also available as a [GitHub repository](https://github.com/umbraco/UmbracoDocs) and is open-source, just like the [Umbraco CMS](https://github.com/umbraco/Umbraco-CMS).
10
10
11
-
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**.
11
+
You can contribute to the documentation if something is missing or outdated. **A GitHub account and a fork of the UmbracoDocs GitHub repository are required**.
12
12
13
-
## How to get started
13
+
## How to Get Started
14
14
15
15
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.
16
16
17
-
* Request a quick/minor change to an article by submitting a [Pull Request](pull-request.md#option-1-creating-a-pr-directly-on-github)
18
-
* Submit a more extensive update/change by [forking the Documentation repository](pull-request.md#options-2-creating-a-pr-through-a-fork)
19
-
* Raise a question, start a discussion, or report an issue on the [Issue Tracker](issues.md)
20
-
* Help improve the readability of the documentation by verifying articles against our [Style Guide](../style-guide/#test-the-docs-yourself).
17
+
* Request a quick/minor change to an article by submitting a [Pull Request](pull-request.md#option-1-creating-a-pr-directly-on-github).
18
+
* Submit a more extensive update or change by [forking the Documentation repository](pull-request.md#options-2-creating-a-pr-through-a-fork).
19
+
* Raise a question, start a discussion, or report an issue on the [Issue Tracker](issues.md).
20
+
* Help improve the readability of the documentation by verifying articles against our [Style Guide](../style-guide/#test-the-documentation-yourself).
21
21
22
22
## [Style guide](../style-guide/)
23
23
24
-
We have a few guidelines to follow when writing documentation and we have some tools you can use for it.
24
+
Consistency and readability are important when writing and reading documentation. When you contribute, follow the style guidelines and rules outlined in the Style Guide.
25
25
26
-
## [Format, naming conventions, and files](../style-guide/markdown-conventions.md)
26
+
## [Markdown and formatting](../style-guide/markdown-conventions.md)
27
27
28
-
The Umbraco Documentation is written using the MarkDown markup language. We have put together [an article where you can learn more about MarkDown](../style-guide/markdown-conventions.md).
28
+
The Umbraco Documentation is written using the Markdown markup language.
29
29
30
-
## [File structure](../style-guide/structure.md)
30
+
## [File names and structure](../style-guide/structure.md)
31
31
32
32
Learn how we structure and name files in the Umbraco documentation.
33
33
34
34
## Writing documentation locally
35
35
36
-
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.
36
+
Use a text editor like Visual Studio Code to make changes to the documentation locally. Although it is possible, it is not recommended to use 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 that are not needed for the document changes to be implemented.
37
37
38
38
## Multi-version documentation
39
39
40
-
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.
40
+
Whenever a new version of an Umbraco product is released, the previous way of doing things may change. This means that multiple versions of our documentation must exist.
41
41
42
-
We do this by keeping documentation for each version in separate folders.
42
+
Versioning is done via the file structure, where all versioned products are located under a folder named by the major version of Umbraco.
43
43
44
-
<figure><imgsrc="../../../generic/.gitbook/assets/repository-folder-structure.png"alt=""><figcaption><p>And overview of the file structure in the UmbracoDocs GitHub repository.</p></figcaption></figure>
44
+
For example, version folders such as '10' and '11' contain documentation specific to those product versions.
45
45
46
-
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.
46
+
<figure><imgsrc="../../../generic/.gitbook/assets/repository-folder-structure.png"alt=""><figcaption><p>An overview of the file structure in the UmbracoDocs GitHub repository.</p></figcaption></figure>
47
47
48
-
Umbraco Cloud and Umbraco Heartcore are not following the same versioning, which is why they are separate from this structure.
48
+
Umbraco Cloud and Umbraco Heartcore are not documented by version, which is why they are separate from this structure.
49
49
50
-
Learn more about how we handle the multiple version of our documentation in the [documenting multiple versions and products](https://docs.umbraco.com/welcome/documentation-and-versions)article.
50
+
Learn more about how versioning is managed in the [Documenting multiple versions and products](https://docs.umbraco.com/welcome/documentation-and-versions)article.
51
51
52
52
## Labels
53
53
54
-
On both Issues and Pull Requests we use labels to categorize the requests and submissions.
55
-
56
-
Here's a quick explanation of the labels (colors) we use:
Labels will be added to your Pull Request or Issue once it has been reviewed.
65
-
66
-
## Contribution badge
67
-
68
-
If your Pull Request to any Umbraco repository gets merged, you will receive a Contributor badge on your profile on [Our Umbraco](https://our.umbraco.com):
69
-
70
-
54
+
On both Issues and Pull Requests, labels are used to categorize the requests and submissions.
55
+
56
+
Here's a quick explanation of the labels (colors):
57
+
58
+
***Category** 
59
+
* `category/missing-documentation`
60
+
*`category/umbraco-cloud`
61
+
* `category/pending-release`
62
+
***Community**
63
+
* `community/pr` 
64
+
*`help wanted`
65
+
***State**
66
+
*`state/hq-discussion`
67
+
***Status** 
68
+
*`status/awaiting-feedback`
69
+
* `status/idea`
70
+
***Type** 
71
+
*`type/bug`
72
+
***Internal Review** 
73
+
*`review/docsteam` 
74
+
*`review/developer`
75
+
76
+
Labels are added during the initial review of your pull request or issue.
Copy file name to clipboardExpand all lines: contributing/documentation/getting-started/how-to-add-a-new-version.md
+26-65Lines changed: 26 additions & 65 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,23 +4,23 @@ description: >-
4
4
including updated material for upcoming releases.
5
5
---
6
6
7
-
# Create a new version of an article
7
+
# Create a New Version of an Article
8
8
9
-
There are 2 scenarios for when you are looking to add a new article to the Umbraco Documentation.
9
+
There are 2 common scenarios where you might want to add a new article to the Umbraco Documentation:
10
10
11
11
1. You are [adding new material](how-to-add-a-new-version.md#add-new-material-to-the-documentation) to the documentation site.
12
-
1. This includes not-before-documented topics and new tutorials.
13
-
2. You are updating [an article for an **Upcoming major version**](how-to-add-a-new-version.md#update-an-article-for-an-upcoming-major-version).
12
+
1. This includes topics or tutorials not previously covered..
13
+
2. You are updating [an existing article for an **Upcoming major version**](how-to-add-a-new-version.md#update-an-article-for-an-upcoming-major-version) of a product.
14
14
15
-
## Add new material to the documentation
15
+
## Add New Material to the Documentation
16
16
17
17
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:
18
18
19
19
<details>
20
20
21
21
<summary>What type of article are you going to be writing?</summary>
22
22
23
-
It could be a tutorial, a guide on how to solve something specific, or it could be an article detailing a specific concept or workflow.
23
+
It could be a tutorial, a guide on how to solve something specific, or an article detailing a specific concept or workflow.
24
24
25
25
The type of article you are writing will determine the content and sometimes also the structure of the material.
26
26
@@ -42,28 +42,29 @@ Knowing your audience will enable you to write in a manner that fits that partic
42
42
43
43
Depending on which product you are adding new material for, the structure of the existing documentation will differ. We recommend browsing the existing material to figure out which section will be the best fit for your new article.
44
44
45
-
If you have doubts about where to place your article, the documentation team at Umbraco HQ can help you out. In this case, add a note in the description when submitting the PR, letting us know that you need help placing the article.
45
+
If you have doubts about where to place your article, the team at Umbraco HQ can help you out. In this case, add a note in the description when submitting the PR, letting us know that you need help placing the article.
46
46
47
47
</details>
48
48
49
-
The steps to create, write, and add a brand new article to the Umbraco Documentation are outlined below:
49
+
The steps to create, write, and add a new article to the Umbraco Documentation are outlined below:
50
50
51
51
1. Access the [UmbracoDocs GitHub](https://github.com/umbraco/UmbracoDocs) repository.
52
52
2. Fork the repository.
53
53
3. Clone your fork to your local machine.
54
54
4. Create a new branch using the following naming convention: `productname/topic`
55
55
* Branch name example: `cms/new-content-app-tutorial`
56
-
5. Locate the section/folder in the existing structure, where your article fits.
57
-
6. Create a new `.md` file and name it identical to the title you will give the article.
58
-
* The file name needs to be all small caps and use hyphens instead of spaces.
56
+
5. Locate the section or folder in the existing structure where your article fits.
57
+
6. Create a new `.md` file and name it using the title you will give the article.
58
+
* The file name needs to be in small caps and use hyphens instead of spaces.
59
59
* File name example: `statistics-content-app-tutorial.md`.
60
-
7. Write the article.
61
-
8. Ensure the article lives up to our [Style Guide](../style-guide/) and follows the outlined [Markdown Conventions](../style-guide/markdown-conventions.md).
62
-
9. Add a link to the new article in the [`SUMMARY.md`](#user-content-fn-2)[^2] file.
8. Add your new article to the [`SUMMARY.md`](#user-content-fn-2)[^2] file so it appears in the documentation navigation.
64
+
9. Commit and push your changes to your forked repository.
65
+
10.[Submit a PR to the official UmbracoDocs repository](pull-request.md).
63
66
64
-
Once you have completed the article, submit the branch to your UmbracoDocs fork and [submit a PR to the official UmbracoDocs repository](pull-request.md).
65
-
66
-
## Update an article for an upcoming major version
67
+
## Update an Article for an Upcoming Major Version
67
68
68
69
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.
69
70
@@ -73,27 +74,22 @@ The documentation follows the Long Term Support (LTS) strategy for Umbraco CMS.
73
74
Read the [Versioning Strategy](https://docs.umbraco.com/welcome/documentation-and-versions) article to learn more about how to handle documentation for the different versions.
74
75
{% endhint %}
75
76
76
-
The following sections of the Umbraco Documentation are following the versioning strategy:
77
+
The following sections of the Umbraco Documentation follow the versioning strategy:
77
78
78
79
* Umbraco CMS
79
80
* Umbraco Forms
80
81
* Umbraco Deploy
81
82
* Umbraco Workflow
82
83
* Umbraco Commerce
83
84
* Umbraco UI Builder
84
-
85
-
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.
86
-
87
-
Once the RC is released, you can find the associated documentation using the version drop-down on the Documentation site.
85
+
* Umbraco Engage
88
86
89
87
{% hint style="info" %}
90
-
Only updated and new material for the upcoming release will be available on the published RC documentation on GitBook. This will occur during the RC phase.
91
-
92
-
All articles will still be available through the UmbracoDocs GitHub repository.
93
-
94
-
When the final version is released, all the documentation will again be available for that version in the published documentation.
88
+
The documentation site for a new major version is publicly available around the Release Candidate (RC) phase. The structure is set up typically 3-4 weeks before the final release.
95
89
{% endhint %}
96
90
91
+
Once the RC is released, you can find the associated documentation using the version drop-down on the Documentation site.
92
+
97
93
### Update an article for the upcoming release
98
94
99
95
1. Access the [UmbracoDocs GitHub](https://github.com/umbraco/UmbracoDocs) repository.
@@ -103,45 +99,10 @@ When the final version is released, all the documentation will again be availabl
103
99
* Branch name example: `cms15/configuration`
104
100
5. Locate the article you need to make changes to.
105
101
6. Make the necessary changes to the article.
106
-
107
-
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.
108
-
109
-
Follow the steps below to add the article to the [first available `SUMMARY.md` file](#user-content-fn-3)[^3] by looking upwards in the file structure.
110
-
111
-
1. Locate the article in the [`SUMMARY.md` file for version 14](how-to-add-a-new-version.md#links-to-summary-files-for-version-14).
112
-
2. Copy the line along with any ancestors.
113
-
1. Siblings to the current and any ancestors should be left out unless they have also been updated.
114
-
2. See the image below for an example of what to include.
9.[Submit a PR to the official UmbracoDocs repository](https://docs.umbraco.com/welcome/contribute/pull-request#step-2-creating-a-pull-request).
142
105
143
106
[^1]: Code samples with comments are great for C# developers, while screenshots and step-by-step lists are good for new Umbraco developers.
144
107
145
108
[^2]: Only articles that are added to the `SUMMARY.md` file will be visible on the published documentation site.
146
-
147
-
[^3]: This `SUMMARY.md` file defines the navigation structure for the documentation site for which you are currently adding an article. If the file is not added here, it will not appear in the published documentation.
0 commit comments