docs(style): Overhaul STYLE.md with course philosophy and principles (#2919)

Make STYLE.md a comprehensive guide for contributors by incorporating
the core,
public-facing principles from the internal design document. This ensures
that a
ll contributions align with the course's pedagogical goals and
structure.

The key additions and changes include:

- **Add "Course Philosophy and Design" Section:**
  - Define the target audience (experienced SWEs new to Rust).
  - State the course goals (solid foundation in a bounded time).
  - Codify the core pedagogical principles:
    - Build on a Foundation
    - Provide a Working Mental Model (The "No Magic" Rule)
    - Use a Spiral Approach

- **Define Course Structure and Pacing:**
- Add a "Pacing and Structure" section explaining the 5-hour daily
schedule and the `minutes` frontmatter convention.
- Add a "Course Structure" section detailing the distinction between the
time-bounded "Fundamentals" course and optional "deep dives".
- Clarify the high bar for adding new content to the Fundamentals
course.

- **Add Guidelines for Course Content:**
- Add an "Exercises" section with principles for creating focused,
time-bounded exercises.
- Add an "Interactive Code Snippets" section explaining the importance
of live, editable code blocks.
- Add a "Pedagogical Flow" section advising a concrete-to-abstract
progression.

- **Refine Existing Sections:**
- Update "Speaker Notes" to clarify their role in guiding the
instructor's live-coding sessions.
- Remove redundant text from "Language and Tone" that is now covered in
the new philosophy section.

Author: gribozavr

STYLE.md

@@ -4,6 +4,86 @@ The course has been expanded and improved by tons of volunteers like you! Thank
 you for that! To help ensure a consistent style throughout the course, we have
 written down some guidelines for you to follow.
 
+## Course Philosophy and Design
+
+To contribute effectively, it's helpful to understand the core design principles
+of Comprehensive Rust. This is not a self-study book; it is a set of slides and
+notes for an **instructor-led course**.
+
+### Target Audience
+
+The course is designed for an audience of experienced software engineers who are
+new to Rust. We assume they have 2-3 years of experience in an imperative
+language like C, C++11+, Java 7+, Python, or Go.
+
+We **do not** assume familiarity with functional programming concepts or
+features from more modern languages like Swift or Kotlin. Course material should
+build upon the concepts that are likely to be familiar to this audience.
+
+### Goals
+
+The goal of the course is to provide a solid foundation in Rust within a bounded
+time frame. This prepares students to continue learning effectively as they
+begin to apply their new skills on the job.
+
+### Pedagogical Principles
+
+We follow a few key principles to make the material effective for learning:
+
+- **Build on a Foundation:** New Rust concepts should be connected to what a
+  learner already knows, either from their prior language experience or from
+  earlier parts of this course.
+- **Provide a Working Mental Model (The "No Magic" Rule):** As much as possible,
+  avoid telling students to accept syntax or behavior that will be explained
+  later. For everything that appears on the slides or in exercises, we must
+  provide a working mental model that allows the student to understand and use
+  the concept.
+- **Use a [Spiral Approach](https://en.wikipedia.org/wiki/Spiral_approach):** To
+  avoid overwhelming the learner, it is highly encouraged to introduce a concept
+  by first providing basic facts and a simplified mental model. The topic can
+  then be revisited later to provide more detail. For example, very early in the
+  course we explain the basics of `println!`, mention that it is a macro so the
+  usage syntax is a bit unusual, but we don't go into details of format strings
+  or macros. We explain details of format strings later, once we have covered
+  traits and can mention the `Debug` and `Display` traits.
+
+### Pacing and Structure
+
+The course is designed for approximately 5 hours of teaching per day, typically
+split into a 3-hour morning session and a 2-hour afternoon session.
+
+This pacing is important context for contributors. Material should be structured
+to fit this rhythm, with clear sections that can be taught in roughly 45-50
+minute blocks to accommodate short breaks and Q&A.
+
+Each slide must include a `minutes` field in its frontmatter, which specifies
+the estimated teaching time for that slide. This helps ensure the overall pacing
+of the course remains consistent.
+
+### Course Structure
+
+The course starts with a core **Rust Fundamentals** curriculum, followed by a
+collection of specialized **deep dives**. All students take the Fundamentals
+course and can then opt into any deep dives that are relevant to them.
+
+#### The Rust Fundamentals Course
+
+The **Rust Fundamentals** course provides a solid foundation in a strictly
+bounded, four-day time frame. This duration is firm, and its scope is carefully
+managed to focus on the most essential concepts for new Rust programmers.
+
+The overall progression of the course starts with the parts of the Rust language
+that should be conceptually familiar to most students from other languages. Then
+we move on to more difficult parts (for example, enums with payloads and
+generics), and parts that are unique to Rust (lifetimes and the borrow checker).
+
+Contributors should keep this structure in mind. The four-day schedule for the
+Fundamentals course is completely full, leaving no time slack for new topics.
+Proposals to add material to the Rust Fundamentals course must also include a
+plan to shorten or remove existing content. Refinements to existing topics are
+always welcome. Topics that are not essential for all new Rust programmers
+should be proposed as new deep dives.
+
 ## Course Slides
 
 Please take the following into account when updating the course material.
@@ -26,6 +106,24 @@ Use the rectangle as a rough guide for how much you can fit on a single slide.
 If you find yourself adding too much detail, move the details to the speaker
 notes (see below).
 
+### One Core Idea Per Slide
+
+Ideally, each slide should focus on a single, clear takeaway. If a slide
+introduces a core concept and then explores an important but distinct tangent
+(e.g., a limitation or an advanced use case), that tangent should be moved to
+its own slide. This keeps the presentation focused and easier to follow.
+
+Consider the instructor's workflow. If the speaker notes require a long or
+complex series of live edits, it can be difficult for the instructor to execute
+well every time. It may be better to add a new slide that presents the desired
+state of the code.
+
+### Pedagogical Flow
+
+When introducing a new concept, start with a simple, relatable, and concrete
+example. A good opening example grounds the concept for the learner and provides
+motivation for the more detailed explanation that will follow.
+
 ### Rust Code
 
 When showing Rust code inline, please use the same spacing as `rustfmt`: `3 * x`
@@ -45,40 +143,96 @@ Enclose the code block in `<!-- dprint-ignore-start -->` and
 `<!-- dprint-ignore-end -->` to suppress the automatic formatting. Please use
 this sparingly.
 
+#### Use Meaningful Examples
+
+Code samples on the slides should be short and do something meaningful. Avoid
+using generic placeholders like `Foo`, `Bar`, and `Baz`. Using descriptive names
+from a real-world, even if simplified, domain makes the code easier to
+understand and relate to.
+
+#### Interactive Code Snippets
+
+All Rust code blocks in the course are not static text but are live, editable
+playgrounds. An important teaching method is for the instructor to edit these
+snippets live to demonstrate concepts, introduce and fix errors, and explore
+variations based on student questions.
+
+Contributors should design their slides with this interactivity in mind. The
+initial state of the code should be a good starting point for a live
+demonstration.
+
 ### Language and Tone
 
 The courses are written in American English, so write "initialize", not
 "initialise".
 
 Use an informal, friendly, and concise tone. Remember that the courses are meant
-to be taught by an experienced programmer to other experienced programmers. We
-expect familiarity with programming, typically in a statically typed language
-like Java or C++. We don't explain common concepts known from that family of
-languages, but we cannot assume familiarity with things like functional
-programming.
+to be taught by an experienced programmer to other experienced programmers. When
+possible, prefer terminology used in
+[the official Rust Book](https://doc.rust-lang.org/book/). If a less common but
+necessary term is used, provide a brief definition.
+
+## Exercises
+
+At the end of some sections, learners will actively engage with the material by
+completing a small exercise. The goal of an exercise is to provide hands-on
+practice with the concepts just taught.
+
+Please keep the following principles in mind when creating or updating
+exercises:
+
+- **Focused Scope:** An exercise should focus on the topic of the preceding
+  section. It should not require knowledge of concepts that have not yet been
+  taught.
+- **Short Duration:** An exercise should be solvable by the target audience in
+  approximately 10-15 minutes. The goal is a quick, successful application of
+  knowledge, not a complex project.
+- **Clear Instructions:** The problem description should be clear and
+  unambiguous.
 
 ## Speaker Notes
 
 We have extended `mdbook` with support for speaker notes: content added between
 `<details> ... </details>` tags is rendered in a special box that can be
 collapsed or removed entirely from the slide.
 
-- Unlike the main content, the speaker notes don't have to fit on a single
-  slide.
+- Speaker notes suggest a narrative structure for the instructor.
 
 - The speaker notes should expand on the topic of the slide. Use them to provide
   interesting background information for both the instructor and for students
   who look at the material outside of a class. Remember that many more people
   will read the course by themselves, so make the notes complete and useful even
   when there is no Rust expert around.
 
+- For slides with evolving code examples, the notes provide a clear,
+  step-by-step flow for how the code is modified and presented. This is a
+  suggested flow for the instructor's live-coding session within the slide's
+  interactive playground. This includes:
+
+  - The order in which to introduce concepts, how to motivate them.
+
+  - Framing of the code example: the problem it tries to solve, if not obvious.
+
+  - How to demonstrate variations of the code example (e.g., code that does not
+    compile or illustrates a bug).
+
+  - How to change the code on the slide to illustrate the concepts being taught.
+
+  - 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.
 
+- 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
+  fit on a single slide.
+
 ### More to Explore
 
-Move extended explanations in the notes to a "More to Explore" section:
+Use the "More to Explore" section for valuable topics that are outside the main
+scope of the class. The content should be placed within the `<details>` block as
+shown below:
 
 ```markdown
 <details>
@@ -92,7 +246,11 @@ Move extended explanations in the notes to a "More to Explore" section:
 </details>
 ```
 
-The material there is outside the scope of the regular class.
+This section can contain a deeper explanation of a concept or provide specific
+pointers to external resources. A link should be accompanied by a brief
+explanation of what the resource contains and why it is relevant. A vague
+reference is not helpful, but a specific one can be a great tool for
+self-learners.
 
 ## Translations