Skip to content

Commit 3a0a1bf

Browse files
committed
docs: Clarify speaker note style for instructors
The previous STYLE.md advised against using speaker notes as a 'script' but didn't provide clear examples of what that meant. This could be interpreted as disallowing any kind of instructor prompt. This change clarifies the guideline by: 1. Distinguishing between long-form, verbatim 'scripts' (bad) and short, actionable 'teaching prompts' (good). 2. Providing concrete 'good' and 'bad' examples to make the distinction unambiguous for future contributors.
1 parent 4ffd664 commit 3a0a1bf

File tree

1 file changed

+17
-3
lines changed

1 file changed

+17
-3
lines changed

STYLE.md

Lines changed: 17 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -220,9 +220,23 @@ collapsed or removed entirely from the slide.
220220

221221
- Where to pause and engage the class with questions.
222222

223-
- Speaker notes are not a script for the instructor. When teaching the course,
224-
instructors only have a short time to glance at the notes. Don't include full
225-
paragraphs for the instructor to read out loud.
223+
- Speaker notes should serve as a quick reference for instructors, not a
224+
verbatim script. Because instructors have limited time to glance at notes, the
225+
content should be concise and easy to scan.
226+
227+
**Avoid** long, narrative paragraphs meant to be read aloud:
228+
> **Bad:** _"In this example, we define a trait named `StrExt`. This trait has
229+
> a single method, `is_palindrome`, which takes a `&self` receiver and returns
230+
> a boolean value indicating if the string is the same forwards and
231+
> backwards..."_
232+
233+
**Instead, prefer** bullet points with background information or actionable
234+
**teaching prompts**:
235+
> **Good:**
236+
>
237+
> - Note: The `Ext` suffix is a common convention.
238+
> - Ask: What happens if the `use` statement is removed?
239+
> - Demo: Comment out the `use` statement to show the compiler error.
226240
227241
- Nevertheless, include all of the necessary teaching prompts for the instructor
228242
in the speaker notes. Unlike the main content, the speaker notes don't have to

0 commit comments

Comments
 (0)