Reference the source code of this document to see how the content was produced.
References¶
<diataxis.fr>¶
Diátaxis is a fantastic resource for writing documentation for various audiences.
Tutorials - The audience of a tutorial is inexperienced. Goal: A successful guided and tightly-controlled hands-on learning experience and target the feeling of doing.
How-to guides - The audience of a how-to is more self-sufficient than the audience of a tutorial. Goal: Help the reader accomplish their own goals. Do we have anything of this type in our workshop?
Reference - The audience of a reference document is looking for specific technical information, like the definition of a word or an API. Goal: Answer questions and provide technical information. E.g. our vocabulary page.
Explanation - The audience of an explanation is seeking deeper understanding. Goal: Provide in-depth understanding of a concept, often linking multiple concepts together or explaining a technical decision, architecture, or history.
Structure¶
All modules should have a consistent structure!
Embedded slides¶
Slides should be the first thing on a given page.
Use a dropdown callout in the following style to embed slides for a module:
“Where we are going”¶
Immediately after the embedded slides, show the learner where they will be going.
It’s important to allow the learner to form an idea of what they will achieve right from the start.
Learning objectives should be phrased as aspirational, not as definite outcomes. Avoid “you will learn...”, as that’s considered an antipattern.
This section should be very short. Aim for 3 sentences max!
Content¶
The “meat” of your materials comes after giving readers a preview of where we are going together.
Authoring¶
What type of audience does your module serve?¶
Is it a tutorial or explanation?
Include this information in the document front-matter.
---
subject: "Tutorial"
authors:
# ...
---Follow the Diátaxis principles for your audience!
Vocabulary¶
All vocabulary should be defined in the 🔍 Vocabulary page. Follow the pre-existing pattern to add new terms.
References should be conscious of case. By default, when referencing a term, the same case that’s used in the definition will be used in the reference. For example:
Instead:
Similarly, if you want to use a plural or other alternate form of a term:
Headings¶
Use consistent heading structure so that the generated document outline on the right pane can be used for navigation.
Use “Title Case” only for
h1headers (single#).Use “Sentence case” for all other headers.
Emojis¶
Use emojis in document titles.
For repeated elements, use emojis.
Steps¶
Use 🔧 in a header to indicate a step.
Testing¶
Use 🧪 in a header to indicate that the reader should stop to test their work.
Noticing¶
Use 👀 in a callout to indicate that the user should notice something, e.g. a UI element or CLI output. E.g.:
Voice / language¶
Tutorials¶
“We...”¶
Use “we” language to reinforce that we, learner and instructor, are on a journey together.
“See ... for details”¶
Tutorials should minimize explanation (ruthlessly). Reference other materials (e.g. vocabulary) for readers who are seeking deeper understanding.
“Notice” / “remember”¶
Provide many opportunities for learners to see results (deliver visible results early and often). Help readers verify that what they’re seeing is what they should be seeing (point out what the learner should notice) Regularly reinforce important concepts (encourage and permit repetition).
Explanation¶
“The reason for...”¶
Explain why! Provide context.
“X is better than Y because...”¶
Make judgements, share your opinions and perspective.
“X interacts with Y...”¶
Make connections to build a network of understanding, a mental model, for your readers.