- Don't try to teach (less explanation), just do something
- One path, not multiple, no diversions
- Show the learner the goal
- Deliver results often
- Highlight expectations (what should happen vs what should not, if relevant)
- Make sure the tutorial can't fail
- Language
- We ...
- In this tutorial, we will ...
- First, do x. Now, do y. Now that you have done y, do z.
- We must always do x before we do y because... (see Explanation for more details).
- The output should look something like ...
- Notice that ... Remember that ... Let’s check ...
- You have built ...
- For one goal or problem that is relevant for a real-life project
- Also helps to highlight what the product can do
- Do not teach, do not explain, just do
- Theoretical, technical knowledge
- Dry, not personal
- Follow the structure of the product
- Build on a standard layout
- Premise: used as an introduction for the item; presents e.g. the end goal of the page
- Definition: the discussed item's outline, purpose etc.
- Process: the mechanism behind the discussed item; can include e.g. code and/or steps to execute, configure, understand the discussed item
- Not necessarily relevant to the project
- Shows how areas of the product connect, work together (e.g. magic)
- Offer alternative solution to a problem
- Language
- The reason for x is because historically, y ...
- W is better than z, because ...
- An x in system y is analogous to a w in system z. However ...
- Some users prefer w (because z). This can be a good approach, but...
- An x interacts with a y as follows: ...
- Don't use too many levels of heading: no more than 2-3 levels
- Use lists: helps readability
- Make links descriptive: not "click here" or "read more"
- Link to external resources: use full URL, not relative link
- Add a table of contents: easier to navigate content
- Use alt text for images: helps search engines and screen readers
- Semantic line breaks
- A semantic line break MUST occur after a sentence, as punctuated by a period (.), exclamation mark (!), or question mark (?).
- A semantic line break SHOULD occur after an independent clause as punctuated by a comma (,), semicolon (;), colon (:), or em dash (—).