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
* I kept the name of my tutorial short. For a small explanation of my tutorial, I used sub-topics.
3
+
* I described what I wanted to train in a few words and clearly state the objective of my tutorial. This should give the reader an idea of what to expect from my tutorial and help them to determine if they really want to learn this topic.
4
+
* I addressed the user directly.
5
+
* I was clear and concise in my writing.
6
+
* I provided links for further related topics.
7
+
* I did not just copy and paste the documentation into a tutorial. I broke down the information into smaller and more simple packages.
8
+
* I want to teach something. Therefore, I did not just write down the steps and results but explained why this step was necessary.
9
+
* I rather made many small steps than a few big steps.
10
+
* I used images and code examples in my tutorial which were provided in the devonfw documentation. Plain text gets boring after time.
11
+
* I used an organized structure in my tutorial.
12
+
* All the things that the user should do actively, I have always written with function calls and steps . I have not given any instructions for action in text form.
13
+
* I proofread my tutorial:
14
+
1. Are the steps available and in the correct order?
15
+
1. Are there any spelling mistakes?
16
+
1. Does everything make sense?
17
+
* I ran through the latest update of my tutorial in Katacoda-Dev and checked if everything was working as intended BEFORE requesting a review.
18
+
19
+
# **Technical**
20
+
* The files that were used in `nextKatacodaStep `are available in `.asciidoc` files and do not contain Katacoda Syntax. `nextKatacodaStep` is almost never needed.
21
+
* Commands like `--- cd devonfw {{execute T1}} ---` should not be used, as it could break certain functions.
22
+
23
+
# Different types of tutorials
24
+
* “Learning”: The user gets a detailed explanation of certain code/feature/functionality.
25
+
* “Quick Start”: Implementing code/feature without comprehensive explanation
26
+
* “Try Out”: The user gets a working sample project (like MyThaiStar), suitable for showcasing functionalities and ease of use.
27
+
28
+
# **Additional things to consider**
29
+
30
+
### Only for Learning-tutorials:
31
+
32
+
* I provided a detailed explanation of the topic in a way, that everybody can understand it.
33
+
* I used more theory and less practice.
34
+
35
+
### Only for Quick Start-tutorials:
36
+
37
+
* I implemented a certain functionality straightforward without any comprehensive explanation.
38
+
* I emphasized practice, and used less theory.
39
+
* I only provided the information which is really needed to understand what I did in the tutorial.
40
+
* For comprehensive explanation of the everything what I have done in the tutorial, I provide links to either the devonfw documentation or the specific Learning-tutorial of the topic (if there is any).
41
+
42
+
### Only for Try Out-tutorials:
43
+
44
+
* I wanted to showcase a certain sample project/feature and its capabilities in a fast and straightforward way to the reader. Example: Tutorial for launching MyThaiStar, so the reader can click through it, and see what is possible.
45
+
* I provided little explanation of the things done in the tutorial.
Copy file name to clipboardExpand all lines: documentation/Tutorials.md
+23Lines changed: 23 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,6 +9,7 @@ Every tutorial has three main parts
9
9
* at least one step
10
10
Additionally, there are optional parts
11
11
* a subtitle
12
+
* tags
12
13
* a conclusion of the tutorial. This will be shown at the last page and can be used to summarize the learned, to foreshadow the next steps on the learning path or to mention useful sources.
13
14
14
15
The tutorials are written in asciidoc files.
@@ -94,6 +95,22 @@ functionName2(parameters)
94
95
--
95
96
```
96
97
98
+
To display images within a step, you can use either the [displayContent](https://github.com/devonfw-tutorials/tutorial-compiler/wiki/Functions#displayContent) function or the following syntax in the index.asciidoc file:
99
+
```
100
+
101
+
```
102
+
The image must be in a folder called `images` in the folder of the playbook (see [Structure](https://github.com/devonfw-tutorials/tutorial-compiler/wiki/Structure)).
103
+
104
+
There is the option to add tags to your tutorials. To do that, you have to add the following syntax after the title or if you have specified a subtitle, after the subtitle.
105
+
106
+
````
107
+
[tags]
108
+
--
109
+
tagType=tag0;tag1
110
+
tagType=tag0;tag1;tag2
111
+
--
112
+
```
113
+
97
114
You can also add an optional conclusion text, which is shown on completion of the tutorial. Use this to summarize the important content of the tutorial, to point out what to learn next or to mention other useful informations.
98
115
99
116
To do that, you have to provide the conclusion at the end of the tutorial (after the last step) surrounded by ```====```.
@@ -110,11 +127,17 @@ These blocks are combined to a complete tutorial.
0 commit comments