Write Course Website Chapters That Explain the Reason Before the Formula

## Know Where Course Pages and Their Translations Belong The project is a static documentation site built from source files in the repository. Keep the tree predictable so that a contributor can guess where anything lives: - `docs/` — the course content that becomes the published pages. - The site-configuration directory inside the content tree — configuration and theme overrides for the static site generator. - `docs/public/` — static assets copied verbatim into the final site. - One directory per additional language inside the content tree — translation trees that mirror the structure of the primary language. Stub pages are acceptable placeholders in a translation tree. - `code/` — runnable experiments aligned chapter by chapter with the prose. - `scripts/` — repository maintenance scripts such as sitemap generation, verification, and asset optimization. - The CI workflow directory — the pipeline that builds and deploys the site. New material goes under the content directory. Navigation and sidebar entries are declared in the site configuration file, never inferred from file placement alone. ## Preview and Check the Site Locally with the Project's Commands Work through the project's own script entry points rather than calling the underlying tools directly, so that everyone runs the same pipeline. A documentation site of this shape exposes a small fixed set of them: - `npm install` — install dependencies. - `npm run dev` — development server with asset optimization. - `npm run dev:fast` — development server that skips asset optimization, for a much faster startup. - `npm run build` — produce the publishable output. - `npm run preview` — serve the built output exactly as it will be published. - `npm run verify` — repository-wide consistency checks. - `npm run assets:optimize` — compress and convert images. Use the fast development variant while editing prose, where image optimization changes nothing you are looking at. Use `build` followed by `preview` when you need to see the output exactly as it will be published. `verify` is the gate described in the next part, and `assets:optimize` is run after adding images so that large originals never reach the published site. ## Update Every Language's Menu and Run Checks Before Publishing - Keep every change scoped to the task at hand. Do not rewrite unrelated documents or configuration while passing through them. - Prefer adding new course material under the content directory over restructuring material that already exists. - Register new pages in the navigation and sidebar configuration when you add them. - When a page is added, moved, or renamed, update the sidebar of every language tree that mirrors it, not only the primary one. A translation tree left behind produces a dead entry or a missing page. - Run the verification command before pushing whenever configuration, theme, or build scripts were touched. A push publishes the site, so an unverified build breaks it in public. ## Write Math Diagrams in LaTeX and Convert Them to SVG Academic-style figures with real mathematical typesetting are authored as source, not drawn by hand: 1. Write the diagram as a standalone document in a vector diagram language — for example a LaTeX standalone document using a TikZ-style package. Copy the style of an existing figure in the repository instead of inventing a new one. 2. Compile the source with a LaTeX engine that supports the fonts you use, then convert the resulting PDF into SVG with a PDF-to-SVG converter. Both steps are command-line tools, so any figure can be rebuilt from its source at any time. 3. Keep both the source file and the generated SVG in the same `images/` directory, next to the chapter that uses them, so the figure stays reproducible. 4. Reference the generated SVG from the markdown page by relative path. Hold one visual style across every figure: rounded-corner boxes with a very light fill and a dark grey stroke, a single arrow-head style, a body font matching the prose, and inline math delimiters for symbols. ## Write in a Patient Lecture Voice, Not a Chatty One - Write chapters as tutorial and lecture material, not as terse reference notes. - Keep a guided lecture voice: conversational, patient, and problem-driven. Phrases that hand the reader the next move — "Let us start with the intuition", "Look at it from another angle", "What this step means is…", "The real issue is…" — are welcome, while the tone stays serious and precise. - Do not slip into chatty, assistant-like, or casual internet phrasing. The target register is a polished textbook chapter. - Pace paragraphs so they can be read aloud or worked through alone. If a paragraph cannot be followed at reading speed, split it. ## Explain the Full Reasoning Without Empty Filler Sentences Depth and economy sit together: explain the whole chain of reasoning, and spend no words on anything outside that chain. - Explain progressively — intuition first, then the formal definition, then code or practice. - Give the background and the reason a step is needed. Do not compress a chapter into a bare list of results. - Cut guiding filler. A sentence that announces an explanation instead of giving it ("an example will make this more intuitive") is deleted, and the example or formula is presented directly. - Say each thing once. Do not restate the same point in different words. - Replace vague qualifiers with precise causal statements. Metaphorical stand-ins ("this is roughly equivalent to…") and hedging connectives belong in a first draft only. - Avoid slogan-like summary phrases that compress a mechanism into a catchy string. State the concrete mechanism instead. - Avoid machine-sounding lists of parallel mistakes ("the query was too broad, no price comparison, wrong stock level, wrong parameter"). Describe the process, and show how one early wrong state propagates into the later actions. - Avoid the "not A, but B" contrast pattern; it reads as indirect. State the positive claim, then explain why it holds. ## Order Ideas So Each New Step Comes with Its Reason - Follow the causal line. Do not circle the same point by summarizing, restating, and then contrasting it. Write in the order in which the idea actually changes: a new capability or setting appears, it changes the training or problem object, and that makes a new formulation possible or unavoidable. - When opening a new concept, prefer the shape "now that X exists, the system does Y, so Z becomes possible (or necessary)". - Open a section by connecting to what the reader already knows, then name the new problem this section solves. - Do not call back to earlier chapters unless the callback is needed for the very next sentence. - Give every conceptual step a transition. Never jump straight from a definition to a formula, term, algorithm, or conclusion; say why the next idea is needed before introducing it. - Do not write encyclopedia-style pages that only list definitions. A definition arrives after its motivation and is followed by an interpretation. - Let paragraphs run from question to answer. A well-built section usually follows the rhythm: familiar example → tension or confusion → formal tool → worked example → takeaway. ## Show a Familiar Example Before a Formula and Explain Each Symbol - Before introducing a formula or an algorithm, state the problem it solves; only then show the notation. - Keep a formula next to its meaning: explain every important symbol, then restate the whole formula in plain language. - Reach for a concrete scene before an abstraction. Small familiar setups — a pole-balancing control task, a multi-armed bandit, text generation, a game task, an everyday choice — should make a concept feel necessary before it is named. - Include small derivations instead of asserting results, and keep the prose learner-facing throughout. - Write technical terms in the primary language of the prose whenever an established equivalent exists, rather than leaving the borrowed English word untranslated. Keep an English term only when it is a standard acronym or when the chapter title requires it, and explain it at first use. - Use one fixed word per concept across the whole course. A synonym that drifts from chapter to chapter reads to a learner as a second concept. ## Keep Sections Short and Start Each Commit with feat:, fix:, or a Similar Label - Use short sections with explicit headings rather than long undivided runs of text. - Use bold sparingly, to mark a conceptual pivot — never as decoration. - Use kebab-case for paths under the content directory. - Prefer directory-based routes with an `index.md` inside, so that a topic can grow into several pages without changing its URL. - Use Conventional Commits for every change: `feat:`, `fix:`, `docs:`, `chore:`, and so on.