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
Copy file name to clipboardExpand all lines: contribution-templates/README.md
+48-49Lines changed: 48 additions & 49 deletions
Original file line number
Diff line number
Diff line change
@@ -52,6 +52,50 @@ Please read the [Arduino Style Guide](https://docs.arduino.cc/hacking/software/A
52
52
53
53
# Documentation Style Guidelines
54
54
55
+
## Format Guidelines
56
+
57
+
### Tutorial Guidelines
58
+
59
+
To write a tutorial for the Arduino Documentation website, you should follow these guidelines:
60
+
61
+
|Section|Rules|Description|Example|
62
+
|-------|-----|-----------|-------|
63
+
|**Frontmatter**|You must fill in title, description and author. The others are voluntary.|Here is where you add the metadata of your tutorial. This is including the author, title of tutorial, compatible libraries, compatible hardware etc.||
64
+
|**Introduction**|This is an h2 heading. <br><br> You should not change the name of the heading.|The Introduction to the tutorial should be a maximum of three sentences long and be well descriptive of what the reader can expect of the tutorial.||
65
+
|**Goals**|This is an h2 heading. <br><br> You should not change the name of the heading.|What are the goals of this tutorial? What should the reader be able to do at the end?||
66
+
|**Hardware & Software Needed**|This is an h2 heading. <br><br> You should not change the name of the heading.|Here you set the hardware and software you need to continue your tutorial. You are more than welcome to link the Arduino based software and hardware to the respective store or downloads page.||
67
+
|**Circuit/Schematic**|This is an h2 heading. <br><br> You should not change the name of the heading.|Here you add the circuits and/or schematics of your tutorial.||
68
+
|**Focus Feature**|This is an h2 heading. <br><br> Here you are allowed to use as many h3 headings as you want, to be able to divide your content into easier to read sections. <br><br> You can add up to three Focus Feature headings in your tutorial. <br><br> This is the only heading you are allowed to modify.|This sections heading should be updated to the main focus of your tutorial. This is where the information about the focus start.||
69
+
|**Programming the Board**|This is an h2 heading. <br><br> You should not change the name of the heading.|This is the section where you go through the code of your tutorial. ||
70
+
|**Testing it Out**|This is an h2 heading. <br><br> You should not change the name of the heading.|This is the experimental part of your tutorial, where the reader is supposed to test out the code and focus of your tutorial.||
71
+
|**Troubleshoot**|This is an h3 heading. <br><br> You should not change the name of the heading.|If there are something in your tutorial that you know people might get stuck on, or get wrong, this is the section where you give suggestion on how the reader can troubleshoot.||
72
+
|**Conclusion**|This is an h2 heading. <br><br> You should not change the name of the heading.|This is where you summarize your tutorial in a few sentences. What is it that you hoped to have taught or shown the reader?||
73
+
74
+
### How To Guidelines
75
+
76
+
To write a How To for the Arduino Documentation website, you should follow these guidelines:
77
+
78
+
|Section|Rules|Description|Example|
79
+
|-------|-----|-----------|-------|
80
+
|**Frontmatter**|You must fill in title, description and author. The others are voluntary.|Here is where you add the metadata of your How To. This is including the author, title of How To, compatible libraries, compatible hardware etc. <br><br> You must fill in title, description and author. The others are voluntary. **Note** that you must remove the sections in the frontmatter which are empty.||
81
+
|**Introduction**|This is an h2 heading. <br><br> You should not change the name of the heading.|The Introduction to the tutorial should be a maximum of three sentences long and be well descriptive of what the reader can expect of the How To.||
82
+
|**Hardware & Software Needed**|This is an h2 heading. <br><br> You should not change the name of the heading.|Here you set the hardware and software you need to continue your How To. You are more than welcome to link the Arduino based software and hardware to the respective store or downloads page.||
83
+
|**Circuit**|This is an h2 heading. <br><br> You should not change the name of the heading.|Here you add the circuit/s and of your How To.||
84
+
|**Schematic**|This is an h2 heading. <br><br> You should not change the name of the heading.|Here you add the schematic/s and of your How To.||
85
+
|**Code**|This is an h2 heading. <br><br> You should not change the name of the heading.|This is where you add your sketch code as well as the descriptive text explaining what the code does and is used for.||
86
+
|**Learn more**|This is an h2 heading. <br><br> You should not change the name of the heading.|This is where you link to more information that the reader could be interested in. This could for example be other tutorials that delve deeper into the same topic, or a project that focus on the learnings of this How To.||
87
+
88
+
### Article Guidelines
89
+
90
+
To write a article for the Arduino Documentation website, you should follow these guidelines:
91
+
92
+
|Section|Rules|Description|Example|
93
+
|-------|-----|-----------|-------|
94
+
|**Frontmatter**|You must fill in title, description and author. The others are voluntary.|Here is where you add the metadata of your article. This is including the author, title of tutorial, compatible libraries, compatible hardware etc.||
95
+
|**Introduction**|This is an h2 heading. <br><br> You should not change the name of the heading.|The Introduction should be a maximum of three sentences long and be well descriptive of what the reader can expect of the article.||
96
+
|**Hardware & Software Needed**|This is an h2 heading. <br><br> You can modify the heading if your article only requires one of the two, either Hardware or Software.|Here you set the hardware and software you need to continue your tutorial. You are more than welcome to link the Arduino based software and hardware to the respective store or downloads page.||
97
+
|**Circuit/Schematic**|This is an h2 heading. <br><br> You should not change the name of the heading.|Here you add the circuits and/or schematics of your tutorial.| <br><br> |
98
+
55
99
## Markdown
56
100
57
101
We write all of our content in markdown. To be able to contribute properly to our website, we suggest you to do the same. Practice your markdown skills here: https://commonmark.org/help/tutorial/
@@ -72,9 +116,9 @@ You should use the following markdown styling for our content:
72
116
73
117
***Note that we are not including cursive writing as a markdown style. We implore you not to use cursive as a means to highlight text. Instead use bold.***
74
118
75
-
---
119
+
<!--
76
120
77
-
## Graphics
121
+
## Graphics
78
122
79
123
All graphics should be **1920x1080**. All graphics are stored in an assets folder in the documentation folder. See section **Naming Guidelines**.
80
124
@@ -83,6 +127,8 @@ All graphics should be **1920x1080**. All graphics are stored in an assets folde
83
127
|Circuit/Schematic|**Circuit diagrams** represent how Arduino products work with components in order to function. <br> A **schematic** is a stylized electronic diagram explaining electric circuits.|Please follow [this]() guide on how to create your own Arduino approved circuit diagrams and schematics.|<br>|
84
128
|Screenshot|**Screenshots** are most often used to show the program in the Arduino IDE or any other chosen software.|Please follow [this]() guide on how to create your own Arduino approved screenshots.|<br><br>|
85
129
130
+
-->
131
+
86
132
## Naming Guidelines
87
133
88
134
### Files
@@ -110,50 +156,3 @@ There is no specific way you need to name the images, however it is a good pract
110
156
`UNO-Mini-LE-external-power.png`
111
157
112
158
`rp2040-ap-mode-img-01.png`
113
-
114
-
## Format Guidelines
115
-
116
-
### Tutorial Guidelines
117
-
118
-
To write a tutorial for the Arduino Documentation website, you should follow these guidelines:
119
-
120
-
|Section|Rules|Description|Example|
121
-
|-------|-----|-----------|-------|
122
-
|**Frontmatter**|You must fill in title, description and author. The others are voluntary.|Here is where you add the metadata of your tutorial. This is including the author, title of tutorial, compatible libraries, compatible hardware etc.||
123
-
|**Introduction**|This is an h2 heading. <br><br> You should not change the name of the heading.|The Introduction to the tutorial should be a maximum of three sentences long and be well descriptive of what the reader can expect of the tutorial.||
124
-
|**Goals**|This is an h2 heading. <br><br> You should not change the name of the heading.|What are the goals of this tutorial? What should the reader be able to do at the end?||
125
-
|**Hardware & Software Needed**|This is an h2 heading. <br><br> You should not change the name of the heading.|Here you set the hardware and software you need to continue your tutorial. You are more than welcome to link the Arduino based software and hardware to the respective store or downloads page.||
126
-
|**Circuit/Schematic**|This is an h2 heading. <br><br> You should not change the name of the heading.|Here you add the circuits and/or schematics of your tutorial.||
127
-
|**Focus Feature**|This is an h2 heading. <br><br> Here you are allowed to use as many h3 headings as you want, to be able to divide your content into easier to read sections. <br><br> You can add up to three Focus Feature headings in your tutorial. <br><br> This is the only heading you are allowed to modify.|This sections heading should be updated to the main focus of your tutorial. This is where the information about the focus start.||
128
-
|**Programming the Board**|This is an h2 heading. <br><br> You should not change the name of the heading.|This is the section where you go through the code of your tutorial. ||
129
-
|**Testing it Out**|This is an h2 heading. <br><br> You should not change the name of the heading.|This is the experimental part of your tutorial, where the reader is supposed to test out the code and focus of your tutorial.||
130
-
|**Troubleshoot**|This is an h3 heading. <br><br> You should not change the name of the heading.|If there are something in your tutorial that you know people might get stuck on, or get wrong, this is the section where you give suggestion on how the reader can troubleshoot.||
131
-
|**Conclusion**|This is an h2 heading. <br><br> You should not change the name of the heading.|This is where you summarize your tutorial in a few sentences. What is it that you hoped to have taught or shown the reader?||
132
-
133
-
### How To Guidelines
134
-
135
-
To write a How To for the Arduino Documentation website, you should follow these guidelines:
136
-
137
-
|Section|Rules|Description|Example|
138
-
|-------|-----|-----------|-------|
139
-
|**Frontmatter**|You must fill in title, description and author. The others are voluntary.|Here is where you add the metadata of your How To. This is including the author, title of How To, compatible libraries, compatible hardware etc. <br><br> You must fill in title, description and author. The others are voluntary. **Note** that you must remove the sections in the frontmatter which are empty.||
140
-
|**Introduction**|This is an h2 heading. <br><br> You should not change the name of the heading.|The Introduction to the tutorial should be a maximum of three sentences long and be well descriptive of what the reader can expect of the How To.||
141
-
|**Hardware & Software Needed**|This is an h2 heading. <br><br> You should not change the name of the heading.|Here you set the hardware and software you need to continue your How To. You are more than welcome to link the Arduino based software and hardware to the respective store or downloads page.||
142
-
|**Circuit**|This is an h2 heading. <br><br> You should not change the name of the heading.|Here you add the circuit/s and of your How To.||
143
-
|**Schematic**|This is an h2 heading. <br><br> You should not change the name of the heading.|Here you add the schematic/s and of your How To.||
144
-
|**Code**|This is an h2 heading. <br><br> You should not change the name of the heading.|This is where you add your sketch code as well as the descriptive text explaining what the code does and is used for.||
145
-
|**Learn more**|This is an h2 heading. <br><br> You should not change the name of the heading.|This is where you link to more information that the reader could be interested in. This could for example be other tutorials that delve deeper into the same topic, or a project that focus on the learnings of this How To.||
146
-
147
-
### Article Guidelines
148
-
149
-
To write a article for the Arduino Documentation website, you should follow these guidelines:
150
-
151
-
# Structure
152
-
153
-
|Section|Rules|Description|Example|
154
-
|-------|-----|-----------|-------|
155
-
|**Frontmatter**|You must fill in title, description and author. The others are voluntary.|Here is where you add the metadata of your article. This is including the author, title of tutorial, compatible libraries, compatible hardware etc.||
156
-
|**Introduction**|This is an h2 heading. <br><br> You should not change the name of the heading.|The Introduction should be a maximum of three sentences long and be well descriptive of what the reader can expect of the article.||
157
-
|**Hardware & Software Needed**|This is an h2 heading. <br><br> You can modify the heading if your article only requires one of the two, either Hardware or Software.|Here you set the hardware and software you need to continue your tutorial. You are more than welcome to link the Arduino based software and hardware to the respective store or downloads page.||
158
-
|**Circuit/Schematic**|This is an h2 heading. <br><br> You should not change the name of the heading.|Here you add the circuits and/or schematics of your tutorial.| <br><br> |
Copy file name to clipboardExpand all lines: contribution-templates/how-to-template/how-to-template.md
+5-2Lines changed: 5 additions & 2 deletions
Original file line number
Diff line number
Diff line change
@@ -16,7 +16,7 @@ software:
16
16
- iot-cloud
17
17
---
18
18
19
-
Update the frontmatter above with information that fits your article. Remove the section that are not relevant or filled in. Note that you must at least fill in the title, description and author.
19
+
Update the frontmatter above with information that fits your article. Remove the section that are not relevant or filled in. Note that you **must** at least fill in the title, description and author. Remove the sections that are not filled in.
20
20
21
21
## Introduction
22
22
@@ -28,16 +28,19 @@ List the hardware and software needed. This could be the IDEs, libraries but als
28
28
29
29
- Arduino IDE ([online](https://create.arduino.cc/) or [offline](https://www.arduino.cc/en/main/software)).
Copy file name to clipboardExpand all lines: contribution-templates/tutorial-template/tutorial-template.md
+5-4Lines changed: 5 additions & 4 deletions
Original file line number
Diff line number
Diff line change
@@ -16,7 +16,7 @@ software:
16
16
- iot-cloud
17
17
---
18
18
19
-
Update the frontmatter above with information that fits your tutorial. Remove the section that are not relevant or filled in. Note that you must at least fill in the title, description and author.
19
+
Update the frontmatter above with information that fits your tutorial. Remove the section that are not relevant or filled in. Note that you **must** at least fill in the title, description and author. Remove the sections that are not filled in.
20
20
21
21
## Introduction
22
22
@@ -42,11 +42,13 @@ List the hardware and software needed. This could be the IDEs, libraries but als
42
42
43
43
Add the image of the circuit here. This section should not need any text following the image, only a well thought alternative image text.
44
44
45
-
45
+
![Well thought out alternative image text.]()
46
46
47
47
## Focus Feature
48
48
49
-
This is the only heading you should rename to what the feature is about. Talk about the first feature you want this tutorial to highlight. You can use step-by-step instructions, images or code snippets to show examples. You can use subheading h3 here as well. You can also add how many of the "Focus Feature" headings as needed, however as the tutorials only focus on minimal features - this amount should not be higher than three.
49
+
This is the **only** heading you should rename to what the feature is about. Talk about the first feature you want this tutorial to highlight. You can use step-by-step instructions, images or code snippets to show examples. You can use subheading h3 here as well.
50
+
51
+
You can also add how many of the "Focus Feature" headings as needed, however as tutorials only focus on minimal features, we recommend to only adding a maximum of three "Focus Feature" headings.
50
52
51
53
## Programming the Board
52
54
@@ -58,7 +60,6 @@ After uploading the code, we should now start using it. Go through the flow with
58
60
59
61
### Troubleshoot
60
62
61
-
62
63
Add a bullet list of the things that could be the potential issue for something not working.
63
64
64
65
If the code is not working, there are some common issues we can troubleshoot:
0 commit comments