- Consolidates all guidance related to code block mechanics under a new
top-level heading, "Code Blocks Mechanics".
- Moves the "Rust Code Formatting" guidance to be a subsection under
this new heading.
- The rest of the former "Rust Code" section is now directly under
"Course Slides".
This restructuring improves the logical flow of the style guide by
grouping all code-related formatting and tooling conventions into a
single, easy-to-find section.
Adds a new pedagogical principle to STYLE.md to formalize the course's
core philosophy of live, interactive instruction.
This principle clarifies the expectation that instructors will interact
with code snippets live, use compiler errors as a teaching tool, and
engage with audience questions dynamically.
Adds a new section to STYLE.md to document mandatory conventions for
using `mdbook` and the custom `mdbook-course` preprocessor.
This section mandates the use of YAML frontmatter, outline helpers, and
file includes for exercises, and links to the `mdbook-course` README for
more detailed technical explanations.
- Moves the canonical documentation for code block annotations and
language identifiers into STYLE.md.
- Removes the redundant, partial documentation from GEMINI.md.
- Updates GEMINI.md to instruct the AI assistant to always refer to
STYLE.md for guidance.
This change makes STYLE.md the single source of truth for all markdown
and code style conventions, ensuring consistency for both human and AI
contributors.
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.
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.
Added a dev theme to help with slide aspect ratio while updating content
or for reviewing PRs.
Fixes#1796.
---------
Co-authored-by: Dustin J. Mitchell <djmitche@google.com>
Co-authored-by: Martin Geisler <martin@geisler.net>
With mdbook-i18n-helpers 0.2, reference links are automatically turned
into inline links in the PO files. This means that translators no longer
have to deal with link references in one message and link definitions in
another.
The dprint formatter is a flexible system which will use sandboxed
WebAssembly formatters to format our code (mostly: it calls out to
`rustfmt` for Rust code).
A particularly interesting feature is that dprint can format Rust code
blocks in the Markdown files. However, before we turn that on, we need
to have a way to normalize the Markdown text as it is extracted[1].
That is so that the word put into the translations is kept after the
reformatting.
[1]: https://github.com/google/mdbook-i18n-helpers/issues/19
