Skip to content

Commit 74396fe

Browse files
mfisher87mfisher87
authored
Add style guide (#13)
1 parent 5123583 commit 74396fe

File tree

2 files changed

+247
-0
lines changed

2 files changed

+247
-0
lines changed

‎for-instructors/style-guide.md‎

Lines changed: 244 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,244 @@
1+
# 🎨 Style guide
2+
3+
Reference the source code of this document to see how the content was produced.
4+
5+
:::{note}
6+
The [`{myst}` directive](https://mystmd.org/guide/directives#directive-myst) is
7+
being used to show both source code and the rendered output in this document;
8+
please do not use the `{myst}` directive in your module.
9+
:::
10+
11+
12+
## References
13+
14+
### <diataxis.fr>
15+
16+
Diátaxis is a fantastic resource for writing documentation for various audiences.
17+
18+
* [Tutorials](https://diataxis.fr/tutorials/) -
19+
The audience of a tutorial is inexperienced.
20+
Goal: A successful guided and tightly-controlled hands-on learning experience and
21+
[target the feeling of doing](https://diataxis.fr/tutorials/#target-the-feeling-of-doing).
22+
* [How-to guides](https://diataxis.fr/how-to-guides/) -
23+
The audience of a how-to is more self-sufficient than the audience of a tutorial.
24+
Goal: Help the reader accomplish their own goals.
25+
_Do we have anything of this type in our workshop?_
26+
* [Reference](https://diataxis.fr/reference/) -
27+
The audience of a reference document is looking for specific technical information,
28+
like the definition of a word or an API.
29+
Goal: Answer questions and provide technical information.
30+
_E.g. our vocabulary page._
31+
* [Explanation](https://diataxis.fr/explanation/) -
32+
The audience of an explanation is seeking deeper understanding.
33+
Goal: Provide in-depth understanding of a concept, often linking multiple concepts
34+
together or explaining a technical decision, architecture, or history.
35+
36+
37+
## Structure
38+
39+
All modules should have a consistent structure!
40+
41+
42+
### Embedded slides
43+
44+
Slides should be the first thing on a given page.
45+
46+
Use a [dropdown callout](https://mystmd.org/guide/admonitions#admonition-dropdown) in
47+
the following style to embed slides for a module:
48+
49+
```{myst}
50+
:::{note} 🛝 Slides
51+
:icon: false
52+
:class: dropdown
53+
54+
<iframe
55+
src="https://docs.google.com/presentation/d/e/2PACX-1vRPPScGGDg9PKQiEQGCj5GWSt5TnrHUyTOPoSRKrLAs9sXKuj2BTwc4SzCpXYrDE2p6B7hpRFgpoguC/pubembed?start=false&loop=false&delayms=60000"
56+
frameborder="0"
57+
width="960"
58+
height="569"
59+
allowfullscreen="true"
60+
mozallowfullscreen="true"
61+
webkitallowfullscreen="true">
62+
</iframe>
63+
:::
64+
```
65+
66+
67+
### "Where we are going"
68+
69+
Immediately after the embedded slides,
70+
[show the learner where they will be going](https://diataxis.fr/tutorials/#show-the-learner-where-they-ll-be-going).
71+
72+
> It’s important to allow the learner to form an idea of what they will achieve right
73+
> from the start.
74+
75+
Learning objectives should be phrased as aspirational, not as definite outcomes.
76+
Avoid "you will learn...", as that's considered an antipattern.
77+
78+
This section should be very short.
79+
Aim for 3 sentences max!
80+
81+
```{myst}
82+
:::{tip} 🧭 Where we are going
83+
:icon: false
84+
85+
_This example is © and provided by Daniele Procida @ <diataxis.fr>_
86+
87+
In this tutorial we will create and deploy a scalable web application.
88+
Along the way we will encounter containerisation tools and services.
89+
:::
90+
```
91+
92+
93+
### Content
94+
95+
The "meat" of your materials comes after giving readers a preview of where we are going
96+
together.
97+
98+
99+
## Authoring
100+
101+
### What type of audience does your module serve?
102+
103+
Is it a tutorial or explanation?
104+
105+
Include this information in the document front-matter.
106+
107+
```yaml
108+
---
109+
subject: "Tutorial"
110+
authors:
111+
# ...
112+
---
113+
```
114+
115+
Follow the [Diátaxis](https://diataxis.fr) principles for your audience!
116+
117+
118+
### Vocabulary
119+
120+
All vocabulary should be defined in the [](../03-vocabulary.md) page.
121+
Follow the pre-existing pattern to add new terms.
122+
123+
References should be conscious of case.
124+
By default, when referencing a term, the same case that's used in the definition will be
125+
used in the reference.
126+
For example:
127+
128+
```{myst}
129+
:::{glossary}
130+
Example term
131+
: Example definition
132+
:::
133+
134+
Using {term}`example term` in a sentence, the case is usually incorrect.
135+
```
136+
137+
Instead:
138+
139+
```{myst}
140+
:::{glossary}
141+
Example term
142+
: Example definition
143+
:::
144+
145+
We can explicitly define the case of our {term}`example term <example term>`.
146+
```
147+
148+
Similarly, if you want to use a plural or other alternate form of a term:
149+
150+
```{myst}
151+
:::{glossary}
152+
Example term
153+
: Example definition
154+
:::
155+
156+
Why can't I hold all these {term}`example terms <example term>`?!
157+
```
158+
159+
160+
### Headings
161+
162+
* Use consistent heading structure so that the generated document outline on the right
163+
pane can be used for navigation.
164+
* Use "Title Case" only for `h1` headers (single `#`).
165+
* Use "Sentence case" for all other headers.
166+
167+
168+
### Emojis
169+
170+
Use emojis in document titles.
171+
172+
For repeated elements, use emojis.
173+
174+
175+
#### Steps
176+
177+
Use 🔧 in a header to indicate a step.
178+
179+
180+
#### Testing
181+
182+
Use 🧪 in a header to indicate that the reader should stop to test their work.
183+
184+
185+
#### Noticing
186+
187+
Use 👀 in a callout to indicate that the user should notice something, e.g. a UI element
188+
or CLI output.
189+
E.g.:
190+
191+
```{myst}
192+
:::{important} 👀 You should notice...
193+
:class: simple
194+
:icon: false
195+
196+
...these commands produce no output when successful.
197+
:::
198+
```
199+
200+
201+
### Voice / language
202+
203+
#### [Tutorials](https://diataxis.fr/tutorials/)
204+
205+
##### "We..."
206+
207+
Use "we" language to reinforce that we, learner and instructor, are on a journey
208+
together.
209+
210+
211+
##### "See ... for details"
212+
213+
Tutorials should
214+
[minimize explanation (ruthlessly)](https://diataxis.fr/tutorials/#ruthlessly-minimise-explanation).
215+
Reference other materials (e.g. vocabulary) for readers who are seeking deeper understanding.
216+
217+
218+
##### "Notice" / "remember"
219+
220+
Provide many opportunities for learners to see results ([deliver visible results early
221+
and often](https://diataxis.fr/tutorials/#deliver-visible-results-early-and-often)).
222+
Help readers verify that what they're seeing is what they should be seeing ([point out
223+
what the learner should notice](https://diataxis.fr/tutorials/#point-out-what-the-learner-should-notice))
224+
Regularly reinforce important concepts ([encourage and permit
225+
repetition](https://diataxis.fr/tutorials/#encourage-and-permit-repetition)).
226+
227+
228+
#### [Explanation](https://diataxis.fr/explanation)
229+
230+
##### "The reason for..."
231+
232+
Explain _why_!
233+
[Provide context](https://diataxis.fr/explanation/#provide-context).
234+
235+
236+
##### "X is better than Y because..."
237+
238+
Make judgements, [share your opinions and perspective](https://diataxis.fr/explanation/#admit-opinion-and-perspective).
239+
240+
241+
##### "X interacts with Y..."
242+
243+
[Make connections](https://diataxis.fr/explanation/#make-connections) to build a network
244+
of understanding, a mental model, for your readers.

‎myst.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,9 @@ project:
1717
- title: "Materials"
1818
children:
1919
- pattern: "materials/0*/index.md"
20+
- title: "For instructors"
21+
children:
22+
- pattern: "for-instructors/*.md"
2023

2124

2225
site:

0 commit comments

Comments
 (0)