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
|
# Contribute to the documentation
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.
The structure of the documentation is handled by a [map](https://github.com/netdata/learn/blob/master/map.tsv) file, that contains metadata for every markdown files in the repos we ingest from.
Then the ingest script parses that map and organizes the markdown files accordingly.
### 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](/docs/developer-and-contributor-corner/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.
```text
[Correct link to this document](/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.
|
