explainer-book

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

explainer-book

explainer

の本版。 1 本の速習資料（20 分以内・例 1 つずつ）で足りないとき、章に分けて、手を動かして身につける資料にする。

ペルソナ・図・検証の仕組みは

explainer

をそのまま使う。先に

../explainer/SKILL.md

を読むこと。このスキルが足すのは、本全体の設計と検査。

スクリプトは、このスキルのディレクトリ（以下

<skill>

）の

scripts/

にあります。

verify-book.mjs

は、隣の

explainer

スキルの

scripts/verify-doc.mjs

を呼びます。2 つのスキルは同じ場所に入れてください。依存の入れ方は

explainer

の「準備」と同じです。

The book edition of

explainer

. When a single quick-study guide (within 20 minutes, one example at a time) is not enough, divide the material into chapters and make it something readers learn by doing.

Use the persona, diagram, and validation mechanisms from

explainer

unchanged. Read

../explainer/SKILL.md

first. This skill adds whole-book design and validation.

The scripts are located in this skill’s directory (below

<skill>

), under

scripts/

verify-book.mjs

calls the adjacent

explainer

skill’s

scripts/verify-doc.mjs

. Place the two skills in the same location. Set up dependencies in the same way as the “Setup” section of

explainer

いつ本にするか

When to make a book

次のどれかに当てはまったら本にする。1 つも当てはまらなければ、

explainer

の 1 本で書く。

読了が 20 分を超える
読み手が手を動かす演習が要る（読むだけでは「判定できる」ようにならない）
概念に順序がある（A を知らないと B が読めない）

Make it a book if any of the following applies. If none applies, write it as a single

explainer

document.

Reading takes more than 20 minutes
Readers need hands-on exercises (reading alone does not enable them to “make a determination”)
Concepts have a dependency order (B cannot be understood without A)

構成

Structure

<topic>-book/
  README.md            目次：想定読者、章ごとの「読み終えたらできること」、章の依存図、再現方法
  book.json            章の順序・学習目標・導入する概念・演習（references/book-json.md）
  01-quickstart.md     最初の章は必ず quickstart：理論の前に、動く結果に着く
  02-….md              concept：1 章 1 つの判定を身につける
  03-….md              practice：演習が中心
  checks.json          本文の出力と演習の答えを再生成するコマンド（explainer と同じ形式）
  examples/            章で使うコード・モデル。演習の出発点と答えを別ファイルにする
  figures/             book-map.*（生成）と各章の図

<topic>-book/
  README.md            目次：想定読者、章ごとの「読み終えたらできること」、章の依存図、再現方法
  book.json            章の順序・学習目標・導入する概念・演習（references/book-json.md）
  01-quickstart.md     最初の章は必ず quickstart：理論の前に、動く結果に着く
  02-….md              concept：1 章 1 つの判定を身につける
  03-….md              practice：演習が中心
  checks.json          本文の出力と演習の答えを再生成するコマンド（explainer と同じ形式）
  examples/            章で使うコード・モデル。演習の出発点と答えを別ファイルにする
  figures/             book-map.*（生成）と各章の図

手順

Procedure

1. ペルソナ     explainer と同じ。「怪しいところ」から、本全体の問いを 1 つ決める
2. 目標を並べる  問いに答えるために読み手ができるべき判定を 3〜6 個。1 章に 1〜2 個
3. 概念の順序   各判定に要る概念を書き出し、どの章で導入するかを決める（book.json introduces / requires）
4. 実物を先に   各章の例と演習を作り、走らせる。演習は「出発点で落ちる」「答えで通る」を両方確かめる
5. 章を書く     explainer の writing.md の型。章の冒頭に所要時間とゴール、末尾に理解度チェック
6. 検証         node <skill>/scripts/verify-book.mjs <book-dir> [--write]
7. 読ませる     first-reader で、少なくとも 01-quickstart と演習の章を、ペルソナ本人に読ませる（explainer の手順 8）
8. 渡す         dist/index.html と、各章の 1 行要約。未検証の点を明記

1. ペルソナ     explainer と同じ。「怪しいところ」から、本全体の問いを 1 つ決める
2. 目標を並べる  問いに答えるために読み手ができるべき判定を 3〜6 個。1 章に 1〜2 個
3. 概念の順序   各判定に要る概念を書き出し、どの章で導入するかを決める（book.json introduces / requires）
4. 実物を先に   各章の例と演習を作り、走らせる。演習は「出発点で落ちる」「答えで通る」を両方確かめる
5. 章を書く     explainer の writing.md の型。章の冒頭に所要時間とゴール、末尾に理解度チェック
6. 検証         node <skill>/scripts/verify-book.mjs <book-dir> [--write]
7. 読ませる     first-reader で、少なくとも 01-quickstart と演習の章を、ペルソナ本人に読ませる（explainer の手順 8）
8. 渡す         dist/index.html と、各章の 1 行要約。未検証の点を明記

2. 学習目標

2. Learning objectives

目標は「読み終えたら、何を判定できるか」で書く。「〜を理解する」は検査できないので書かない。

悪い例：「CTI を理解する」
良い例：「CTI が出たとき、条件が弱すぎるだけか、性質が本当に破れるかを TLC で判定できる」

各目標には、理解度チェックの問いを 1 つ以上付ける（

<!-- quiz: <目標id> -->

）。

Write each objective in terms of “what the reader can determine after finishing.” Do not write “understand …,” because it cannot be assessed.

Bad example: “Understand CTI”
Good example: “When CTI appears, use TLC to determine whether the conditions are merely too weak or whether the property is actually violated”

Attach at least one comprehension-check question to every objective (

<!-- quiz: <objective-id> -->

3. 概念の順序

3. Concept order

ペルソナが既に知っている概念は
```
assumed
```
に書く。説明しない。
それ以外の概念は、ちょうど 1 つの章が
```
introduces
```
する。その章より前の章の本文に出てきたら、検証が落ちる。
章が前提にする概念は
```
requires
```
に書く。依存図の矢印になる。

Put concepts the persona already knows in
```
assumed
```
. Do not explain them.
For every other concept, exactly one chapter
```
introduces
```
it. If it appears in the body of an earlier chapter, validation fails.
Put concepts that a chapter depends on in
```
requires
```
. These become arrows in the dependency graph.

4. 演習

4. Exercises

演習の答えも実行して確かめる。答えが間違った演習は、間違いを教える。

kind	例	検査
`write`	条件・関数・設定を書かせる	`starter` ：出発点のまま実行すると落ちることを確かめる check。 `answer` ：答えで通ることを確かめる check
`check`	道具を回して判定させる	`answer` ：判定の根拠になる出力を再生成する check

答えは、演習と同じ節の
```
<details>
```
に入れる。
演習の前に
```

```
を置く。

Run the exercise answers as well and verify them. An exercise with an incorrect answer teaches the mistake.

kind	Example	Check
`write`	Have the reader write conditions, functions, or configuration	`starter` : A check that confirms the starting point fails when run unchanged. `answer` : A check that confirms it passes with the answer
`check`	Have the reader run a tool to make a determination	`answer` : A check that regenerates the output supporting the determination

Put the answer in a
```
<details>
```
element in the same section as the exercise.
Place
```

```
before the exercise.

5. 章を書く

5. Writing chapters

explainer

の文体に加えて、次を守る。

冒頭の引用ブロックに、所要時間・ゴール（その章の目標）・前提（前の章）を書く。
末尾で次の章へリンクする（
```
→ [02 …](02-….md)
```
）。HTML では前後の章と目次へのナビが付く。
前の章の結果を使うときは、章番号で参照する（「1 章の 3 つの check」）。同じ説明を繰り返さない。
手で推論した結果（「この状態には着けない」「この順序で起きる」）は、道具の出力に置き換える。推論は外れる。

In addition to the

explainer

style, follow these rules:

In the opening block quote, include the estimated time required, the goal (the chapter’s objectives), and the prerequisites (previous chapters).
At the end, link to the next chapter (
```
→ [02 …](02-….md)
```
). In HTML, navigation to the previous and next chapters and to the table of contents is added.
When using a result from a previous chapter, refer to it by chapter number (“the three checks in Chapter 1”). Do not repeat the same explanation.
Replace results derived through manual reasoning (“this state is unreachable,” “this happens in this order”) with tool output. Manual reasoning can be wrong.

6. 検証

6. Validation

node <skill>/scripts/verify-book.mjs <book-dir>           # 検査
node <skill>/scripts/verify-book.mjs <book-dir> --write   # 依存図と SVG を作り直す

本全体の検査：

検査	落ちる条件
chapters	章ファイルがない。 `NN-` の番号が book.json の順と違う。1 章が quickstart でない
objectives	quiz が付いていない目標がある。quiz が他の章の目標を名指ししている
concepts	概念を導入より前の章で使っている。 `requires` が導入されていない。 `introduces` と宣言したのに本文に出てこない
budget	本文の推定読了時間（500 字/分 + コード 15 行/分）が `minutes` を超える
exercises	印がない。答えが `<details>` にない。check が checks.json にない。 `write` 演習に落ちる starter がない
map	`figures/book-map.*` が book.json と一致しない。README に図がない

そのあと、README と全章を

verify-doc.mjs --pages

に渡す。出力の引用、図、ページ間リンク、各ページの vlmkit ゲートを検査する。

book verdict: VERIFIED

になるまで直す。

node <skill>/scripts/verify-book.mjs <book-dir>           # 検査
node <skill>/scripts/verify-book.mjs <book-dir> --write   # 依存図と SVG を作り直す

The whole-book checks are:

Check	Failure condition
chapters	A chapter file is missing. The `NN-` number does not match the order in book.json. Chapter 1 is not quickstart.
objectives	An objective has no quiz. A quiz explicitly refers to an objective in a different chapter.
concepts	A concept is used in a chapter before it is introduced. A `requires` concept has not been introduced. A concept declared in `introduces` does not appear in the body.
budget	The estimated body reading time (500 characters/min + 15 lines of code/min) exceeds `minutes` .
exercises	A marker is missing. The answer is not in `<details>` . A check is missing from checks.json. A `write` exercise has no failing starter.
map	`figures/book-map.*` does not match book.json. README has no diagram.

Afterward, pass the README and every chapter to

verify-doc.mjs --pages

. It checks output quotations, diagrams, links between pages, and the vlmkit gate for every page.

Keep fixing the material until it displays

book verdict: VERIFIED

やってはいけないこと

Things not to do

章を増やして薄める。 1 章に目標がない、または理解度チェックが目標を問わないなら、その章は要らない。
演習の答えを走らせない。
前の章の説明を繰り返す。 章番号で参照する。
検証を通すために言い換える。 概念の検査に落ちたら、定義を前の章に移すか、章の順序を見直す。同義語に置き換えて逃げない。

Add chapters and dilute the material. If a chapter has no objective, or its comprehension check does not ask about the objective, the chapter is unnecessary.
Do not run the exercise answers.
Do not repeat the previous chapter’s explanation. Refer to it by chapter number.
Do not reword things merely to pass validation. If a concept check fails, move the definition to an earlier chapter or revise the chapter order. Do not evade the check with synonyms.

ファイル

Files

パス	内容
`references/book-json.md`	book.json の全フィールド
`scripts/verify-book.mjs`	本全体の検査 → verify-doc.mjs
`../explainer/scripts/build-html.mjs`	複数ページを HTML に（目次・前後の章へのナビつき）

Path	Contents
`references/book-json.md`	All fields of book.json
`scripts/verify-book.mjs`	Whole-book validation → verify-doc.mjs
`../explainer/scripts/build-html.mjs`	Builds multiple pages into HTML, with a table of contents and previous/next chapter navigation