Tweaks and linter fixes (#7407)
Joel Hans committed
Jan 14, 2020 at 03:50 UTC
bb51e824f97cd135674e2940bdbd5458fbfba15f
2 files changed
+194
-139
docs/contributing/contributing-documentation.md
+84
-87
@@ -1,19 +1,19 @@
1
# Contributing to documentation
2
3
-We welcome contributions to Netdata's already extensive documentation,
4
-which we host at [docs.netdata.cloud](https://docs.netdata.cloud/)
5
-and store inside of the [main repository](https://github.com/netdata/netdata) on GitHub.
3
+We welcome contributions to Netdata's already extensive documentation, which we host at
4
+[docs.netdata.cloud](https://docs.netdata.cloud/) and store inside of the [main
5
+repository](https://github.com/netdata/netdata) on GitHub.
6
7
-Like all contributing to all other aspects of Netdata, we ask that anyone who wants to help with documentation
8
-read and abide by the [Contributor Convenant Code of Conduct](https://docs.netdata.cloud/code_of_conduct/)
9
-and follow the instructions outlined in our [Contributing document](../../CONTRIBUTING.md).
7
+Like all contributing to all other aspects of Netdata, we ask that anyone who wants to help with documentation read and
8
+abide by the [Contributor Convenant Code of Conduct](https://docs.netdata.cloud/code_of_conduct/) and follow the
9
+instructions outlined in our [Contributing document](../../CONTRIBUTING.md).
10
11
-We also ask you to read our [documentation style guide](style-guide.md), which, while not complete,
12
-will give you some guidance on how we write and organize our documentation.
11
+We also ask you to read our [documentation style guide](style-guide.md), which, while not complete, will give you some
12
+guidance on how we write and organize our documentation.
13
14
-All our documentation uses the Markdown syntax. If you're not familiar with how it works,
15
-please read the [Markdown introduction post](https://daringfireball.net/projects/markdown/) by its creator,
16
-followed by [Mastering Markdown](https://guides.github.com/features/mastering-markdown/) guide from GitHub.
14
+All our documentation uses the Markdown syntax. If you're not familiar with how it works, please read the [Markdown
15
+introduction post](https://daringfireball.net/projects/markdown/) by its creator, followed by [Mastering
16
+Markdown](https://guides.github.com/features/mastering-markdown/) guide from GitHub.
17
18
## How contributing to the documentation works
19
@@ -22,16 +22,15 @@ There are two ways to contribute to Netdata's documentation:
22
1. Edit documentation [directly in GitHub](#edit-documentation-directly-on-github).
23
2. Download the repository and [edit documentation locally](#edit-documentation-locally).
24
25
-Editing in GitHub is a simpler process and is perfect for quick edits to a single document,
26
-such as fixing a typo or clarifying a confusing sentence.
25
+Editing in GitHub is a simpler process and is perfect for quick edits to a single document, such as fixing a typo or
26
+clarifying a confusing sentence.
27
28
-Editing locally is more complex, as you need to download the Netdata repository
29
-and build the documentation using `mkdocs`, but allows you to better organize complex projects.
30
-By building documentation locally, you can preview your work using a local web server before you submit your PR.
28
+Editing locally is more complex, as you need to download the Netdata repository and build the documentation using
29
+`mkdocs`, but allows you to better organize complex projects. By building documentation locally, you can preview your
30
+work using a local web server before you submit your PR.
31
32
-In both cases, you'll finish by submitting a pull request (PR).
33
-Once you submit your PR, GitHub will initiate a number of jobs, including a Netlify preview.
34
-You can use this preview to view the documentation site with your changes applied,
32
+In both cases, you'll finish by submitting a pull request (PR). Once you submit your PR, GitHub will initiate a number
33
+of jobs, including a Netlify preview. You can use this preview to view the documentation site with your changes applied,
34
which might help you catch any lingering issues.
35
36
To continue, follow one of the paths below:
@@ -41,46 +40,47 @@ To continue, follow one of the paths below:
40
41
## Edit documentation directly on GitHub
42
44
-Start editing documentation on GitHub by clicking the small pencil icon on any page on Netdata's [documentation site](https://docs.netdata.cloud/).
45
-You can find them at the top of every page.
43
+Start editing documentation on GitHub by clicking the small pencil icon on any page on Netdata's [documentation
44
+site](https://docs.netdata.cloud/). You can find them at the top of every page.
45
47
-Clicking on this icon will take you to the associated page in the `netdata/netdata` repository.
48
-Then click the small pencil icon on any documentation file (those ending in the `.md` Markdown extension) in the `netdata/netdata` repository.
46
+Clicking on this icon will take you to the associated page in the `netdata/netdata` repository. Then click the small
47
+pencil icon on any documentation file (those ending in the `.md` Markdown extension) in the `netdata/netdata`
48
+repository.
49
50
-
50
+
52
52
-If you know where a file resides in the Netdata repository already,
53
-you can skip the step of beginning on the documentation site and go directly to GitHub.
53
+If you know where a file resides in the Netdata repository already, you can skip the step of beginning on the
54
+documentation site and go directly to GitHub.
55
55
-Once you've clicked the pencil icon on GitHub, you'll see a full Markdown version of the file.
56
-Make changes as you see fit.
57
-You can use the `Preview changes` button to ensure your Markdown syntax is working properly.
56
+Once you've clicked the pencil icon on GitHub, you'll see a full Markdown version of the file. Make changes as you see
57
+fit. You can use the `Preview changes` button to ensure your Markdown syntax is working properly.
58
59
-Under the `Propose file change` header, write in a descriptive title for your requested change.
60
-Beneath that, add a concise description of what you've changed and why you think it's important. Then, click the `Propose file change` button.
59
+Under the `Propose file change` header, write in a descriptive title for your requested change. Beneath that, add a
60
+concise descrition of what you've changed and why you think it's important. Then, click the `Propose file change`
61
+button.
62
62
-After you've hit that button,
63
-jump down to our instructions on [pull requests and cleanup](#pull-requests-and-final-steps) for your next steps.
63
+After you've hit that button, jump down to our instructions on [pull requests and
64
+cleanup](#pull-requests-and-final-steps) for your next steps.
65
65
-!!! note
66
- This process will create a branch directly on the `netdata/netdata` repository, which then requires manual cleanup.
67
- If you're going to make significant documentation contributions, or contribute often,
68
- we recommend the local editing process just below.
66
+!!! note This process will create a branch directly on the `netdata/netdata` repository, which then requires manual
67
+ cleanup. If you're going to make significant documentation contributions, or contribute often, we recommend the
68
+ local editing process just below.
69
70
## Edit documentation locally
71
72
-Editing documentation locally is the preferred method for complex changes, PRs that span across multiple documents,
73
-or those that change the styling or underlying functionality of the documentation.
72
+Editing documentation locally is the preferred method for complex changes, PRs that span across multiple documents, or
73
+those that change the styling or underlying functionality of the documentation.
74
75
-Here is the workflow for editing documentation locally. First, create a fork of the Netdata repository,
76
-if you don't have one already. Visit the [Netdata repository](https://github.com/netdata/netdata)
77
-and click on the `Fork` button in the upper-right corner of the window.
75
+Here is the workflow for editing documentation locally. First, create a fork of the Netdata repository, if you don't
76
+have one already. Visit the [Netdata repository](https://github.com/netdata/netdata) and click on the `Fork` button in
77
+the upper-right corner of the window.
78
79
-
79
+
81
81
-GitHub will ask you where you want to clone the repository,
82
-and once finished you'll end up at the index of your forked Netdata repository.
83
-Clone your fork to your local machine:
82
+GitHub will ask you where you want to clone the repository, and once finished you'll end up at the index of your forked
83
+Netdata repository. Clone your fork to your local machine:
84
85
```bash
86
git clone https://github.com/YOUR-GITHUB-USERNAME/netdata.git
@@ -90,19 +90,19 @@ You can now jump into the directory and explore Netdata's structure for yourself
90
91
### Understanding the structure of Netdata's documentation
92
93
-All of Netdata's documentation is stored within the repository itself, as close as possible to the code it
94
-corresponds to. Many sub-folders contain a `README.md` file,
95
-which is then used to populate the documentation about that feature/component of Netdata.
93
+All of Netdata's documentation is stored within the repository itself, as close as possible to the code it corresponds
94
+to. Many sub-folders contain a `README.md` file, which is then used to populate the documentation about that
95
+feature/component of Netdata.
96
97
-For example, the file at `packaging/installer/README.md` becomes `https://docs.netdata.cloud/packaging/installer/`
98
-and is our installation documentation. By co-locating it with quick-start installation code,
99
-we ensure documentation is always tightly knit with the functions it describes.
97
+For example, the file at `packaging/installer/README.md` becomes `https://docs.netdata.cloud/packaging/installer/` and
98
+is our installation documentation. By co-locating it with quick-start installtion code, we ensure documentation is
99
+always tightly-knit with the functions it describes.
100
101
-You might find other `.md` files within these directories. The `packaging/installer/` folder also contains `UPDATE.md`
102
-and `UNINSTALL.md`, which become `https://docs.netdata.cloud/packaging/installer/update/`
103
-and `https://docs.netdata.cloud/packaging/installer/uninstall/`, respectively.
101
+You might find other `.md` files within these directories. The `packaging/installer/` folder also contains `UPDATE.md`
102
+and `UNINSTALL.md`, which become `https://docs.netdata.cloud/packaging/installer/update/` and
103
+`https://docs.netdata.cloud/packaging/installer/uninstall/`, respectively.
104
105
-If the documentation you're working on has a direct correlation to some component of Netdata, place it into the correct
105
+If the documentation you're working on has a direct correlation to some component of Netdata, place it into the correct
106
folder and either name it `README.md` for generic documentation, or with another name for very specific instructions.
107
108
#### The `docs` folder
@@ -112,57 +112,56 @@ a direct relationship to a specific component of Netdata. It's where we house ou
112
guide](../../docs/getting-started.md), guides on [running Netdata behind Nginx](../../docs/Running-behind-nginx.md), and
113
more.
114
115
-If the documentation you're working on doesn't have a direct relationship to a component of Netdata,
116
-it can be placed in this `docs/` folder.
115
+If the documentation you're working on doesn't have a direct relaionship to a component of Netdata, it can be placed in
116
+this `docs/` folder.
117
118
### Make your edits
119
120
-Now that you're set up and understand where to find or create your `.md` file, you can now begin to make your edits.
120
+Now that you're set up and understand where to find or create your `.md` file, you can now begin to make your edits.
121
Just use your favorite editor and keep in mind our [style guide](style-guide.md) as you work.
122
123
-If you add a new file to the documentation, you may need to modify the `buildyaml.sh` file to ensure
124
-it's added to the site's navigation. This is true for any file added to the `docs/` folder.
123
+If you add a new file to the documentation, you may need to modify the `buildyaml.sh` file to ensure it's added to the
124
+site's navigation. This is true for any file added to the `docs/` folder.
125
126
-Be sure to periodically add/commit your edits so that you don't lose your work!
127
-We use version control software for a reason.
126
+Be sure to periodically add/commit your edits so that you don't lose your work! We use version control software for a
127
+reason.
128
129
### Build the documentation
130
131
-Building the documentation periodically gives you a glimpse into the final product, and is generally required
132
-if you're making changes to the table of contents.
131
+Building the documentation periodically gives you a glimpse into the final product, and is generally required if you're
132
+making changes to the table of contents.
133
134
-!!! attention ""
135
- We have only tested the build process on Linux. Initial tests on OS X have been unsuccessful.
136
- Windows is fully untested at this point, but we would love to know if it works there as well!
134
+!!! attention "" We have only tested the build process on Linux. Initial tests on OS X have been unsuccessful. Windows
135
+ is fully untested at this point, but we would love to know if it works there as well!
136
137
To build the documentation, you need `python`/`pip`, `mkdocs`, and `mkdocs-material` installed on your machine.
138
139
Follow the [Python installation instructions](https://www.python.org/downloads/) for your machine.
140
142
-Use `pip`, which was installed alongside Python, to install `mkdocs` and `mkdocs-material`.
143
-Your operating system might force you to use `pip2` or `pip3` instead,
144
-depending on which version of Python you have installed.
141
+Use `pip`, which was installed alongside Python, to install `mkdocs` and `mkdocs-material`. Your operating system might
142
+force you to use `pip2` or `pip3` instead, depending on which version of Python you have installed.
143
144
```bash
147
-pip install mkdocs mkdocs-material
145
+pip install mkdocs mkdocs-material --user
146
```
147
150
-??? note "Troubleshooting"
151
- If you're having trouble with the installation of Python, `mkdocs`, or `mkdocs-material`, try looking into the `mkdocs` [installation instructions](https://squidfunk.github.io/mkdocs-material/getting-started/#installation).
148
+> If you're having trouble with the installation of Python, `mkdocs`, or `mkdocs-material`, try looking into the
149
+> `mkdocs` [installation instructions](https://squidfunk.github.io/mkdocs-material/getting-started/#installation).
150
153
-When `pip` is finished installing, navigate to the root directory of the Netdata repository
154
-and run the documentation generator script.
151
+When `pip` is finished installing, navigate to the root directory of the Netdata repository and run the documentation
152
+generator script.
153
154
```bash
155
sh docs/generator/buildhtml.sh
156
```
157
160
-This process will take some time. Once finished, the built documentation site will be located at `docs/generator/build/`.
158
+This process will take some time. Once finished, the built documentation site will be located at
159
+`docs/generator/build/`.
160
161
### Run a local web server to test documentation
162
164
-The best way to view the documentation site you just built is to run a simple web server from the `docs/generator/build/` directory.
165
-So, navigate there and run a Python-based web server:
163
+The best way to view the documentation site you just built is to run a simple web server from the
164
+`docs/generator/build/` directory. So, navigate there and run a Python-based web server:
165
166
```sh
167
cd docs/generator/build/
@@ -172,18 +171,16 @@ python3 -m http.server 20000
171
Feel free to replace the port number you want this web server to listen on (port `20000` in this case (only one higher
172
than the agent!)).
173
175
-Open your web browser and navigate to `http://localhost:20000`.
176
-If you replaced the port earlier, change it here as well.
177
-You can now navigate through the documentation as you would on the live site!
174
+Open your web browser and navigate to `http://localhost:20000`. If you replaced the port earlier, change it here as
175
+well. You can now navigate through the documentation as you would on the live site!
176
177
## Pull requests and final steps
178
181
-When you're finished with your changes, add and commit them to your fork of the Netdata repository.
182
-Head over to GitHub to create your pull request (PR).
179
+When you're finished with your changes, add and commit them to your fork of the Netdata repository. Head over to GitHub
180
+to create your pull request (PR).
181
184
-Once we receive your pull request (PR), we'll take time to read through it and assess it for correctness, conciseness,
185
-and overall quality.
186
-We may point to specific sections and ask for additional information or other fixes.
182
+Once we receive your pull request (PR), we'll take time to read through it and assess it for correctness, conciseness,
183
+and overall quality. We may point to specific sections and ask for additional information or other fixes.
184
185
## What's next
186
docs/contributing/style-guide.md
+110
-52
@@ -1,6 +1,7 @@
1
# Netdata style guide
2
3
-This in-progress style guide establishes editorial guidelines for anyone who wants to write documentation for Netdata products.
3
+This in-progress style guide establishes editorial guidelines for anyone who wants to write documentation for Netdata
4
+products.
5
6
## Table of contents
7
@@ -14,28 +15,34 @@ This in-progress style guide establishes editorial guidelines for anyone who wan
15
16
## Welcome
17
17
-Proper documentation is essential to the success of any open-source project. Netdata is no different. The health of our monitoring agent, and the community it's created, depends on this effort.
18
+Proper documentation is essential to the success of any open-source project. Netdata is no different. The health of our
19
+monitoring agent, and the community it's created, depends on this effort.
20
21
We’re here to make developers, sysadmins, and DevOps engineers better at their jobs, after all!
22
21
-We welcome contributions to Netdata's documentation. Begin with the [contributing to documentation guide](contributing-documentation.md), followed by this style guide.
23
+We welcome contributions to Netdata's documentation. Begin with the [contributing to documentation
24
+guide](contributing-documentation.md), followed by this style guide.
25
26
## Goals of the Netdata style guide
27
25
-An editorial style guide establishes standards for writing and maintaining documentation. At Netdata, we focus on the following principles:
28
+An editorial style guide establishes standards for writing and maintaining documentation. At Netdata, we focus on the
29
+following principles:
30
31
- Consistency
32
- High-quality writing
33
- Conciseness
34
- Accessibility
35
32
-These principles will make documentation better for everyone who wants to use Netdata, whether they're a beginner or an expert.
36
+These principles will make documentation better for everyone who wants to use Netdata, whether they're a beginner or an
37
+expert.
38
39
### Breaking the rules
40
36
-None of the rules described in this style guide are absolute. **We welcome rule-breaking if it creates better, more accessible documentation.**
41
+None of the rules described in this style guide are absolute. **We welcome rule-breaking if it creates better, more
42
+accessible documentation.**
43
38
-But be aware that Netdata staff or community members may ask you to justify your rule-breaking during the PR review process.
44
+But be aware that Netdata staff or community members may ask you to justify your rule-breaking during the PR review
45
+process.
46
47
## General principles
48
@@ -52,7 +59,8 @@ Here's a few key points to start with. Where relevant, they link to more in-dept
59
60
**[Language and grammar](#language-and-grammar)**:
61
55
-- [Capitalize words](#capitalization) at the beginning of sentences, for proper nouns, and at the beginning of document titles and section headers.
62
+- [Capitalize words](#capitalization) at the beginning of sentences, for proper nouns, and at the beginning of
63
+ document titles and section headers.
64
- Use [second person](#second-person)—"you" rather than "we"—when giving instructions.
65
- Use [active voice](#active-voice) to make clear who or what is performing an action.
66
- Always employ an [Oxford comma](#oxford-comma) on lists.
@@ -60,7 +68,8 @@ Here's a few key points to start with. Where relevant, they link to more in-dept
68
**[Markdown syntax](#markdown-syntax)**:
69
70
- [Reference UI elements](#references-to-ui-elements) with bold text.
63
-- Use our [built-in syntax highlighter](#language-specific-syntax-highlighting-in-code-blocks) to improve the readability and usefulness of code blocks.
71
+- Use our [built-in syntax highlighter](#language-specific-syntax-highlighting-in-code-blocks) to improve the
72
+ readability and usefulness of code blocks.
73
74
**[Accessibility](#accessibility)**:
75
@@ -70,25 +79,31 @@ Here's a few key points to start with. Where relevant, they link to more in-dept
79
80
## Tone and content
81
73
-Netdata's documentation should be conversational, concise, and informational, without feeling formal. This isn't a textbook. It's a repository of information that should (on occasion!) encourage and excite its readers.
82
+Netdata's documentation should be conversational, concise, and informational, without feeling formal. This isn't a
83
+textbook. It's a repository of information that should (on occasion!) encourage and excite its readers.
84
75
-By following a few principles on tone and content we'll ensure more readers from every background and skill level will learn as much as possible about Netdata's capabilities.
85
+By following a few principles on tone and content we'll ensure more readers from every background and skill level will
86
+learn as much as possible about Netdata's capabilities.
87
88
### Conversational and friendly tone
89
79
-Netdata's documentation should be conversational and friendly. To borrow from Google's fantastic [developer style guide](https://developers.google.com/style/tone):
90
+Netdata's documentation should be conversational and friendly. To borrow from Google's fantastic [developer style
91
+guide](https://developers.google.com/style/tone):
92
93
> Try to sound like a knowledgeable friend who understands what the developer wants to do.
94
83
-Feel free to let some of your personality show! Documentation can be highly professional without being dry, formal, or overly instructive.
95
+Feel free to let some of your personality show! Documentation can be highly professional without being dry, formal, or
96
+overly instructive.
97
98
### Write concisely
99
87
-You should always try to use as few words as possible to explain a particular feature, configuration, or process. Conciseness leads to more accurate and understandable writing.
100
+You should always try to use as few words as possible to explain a particular feature, configuration, or process.
101
+Conciseness leads to more accurate and understandable writing.
102
103
### Use informational hyperlinks
104
91
-Hyperlinks should clearly state its destination. Don't use words like "here" to describe where a link will take your reader.
105
+Hyperlinks should clearly state its destination. Don't use words like "here" to describe where a link will take your
106
+reader.
107
108
```
109
# Not recommended
@@ -98,50 +113,64 @@ To install Netdata, click [here](https://docs.netdata.cloud/packaging/installer/
113
To install Netdata, read our [installation instructions](https://docs.netdata.cloud/packaging/installer/).
114
```
115
101
-In general, guides should include fewer hyperlinks to keep the reader focused on the task at hand. Documentation should include as many hyperlinks as necessary to provide meaningful context.
116
+In general, guides should include fewer hyperlinks to keep the reader focused on the task at hand. Documentation should
117
+include as many hyperlinks as necessary to provide meaningful context.
118
119
### Avoid words like "easy" or "simple"
120
105
-Never assume readers of Netdata documentation are experts in Netdata's inner workings or health monitoring/performance troubleshooting in general.
121
+Never assume readers of Netdata documentation are experts in Netdata's inner workings or health monitoring/performance
122
+troubleshooting in general.
123
124
If you claim that a task is easy and the reader struggles to complete it, they'll get discouraged.
125
109
-If you perceive one option to be easier than another, be specific about how and why. For example, don't write, "Netdata's one-line installer is the easiest way to install Netdata." Instead, you might want to say, "Netdata's one-line installer requires fewer steps than manually installing from source."
126
+If you perceive one option to be easier than another, be specific about how and why. For example, don't write,
127
+"Netdata's one-line installer is the easiest way to install Netdata." Instead, you might want to say, "Netdata's
128
+one-line installer requires fewer steps than manually installing from source."
129
130
### Avoid slang, metaphors, and jargon
131
113
-A particular word, phrase, or metaphor you're familiar with might not translate well to the other cultures featured among Netdata's global community. It's recommended you avoid slang or colloquialisms in your writing.
132
+A particular word, phrase, or metaphor you're familiar with might not translate well to the other cultures featured
133
+among Netdata's global community. It's recommended you avoid slang or colloquialisms in your writing.
134
115
-If you must use industry jargon, such as "white-box monitoring," in a document, be sure to define the term as clearly and concisely as you can.
135
+If you must use industry jargon, such as "white-box monitoring," in a document, be sure to define the term as clearly
136
+and concisely as you can.
137
138
> White-box monitoring: Monitoring of a system or application based on the metrics it directly exposes, such as logs.
139
119
-Avoid emojis whenever possible for the same reasons—they can be difficult to understand immediately and don't translate well.
140
+Avoid emojis whenever possible for the same reasons—they can be difficult to understand immediately and don't translate
141
+well.
142
143
### Mentioning future releases or features
144
123
-Documentation is meant to describe the product as-is, not as it will be or could be in the future. Netdata documentation generally avoids talking about future features or products, even if we know they are inevitable.
145
+Documentation is meant to describe the product as-is, not as it will be or could be in the future. Netdata documentation
146
+generally avoids talking about future features or products, even if we know they are inevitable.
147
148
An exception can be made for documenting beta features that are subject to change with further development.
149
150
## Language and grammar
151
129
-Netdata's documentation should be consistent in the way it uses certain words, phrases, and grammar. The following sections will outline the preferred usage for capitalization, point of view, active voice, and more.
152
+Netdata's documentation should be consistent in the way it uses certain words, phrases, and grammar. The following
153
+sections will outline the preferred usage for capitalization, point of view, active voice, and more.
154
155
### Capitalization
156
133
-In text, follow the general [English standards](https://owl.purdue.edu/owl/general_writing/mechanics/help_with_capitals.html) for capitalization. In summary:
157
+In text, follow the general [English
158
+standards](https://owl.purdue.edu/owl/general_writing/mechanics/help_with_capitals.html) for capitalization. In summary:
159
160
- Capitalize the first word of every new sentence.
161
- Don't use uppercase for emphasis. (Netdata is the BEST!)
137
-- Capitalize the names of brands, software, products, and companies according to their official guidelines. (Netdata, Docker, Apache, Nginx)
162
+- Capitalize the names of brands, software, products, and companies according to their official guidelines. (Netdata,
163
+ Docker, Apache, Nginx)
164
- Avoid camel case (NetData) or all caps (NETDATA).
165
166
#### Capitalization of 'Netdata' and 'netdata'
167
142
-Whenever you refer to the company Netdata, Inc., or the open-source monitoring agent the company develops, capitalize **Netdata**.
168
+Whenever you refer to the company Netdata, Inc., or the open-source monitoring agent the company develops, capitalize
169
+**Netdata**.
170
144
-However, if you are referring to a process, user, or group on a Linux system, you should not capitalize, as by default those are typically lowercased. In this case, you should also fence these terms in an inline code block: `` `netdata` ``.
171
+However, if you are referring to a process, user, or group on a Linux system, you should not capitalize, as by default
172
+those are typically lowercased. In this case, you should also fence these terms in an inline code block: `` `netdata`
173
+``.
174
175
```
176
# Not recommended
@@ -155,7 +184,8 @@ The Netdata agent, which spawns the `netdata` process, is actively maintained by
184
185
Document titles and page headings should use sentence case. That means you should only capitalize the first word.
186
158
-If you need to use the name of a brand, software, product, and company, capitalize it according to their official guidelines.
187
+If you need to use the name of a brand, software, product, and company, capitalize it according to their official
188
+guidelines.
189
190
Also, don't put a period (`.`) or colon (`:`) at the end of a title or header.
191
@@ -169,7 +199,8 @@ Also, don't put a period (`.`) or colon (`:`) at the end of a title or header.
199
200
### Second person
201
172
-When writing documentation, you should use the second person ("you") to give instructions. When using the second person, you give the impression that you're personally leading your reader through the steps or tips in question.
202
+When writing documentation, you should use the second person ("you") to give instructions. When using the second person,
203
+you give the impression that you're personally leading your reader through the steps or tips in question.
204
205
See how that works? It's a core part of making Netdata's documentation feel welcoming to all.
206
@@ -192,7 +223,8 @@ To install Netdata, try the one-line installer...
223
224
Use active voice instead of passive voice, because active voice is more concise and easier to understand.
225
195
-When using voice, the subject of the sentence is performing the action. In passive voice, the subject is being acted upon. A famous example of passive voice is the phrase "mistakes were made."
226
+When using voice, the subject of the sentence is performing the action. In passive voice, the subject is being acted
227
+upon. A famous example of passive voice is the phrase "mistakes were made."
228
229
```
230
# Not recommended (passive)
@@ -204,11 +236,13 @@ When a metric triggers an alarm, Netdata sends a notification...
236
237
### Standard American spelling
238
207
-While the Netdata team is mostly *not* American, we still aspire to use American spelling whenever possible, as it is more commonly used within the monitoring industry.
239
+While the Netdata team is mostly *not* American, we still aspire to use American spelling whenever possible, as it is
240
+more commonly used within the monitoring industry.
241
242
### Clause order
243
211
-If you want to instruct your reader to take some action in a particular circumstance, such as optional steps, the beginning of the sentence should indicate that circumstance.
244
+If you want to instruct your reader to take some action in a particular circumstance, such as optional steps, the
245
+beginning of the sentence should indicate that circumstance.
246
247
```
248
# Not recommended
@@ -218,11 +252,13 @@ Read the reference guide if you'd like to learn more about custom dashboards.
252
If you'd like to learn more about custom dashboards, read the reference guide.
253
```
254
221
-By placing the circumstance at the beginning of the sentence, those who don't want to follow can stop reading and move on. Those who *do* want to read it are less likely to skip over the sentence.
255
+By placing the circumstance at the beginning of the sentence, those who don't want to follow can stop reading and move
256
+on. Those who *do* want to read it are less likely to skip over the sentence.
257
258
### Oxford comma
259
225
-The Oxford comma is the comma used after the second-to-last item in a list of three or more items. It appears just before "and" or "or."
260
+The Oxford comma is the comma used after the second-to-last item in a list of three or more items. It appears just
261
+before "and" or "or."
262
263
```
264
# Not recommended
@@ -234,22 +270,28 @@ Netdata can monitor RAM, disk I/O, MySQL queries per second, and lm-sensors.
270
271
## Markdown syntax
272
237
-The Netdata documentation uses the Markdown syntax for styling and formatting. If you're not familiar with how it works, please read the [Markdown introduction post](https://daringfireball.net/projects/markdown/) by its creator, followed by [Mastering Markdown](https://guides.github.com/features/mastering-markdown/) guide from GitHub.
273
+The Netdata documentation uses the Markdown syntax for styling and formatting. If you're not familiar with how it works,
274
+please read the [Markdown introduction post](https://daringfireball.net/projects/markdown/) by its creator, followed by
275
+[Mastering Markdown](https://guides.github.com/features/mastering-markdown/) guide from GitHub.
276
239
-We also leverage the power of the [Material theme for MkDocs](https://squidfunk.github.io/mkdocs-material/), which features several [extensions](https://squidfunk.github.io/mkdocs-material/extensions/admonition/), such as the ability to create notes, warnings, and collapsible blocks.
277
+We also leverage the power of the [Material theme for MkDocs](https://squidfunk.github.io/mkdocs-material/), which
278
+features several [extensions](https://squidfunk.github.io/mkdocs-material/extensions/admonition/), such as the ability
279
+to create notes, warnings, and collapsible blocks.
280
241
-You can follow the syntax specified in the above resources for the majority of documents, but the following sections specify a few particular use cases.
281
+You can follow the syntax specified in the above resources for the majority of documents, but the following sections
282
+specify a few particular use cases.
283
284
### References to UI elements
285
245
-If you need to instruct your reader to click a user interface (UI) element inside of a Netdata interface, you should reference the label text of the link/button with Markdown's (`**bold text**`) tag.
286
+If you need to instruct your reader to click a user interface (UI) element inside of a Netdata interface, you should
287
+reference the label text of the link/button with Markdown's (`**bold text**`) tag.
288
289
```markdown
290
Click on the **Sign in** button.
291
```
292
251
-!!! note
252
- Whenever possible, avoid using directional language to orient readers, because not every reader can use instructions like "look at the top-left corner" to find their way around an interface.
293
+!!! note Whenever possible, avoid using directional language to orient readers, because not every reader can use
294
+ instructions like "look at the top-left corner" to find their way around an interface.
295
296
```
297
If you feel that you must use directional language, perhaps use an [image](#images) (with proper alt text) instead.
@@ -259,11 +301,17 @@ We're also working to establish standards for how we refer to certain elements o
301
302
### Language-specific syntax highlighting in code blocks
303
262
-Our documentation uses the [Highlight extension](https://facelessuser.github.io/pymdown-extensions/extensions/highlight/) for syntax highlighting. Highlight is fully compatible with [Pygments](http://pygments.org/), allowing you to highlight the syntax within code blocks in a number of interesting ways.
304
+Our documentation uses the [Highlight
305
+extension](https://facelessuser.github.io/pymdown-extensions/extensions/highlight/) for syntax highlighting. Highlight
306
+is fully compatible with [Pygments](http://pygments.org/), allowing you to highlight the syntax within code blocks in a
307
+number of interesting ways.
308
264
-For a full list of languages, see [Pygment's supported languages](http://pygments.org/languages/). Netdata documentation will use the following for the most part: `c`, `python`, `js`, `shell`, `markdown`, `bash`, `css`, `html`, and `go`. If no language is specified, the Highlight extension doesn't apply syntax highlighting.
309
+For a full list of languages, see [Pygment's supported languages](http://pygments.org/languages/). Netdata documentation
310
+will use the following for the most part: `c`, `python`, `js`, `shell`, `markdown`, `bash`, `css`, `html`, and `go`. If
311
+no language is specified, the Highlight extension doesn't apply syntax highlighting.
312
266
-Include the language directly after the three backticks (```` ``` ````) that start the code block. For highlighting C code, for example:
313
+Include the language directly after the three backticks (```` ``` ````) that start the code block. For highlighting C
314
+code, for example:
315
316
````
317
```c
@@ -285,28 +333,37 @@ inline char *health_stock_config_dir(void) {
333
}
334
```
335
288
-You can also use the Highlight and [SuperFences](https://facelessuser.github.io/pymdown-extensions/extensions/superfences/) extensions together to show line numbers or highlight specific lines.
336
+You can also use the Highlight and
337
+[SuperFences](https://facelessuser.github.io/pymdown-extensions/extensions/superfences/) extensions together to show
338
+line numbers or highlight specific lines.
339
290
-Display line numbers by appending `linenums="1"` after the language declaration, replacing `1` with the starting line number of your choice. Highlight lines by appending `hl_lines="2"`, replacing `2` with the line you'd like to highlight. Or, multiple lines: `hl_lines="1 2 4 12`.
340
+Display line numbers by appending `linenums="1"` after the language declaration, replacing `1` with the starting line
341
+number of your choice. Highlight lines by appending `hl_lines="2"`, replacing `2` with the line you'd like to highlight.
342
+Or, multiple lines: `hl_lines="1 2 4 12`.
343
292
-!!! note
293
- Line numbers and highlights are not compatible with GitHub's Markdown parser, and thus will only be viewable on our [documentation site](https://docs.netdata.cloud/). They should be used sparingly and only when necessary.
344
+!!! note Line numbers and highlights are not compatible with GitHub's Markdown parser, and thus will only be viewable on
345
+ our [documentation site](https://docs.netdata.cloud/). They should be used sparingly and only when necessary.
346
347
## Accessibility
348
297
-Netdata's documentation should be as accessible as possible to as many people as possible. While the rules about [tone and content](#tone-and-content) and [language and grammar](#language-and-grammar) are helpful to an extent, we also need some additional rules to improve the reading experience for all readers.
349
+Netdata's documentation should be as accessible as possible to as many people as possible. While the rules about [tone
350
+and content](#tone-and-content) and [language and grammar](#language-and-grammar) are helpful to an extent, we also need
351
+some additional rules to improve the reading experience for all readers.
352
353
### Images
354
355
Images are an important component to documentation, which is why we have a few rules around their usage.
356
303
-Perhaps most importantly, don't use only images to convey instructions. Each image should be accompanied by alt text and text-based instructions to ensure that every reader can access the information in the best way for them.
357
+Perhaps most importantly, don't use only images to convey instructions. Each image should be accompanied by alt text and
358
+text-based instructions to ensure that every reader can access the information in the best way for them.
359
360
#### Alt text
361
307
-Provide alt text for every image you include in Netdata's documentation. It should summarize the intent and content of the image.
362
+Provide alt text for every image you include in Netdata's documentation. It should summarize the intent and content of
363
+the image.
364
309
-In Markdown, use the standard image syntax, `![]()`, and place the alt text between the brackets `[]`. Here's an example using our logo:
365
+In Markdown, use the standard image syntax, `![]()`, and place the alt text between the brackets `[]`. Here's an example
366
+using our logo:
367
368
```
369
@@ -314,6 +371,7 @@ In Markdown, use the standard image syntax, `![]()`, and place the alt text betw
371
372
#### Images of text
373
317
-Don't use images of text, code samples, or terminal output. Instead, put that text content in a code block so that all devices can render it clearly and screen readers can parse it.
374
+Don't use images of text, code samples, or terminal output. Instead, put that text content in a code block so that all
375
+devices can render it clearly and screen readers can parse it.
376
377
[](<>)