Docs templates (#12466)
* Add concept template * Add task template * commit pending changes bc I need to switch branch * Upload set of templates for discussion * Amend templates based on feedback * Refinements * Rename _concept-template.md to _concept-page-template.md
Tina Luedtke committed
Apr 20, 2022 at 08:06 UTC
dffa33f83d1f82e074cbe5ba9365d18cbb9e8d2d
4 files changed
+193
docs/.templates/.page-level/_collector-page-template.mdx
new
+68
@@ -0,0 +1,68 @@
1
+<!--
2
+title: $COLLECTOR_NAME monitoring with Netdata
3
+description: Short summary (will be displayed in search engines)
4
+custom_edit_url: Edit URL of the source file
5
+keywords: [keywords, describing, the main topics]
6
+-->
7
+
8
+# Title
9
+
10
+import {
11
+ EnableCollector,
12
+ CollectorDebug,
13
+} from '@site/src/components/Collectors/_collector-components.jsx';
14
+
15
+Short description of what the collector does on a high level.
16
+Why should I use this collector?
17
+
18
+## Configuring $COLLECTOR_NAME
19
+
20
+#### Prerequisites
21
+
22
+List all needed prerequisites:
23
+
24
+- Prerequisite 1
25
+- Prerequisite 2
26
+- Prerequisite 3
27
+
28
+<CollectorConfiguration configURL="" moduleName="PLUGIN/COLLECTOR.conf" />
29
+
30
+### Example
31
+
32
+TODO: Check if we can automatically fetch the [JOBS] section of netdata.conf
33
+
34
+## Other configuration information
35
+
36
+Explain other configuration options, as needed.
37
+
38
+#### Prerequisites
39
+
40
+<!-- If there is only one requirement, use a paragraph instead of a single bullet item. Bullets are social animals and only appear in groups of 2 or more :) -->
41
+
42
+Optional. List all needed prerequisites:
43
+
44
+- Prerequisite 1
45
+- Prerequisite 2
46
+- Prerequisite 3
47
+
48
+To do x:
49
+
50
+1. Step 1 written in active voice
51
+ ```bash
52
+ Code sample for step
53
+ ```
54
+2. Step 2
55
+ Result of step 2, for example a system reaction; written in passive voice
56
+3. Step 3
57
+
58
+## Debugging $COLLECTOR_NAME (optional)
59
+
60
+<CollectorDebug pluginName="" collectorName="" />
61
+
62
+## Metrics and Alerts produced by this collector
63
+
64
+| Chart | Metrics | Alert |
65
+| ---------- | ----------- | ------------------------ |
66
+| Chart Name | Metric name | [Alert 1](Link to alert) |
67
+| Chart Name | Metric name | [Alert 2](Link to alert) |
68
+| Chart Name | Metric name | [Alert 3](Link to alert) |
docs/.templates/.page-level/_concept-page-template.md
new
+30
@@ -0,0 +1,30 @@
1
+<!--
2
+title: Noun that describes the concept
3
+description: Short summary (will be displayed in search engines)
4
+custom_edit_url: Edit URL of the source file
5
+keywords: [keywords, describing, the main topics]
6
+-->
7
+
8
+# Title
9
+
10
+Why should the reader care: “What’s in it for me?”
11
+
12
+## Subheading
13
+
14
+Ideally, try to explain one core idea per section. Questions that you could keep in mind while writing:
15
+
16
+- How does it work?
17
+- What are the outcomes?
18
+- What are the positive and negative effects of it?
19
+- Are there alternatives that provide a similar result?
20
+
21
+## Subheading
22
+
23
+Add more subheadings and anything else that needs to be explained...
24
+Remember, if you start to describe about another concept, stop yourself.
25
+Each concept should be about one concept only.
26
+
27
+<!-- Optional -->
28
+### Related links
29
+<!-- Here, you could include links to task topic that describe how to implement the thing you discussed in this concept. -->
30
+- Visit the [related thing documentation](www.related-thing.com) to learn more about related thing.
docs/.templates/.page-level/_task-page-template.md
new
+41
@@ -0,0 +1,41 @@
1
+<!--
2
+title: Starts with an active verb, like "Create a widget" or "Delete a widget"
3
+description: Short summary (will be displayed in search engines)
4
+custom_edit_url: Edit URL of the source file
5
+keywords: [keywords, describing, the main topics]
6
+-->
7
+# Title
8
+
9
+Short description of why or when the procedure makes sense.
10
+
11
+## Subheading that describes the task
12
+#### Prerequisites
13
+<!-- If there is only one requirement, use a paragraph instead of a single bullet item. Bullets are social animals and only appear in groups of 2 or more :) -->
14
+Optional. List all needed prerequisites:
15
+- Prerequisite 1
16
+- Prerequisite 2
17
+- Prerequisite 3
18
+
19
+To do x:
20
+
21
+1. Step 1 written in active voice
22
+ ```bash
23
+ Code sample for step
24
+ ```
25
+2. Step 2
26
+ Result of step 2, for example a system reaction; written in passive voice
27
+3. Step 3
28
+
29
+## If needed, another task section
30
+
31
+See lines 11-24
32
+
33
+<!-- Optional -->
34
+## What's next?
35
+
36
+Optional section that explains the next logical steps.
37
+
38
+<!-- Optional -->
39
+## Related links
40
+
41
+- Visit the [related thing documentation](www.related-thing.com) to learn more about related thing.
docs/.templates/.page-level/_tutorial-page-template.mdx
new
+54
@@ -0,0 +1,54 @@
1
+<!--
2
+title: Starts with an active verb, like "Create a widget" or "Delete a widget"
3
+description: Short summary (will be displayed in search engines)
4
+custom_edit_url: Edit URL of the source file
5
+author: "Your Name"
6
+author_title: "Your title at Netdata"
7
+author_img: "/img/authors/YourFace.jpg"
8
+keywords: [keywords, describing, the main topics]
9
+-->
10
+
11
+A paragraph that explains what the tutorial does, why it matters, and the expected outcome.
12
+
13
+To achieve goal:
14
+
15
+1. [Do the first task](#first-task)
16
+2. [Do the second task](#second-task)
17
+
18
+## Prerequisites
19
+
20
+<!-- If there is only one requirement, use a paragraph instead of a single bullet item. Bullets are social animals and only appear in groups of 2 or more :) -->
21
+
22
+Optional. List all needed prerequisites:
23
+
24
+- Prerequisite 1
25
+- Prerequisite 2
26
+- Prerequisite 3
27
+
28
+## First task
29
+
30
+To do x:
31
+
32
+1. Step 1 written in active voice
33
+ ```bash
34
+ Code sample for step
35
+ ```
36
+2. Step 2
37
+ Result of step 2, for example a system reaction; written in passive voice
38
+3. Step 3
39
+
40
+## Second task
41
+
42
+To do x:
43
+
44
+1. Step 1 written in active voice
45
+ ```bash
46
+ Code sample for step
47
+ ```
48
+2. Step 2
49
+ Result of step 2, for example a system reaction; written in passive voice
50
+3. Step 3
51
+
52
+## What's next?
53
+
54
+Optional section that explains the next logical steps.