Skip to content

Commit db037f1

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 1e3be17 commit db037f1

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
@@ -72,9 +72,23 @@ collapsed or removed entirely from the slide.
7272
will read the course by themselves, so make the notes complete and useful even
7373
when there is no Rust expert around.
7474

75-
- Speaker notes are not a script for the instructor. When teaching the course,
76-
instructors only have a short time to glance at the notes. Don't include full
77-
paragraphs for the instructor to read out loud.
75+
- Speaker notes should serve as a quick reference for instructors, not a
76+
verbatim script. Because instructors have limited time to glance at notes, the
77+
content should be concise and easy to scan.
78+
79+
**Avoid** long, narrative paragraphs meant to be read aloud:
80+
> **Bad:** _"In this example, we define a trait named `StrExt`. This trait has
81+
> a single method, `is_palindrome`, which takes a `&self` receiver and returns
82+
> a boolean value indicating if the string is the same forwards and
83+
> backwards..."_
84+
85+
**Instead, prefer** bullet points with background information or actionable
86+
**teaching prompts**:
87+
> **Good:**
88+
>
89+
> - Note: The `Ext` suffix is a common convention.
90+
> - Ask: What happens if the `use` statement is removed?
91+
> - Demo: Comment out the `use` statement to show the compiler error.
7892
7993
### More to Explore
8094

0 commit comments

Comments
 (0)