Skip to content

Commit 36c07e3

Browse files
authored
docs: Clarify speaker note style for instructors (#2917)
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 by LLMs 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 4d755f6 commit 36c07e3

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
@@ -226,9 +226,23 @@ collapsed or removed entirely from the slide.
226226

227227
- Where to pause and engage the class with questions.
228228

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

0 commit comments

Comments
 (0)