You've already forked comprehensive-rust
mirror of
https://github.com/google/comprehensive-rust.git
synced 2025-10-09 10:55:26 +02:00
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.
This commit is contained in:
20
STYLE.md
20
STYLE.md
@@ -226,9 +226,23 @@ collapsed or removed entirely from the slide.
|
||||
|
||||
- Where to pause and engage the class with questions.
|
||||
|
||||
- Speaker notes are not a script for the instructor. When teaching the course,
|
||||
instructors only have a short time to glance at the notes. Don't include full
|
||||
paragraphs for the instructor to read out loud.
|
||||
- Speaker notes should serve as a quick reference for instructors, not a
|
||||
verbatim script. Because instructors have limited time to glance at notes, the
|
||||
content should be concise and easy to scan.
|
||||
|
||||
**Avoid** long, narrative paragraphs meant to be read aloud:
|
||||
> **Bad:** _"In this example, we define a trait named `StrExt`. This trait has
|
||||
> a single method, `is_palindrome`, which takes a `&self` receiver and returns
|
||||
> a boolean value indicating if the string is the same forwards and
|
||||
> backwards..."_
|
||||
|
||||
**Instead, prefer** bullet points with background information or actionable
|
||||
**teaching prompts**:
|
||||
> **Good:**
|
||||
>
|
||||
> - Note: The `Ext` suffix is a common convention.
|
||||
> - Ask: What happens if the `use` statement is removed?
|
||||
> - Demo: Comment out the `use` statement to show the compiler error.
|
||||
|
||||
- Nevertheless, include all of the necessary teaching prompts for the instructor
|
||||
in the speaker notes. Unlike the main content, the speaker notes don't have to
|
||||
|
Reference in New Issue
Block a user