1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
|
# Contribute to the documentation
import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
Welcome to our docs developer guidelines!
This document will guide you to the process of contributing to our
docs (**learn.netdata.cloud**)
## Documentation architecture
Our documentation in https://learn.netdata.cloud is generated by markdown documents in the public
Github repositories of the "netdata" organization.
### Improve existing documentation
The easiest way to contribute to Netdata's documentation is to edit a file directly on GitHub. This is perfect for small
fixes to a single document, such as fixing a typo or clarifying a confusing sentence.
Each published document on [Netdata Learn](https://learn.netdata.cloud) includes at the bottom a link to
**Edit this page**. Clicking on that link is the recommended way to improve our documentation, as it
leads you directly to GitHub's code editor.
Make your suggested changes, and use the ***Preview changes*** button to ensure your Markdown syntax works as expected.
Under the **Commit changes** header, write descriptive title for your requested change. Click the **Commit changes**
button to initiate your pull request (PR).
Jump down to our instructions on [PRs](#making-a-pull-request) for your next steps.
### Create a new document
You can create a pull request to add a completely new markdown document in any of our public repositories.
After the Github pull request is merged, our documentation team will decide where in the documentation hierarchy to publish
that document.
If you wish to contribute documentation that is tailored to your specific infrastructure
monitoring/troubleshooting experience, please consider submitting a blog post about your experience.
Check out our [blog](https://github.com/netdata/blog#readme) repo! Any blog submissions that have
widespread or universal application will be integrated into our permanent documentation.
#### Before you get started
Anyone interested in contributing significantly to documentation should first read the
[Netdata style guide](https://github.com/netdata/netdata/blob/master/docs/contributing/style-guide.md)
and the [Netdata Community Code of Conduct](https://github.com/netdata/.github/blob/main/CODE_OF_CONDUCT.md).
Netdata's documentation uses Markdown syntax. If you're not familiar with Markdown, read
the [Mastering Markdown](https://guides.github.com/features/mastering-markdown/) guide from GitHub for the basics on
creating paragraphs, styled text, lists, tables, and more.
#### Edit locally
Editing documentation locally is the preferred method for completely new documents, or complex changes that span multiple
documents. Clone the repository where you wish to make your changes, work on a new branch and create a pull request
with that branch.
### Links to other documents
Please ensure that any links to a different documentation resource are fully expanded URLs to the relevant markdown document,
not links to learn.netdata.cloud.
e.g.
```
[Correct link to this document](https://github.com/netdata/netdata/blob/master/docs/guidelines.md)
vs
[Incorrect link to this document](https://learn.netdata.cloud/XYZ)
```
This permalink ensures that the link will not be broken by any future restructuring in learn.netdata.cloud.
You can see the URL to the source of any published documentation page in the **Edit this page** link at the bottom. If you
just replace `edit` with `blob` in that URL, you have the permalink to the original markdown document.
### Making a pull request
Pull requests (PRs) should be concise and informative. See our
[PR guidelines](https://github.com/netdata/.github/blob/main/CONTRIBUTING.md#pr-guidelines) for
specifics.
The Netdata team will review your PR and assesses it for correctness, conciseness, and overall quality. We may point to
specific sections and ask for additional information or other fixes.
After merging your PR, the Netdata team rebuilds the [documentation site](https://learn.netdata.cloud) to publish the
changed documentation.
|