コースの教材サイトに、数式の前に理由を説明する章を書く

## 教材ページと翻訳ページの置き場所を決める このプロジェクトは、リポジトリ内のソースファイルから生成される静的ドキュメントサイトである。貢献者が「どこに何があるか」を推測できるよう、ツリーは予測可能に保つこと。 - `docs/` — 公開ページになるコース内容。 - コンテンツツリー内のサイト設定ディレクトリ — 静的サイトジェネレーターの設定とテーマの上書き。 - `docs/public/` — 最終的なサイトへそのままコピーされる静的アセット。 - コンテンツツリー内の、追加言語ごとに1つのディレクトリ — 主言語の構造を鏡写しにした翻訳ツリー。翻訳ツリーではスタブページをプレースホルダとして置いてよい。 - `code/` — 本文と章ごとに対応する、実行可能な実験コード。 - `scripts/` — サイトマップ生成・検証・アセット最適化などのリポジトリ保守スクリプト。 - CI ワークフローのディレクトリ — サイトをビルドしてデプロイするパイプライン。 新しい教材はコンテンツディレクトリの下に置く。ナビゲーションとサイドバーの項目はサイト設定ファイルで宣言するものであり、ファイルの配置だけから推測されることは決してない。 ## プロジェクトのコマンドで、サイトを手元で表示して確かめる 全員が同じパイプラインを通るよう、下位のツールを直接呼ぶのではなく、プロジェクト自身のスクリプトの入口を通して作業すること。この形のドキュメントサイトは、少数の固定された入口を公開している。 - `npm install` — 依存関係をインストールする。 - `npm run dev` — アセット最適化ありの開発サーバー。 - `npm run dev:fast` — アセット最適化を省略する開発サーバー。起動がはるかに速い。 - `npm run build` — 公開可能な出力を生成する。 - `npm run preview` — ビルド済み出力を、公開されるのとまったく同じ形で配信する。 - `npm run verify` — リポジトリ全体の整合性チェック。 - `npm run assets:optimize` — 画像を圧縮・変換する。 本文を書いている間は、高速な開発用のバリアントを使う。画像最適化は、そこで見ているものを何も変えないからである。公開されるのとまったく同じ出力を確認したいときは、`build` の後に `preview` を使う。`verify` は次のパートで説明するゲートであり、`assets:optimize` は画像を追加した後に実行して、大きな原本が公開サイトへ届かないようにするためのものである。 ## ページを足したら全言語のメニューを直し、公開前にチェックする - すべての変更を、目の前のタスクの範囲に限定して保つこと。通りがかりに、無関係な文書や設定を書き直さないこと。 - すでに存在する教材を再構成するよりも、コンテンツディレクトリの下に新しいコース教材を追加することを優先する。 - 新しいページを追加したら、ナビゲーションとサイドバーの設定に登録する。 - ページを追加・移動・改名したときは、主言語だけでなく、それを鏡写しにしているすべての言語ツリーのサイドバーを更新する。取り残された翻訳ツリーは、死んだ項目か、存在しないページを生む。 - 設定・テーマ・ビルドスクリプトに触れた場合は、プッシュ前に必ず検証コマンドを実行する。プッシュはサイトを公開するので、検証していないビルドは人目に触れる形でサイトを壊す。 ## 数式入りの図を LaTeX で書き、SVG に変えて使う 本物の数式組版を伴う学術的な図版は、手で描くのではなくソースとして著述する。 1. 図をベクター図言語の単体ドキュメントとして書く — たとえば TikZ 系パッケージを使った LaTeX の standalone ドキュメント。新しい様式を発明せず、リポジトリにある既存の図のスタイルを踏襲する。 2. 使用するフォントに対応した LaTeX エンジンでソースをコンパイルし、できた PDF を PDF-to-SVG コンバーターで SVG へ変換する。どちらの工程もコマンドラインツールなので、どの図もいつでもソースから作り直せる。 3. ソースファイルと生成された SVG の両方を、それを使う章の隣にある同じ `images/` ディレクトリに置き、図が再現可能な状態を保つ。 4. 生成された SVG は、マークダウンのページから相対パスで参照する。 すべての図で1つのビジュアルスタイルを貫くこと。角丸のボックスに非常に淡い塗りと濃いグレーの線、単一の矢頭スタイル、本文と揃った本文用フォント、記号にはインライン数式の区切り記号を用いる。 ## おしゃべりではなく、落ち着いた講義の口調で書く - 各章は、そっけないリファレンスノートではなく、チュートリアルおよび講義の教材として書く。 - 導いてくれる講義の声を保つこと。会話的で、辛抱強く、問題を起点にする。読者に次の一手を手渡すような言い回し（「まずは直感から始めよう」「別の角度から見てみよう」「この手順が意味しているのは…」「本当の問題は…」）は歓迎されるが、トーンは真面目で正確なままにする。 - おしゃべりな調子、アシスタントめいた調子、くだけたインターネット的な言い回しに流れないこと。目指す語調は、磨き上げられた教科書の一章である。 - 段落は、声に出して読めるか、一人で読み進められる速さに整える。読む速度で追えない段落は分割する。 ## 理由のつながりを全部説明し、中身のない前置きを書かない 厚みと簡潔さは両立する。推論の連鎖を丸ごと説明し、その連鎖の外にあるものには一語も費やさない。 - 段階的に説明する — まず直感、次に形式的な定義、そしてコードや実践。 - 背景と、その手順が必要な理由を示す。章を結果の素っ気ない箇条書きへ圧縮しないこと。 - 案内役の埋め草は削ぎ落とす。説明を与える代わりに説明を予告するだけの文（「例を挙げるとこれはより直感的になる」）は本文から外し、例や数式を直接示す。 - 各事項は一度だけ述べる。同じ論点を言い換えて繰り返さないこと。 - 曖昧な限定表現は、正確な因果の言明に置き換える。比喩的な代用（「これはおおよそ…に相当する」）や、ぼかしの接続表現は初稿にだけ許される。 - 仕組みをキャッチーな一文へ圧縮する、標語めいた要約表現を避ける。代わりに具体的な仕組みを述べる。 - 並列した誤りを機械的に列挙する書き方（「クエリが広すぎた、価格比較なし、在庫数が誤り、パラメータが誤り」）を避ける。プロセスを記述し、初期の1つの誤った状態が後続の行動へどう波及するかを示す。 - 「A ではなく B」という対比の型を避ける。回りくどく読める。まず肯定的な主張を述べ、次にそれが成り立つ理由を説明する。 ## 新しい考えを出す前に、なぜ必要かを言う順に並べる - 因果の線をたどること。同じ論点を、要約し、言い直し、そして対比して、ぐるぐる回らないこと。アイデアが実際に変化していく順序で書く。新しい能力や設定が現れ、それが学習対象や問題の対象を変え、そのために新しい定式化が可能になる、あるいは避けられなくなる。 - 新しい概念を開くときは、「X が存在するようになった今、システムは Y を行い、だから Z が可能（あるいは必要）になる」という形を優先する。 - セクションは、読者がすでに知っていることへの接続で開き、それからこのセクションが解決する新しい問題を名指しする。 - すぐ次の一文のためにその参照が必要な場合を除き、前の章を振り返らないこと。 - すべての概念的な手順に移行を与える。定義から数式・用語・アルゴリズム・結論へいきなり飛ばないこと。次のアイデアを導入する前に、それがなぜ必要かを述べる。 - 定義を並べるだけの百科事典的なページを書かないこと。定義はその動機の後に現れ、その後に解釈が続く。 - 段落は問いから答えへ流れるようにする。よく組み立てられたセクションは、たいてい次のリズムをたどる。馴染みのある例 → 緊張または混乱 → 形式的な道具 → 例題 → 学びの要点。 ## 数式の前に身近な例を出し、記号を1つずつ説明する - 数式やアルゴリズムを導入する前に、それが解く問題を述べる。記法を示すのはその後である。 - 数式はその意味の隣に置く。重要な記号をすべて説明し、それから数式全体を平易な言葉で言い直す。 - 抽象化の前に具体的な場面へ手を伸ばす。小さく馴染みのある設定 — 棒立てのバランス制御タスク、多腕バンディット、文章生成、ゲームのタスク、日常の選択 — によって、概念が名指しされる前に、それが必要だと感じられるようにする。 - 結果を断言する代わりに小さな導出を含め、本文全体を通して学習者に向けた語りを保つ。 - 定着した訳語がある限り、借用した英単語を未翻訳のまま残さず、技術用語は本文の主言語で書く。英語の用語を残すのは、標準的な略語である場合か、章題がそれを要求する場合だけにし、初出時に説明する。 - 1つの概念には、コース全体を通して1つの決まった語を使う。章ごとに揺れる同義語は、学習者には第二の概念として読まれてしまう。 ## 見出しで短く区切り、変更記録の頭に feat: などの印を付ける - 長く区切りのない文章の塊ではなく、明示的な見出しを持つ短いセクションを使う。 - 太字は概念の転換点を示すために控えめに使う。装飾として使うことは決してない。 - コンテンツディレクトリ配下のパスにはケバブケースを使う。 - `index.md` を内側に持つディレクトリベースのルートを優先し、1つのトピックが URL を変えずに複数ページへ育てられるようにする。 - すべての変更に Conventional Commits を使う。`feat:`、`fix:`、`docs:`、`chore:` など。