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.

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,17 +143,52 @@ 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
 
@@ -63,8 +196,7 @@ 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
@@ -72,13 +204,35 @@ collapsed or removed entirely from the slide.
   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