Skip to content

Commit 2fd147d

Browse files
mfisher87mfisher87
committed
Add style guide
1 parent e5fe0ff commit 2fd147d

File tree

2 files changed

+172
-0
lines changed

2 files changed

+172
-0
lines changed

‎for-instructors/style-guide.md‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
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+
### Headings
119+
120+
* Use consistent heading structure so that the generated document outline on the right
121+
pane can be used for navigation.
122+
* Use "Title Case" only for `h1` headers (single `#`).
123+
* Use "Sentence case" for all other headers.
124+
125+
126+
### Voice / language
127+
128+
#### [Tutorials](https://diataxis.fr/tutorials/)
129+
130+
##### "We..."
131+
132+
Use "we" language to reinforce that we, learner and instructor, are on a journey
133+
together.
134+
135+
136+
##### "See ... for details"
137+
138+
Tutorials should
139+
[minimize explanation (ruthlessly)](https://diataxis.fr/tutorials/#ruthlessly-minimise-explanation).
140+
Reference other materials (e.g. vocabulary) for readers who are seeking deeper understanding.
141+
142+
143+
##### "Notice" / "remember"
144+
145+
Provide many opportunities for learners to see results ([deliver visible results early
146+
and often](https://diataxis.fr/tutorials/#deliver-visible-results-early-and-often)).
147+
Help readers verify that what they're seeing is what they should be seeing ([point out
148+
what the learner should notice](https://diataxis.fr/tutorials/#point-out-what-the-learner-should-notice))
149+
Regularly reinforce important concepts ([encourage and permit
150+
repetition](https://diataxis.fr/tutorials/#encourage-and-permit-repetition)).
151+
152+
153+
#### [Explanation](https://diataxis.fr/explanation)
154+
155+
##### "The reason for..."
156+
157+
Explain _why_!
158+
[Provide context](https://diataxis.fr/explanation/#provide-context).
159+
160+
161+
##### "X is better than Y because..."
162+
163+
Make judgements, [share your opinions and perspective](https://diataxis.fr/explanation/#admit-opinion-and-perspective).
164+
165+
166+
##### "X interacts with Y..."
167+
168+
[Make connections](https://diataxis.fr/explanation/#make-connections) to build a network
169+
of understanding, a mental model, for your readers.

‎myst.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,9 @@ project:
1616
- title: "Materials"
1717
children:
1818
- file: "04-materials/01-working-in-jupyterhub/CryoCloud_demo.ipynb"
19+
- title: "For instructors"
20+
children:
21+
- pattern: "for-instructors/*.md"
1922

2023

2124
site:

0 commit comments

Comments
 (0)