メインコンテンツまでスキップ

この文書の書き方

この文書に頁を足す・直すときの手順である。読者ではなく、書き手のための頁である。

一つの掟​

この文書が正典である。読者にとって、ここに書かれていることが koyu の事実の全部である。したがって、

頁は自分の言葉で事実を述べ切る。他所へ預けない。

外部の文書へ読者を送る一文 — 「本当のことは別の場所にある」と読める一文 — は、読者が開けない扉を指している。それは頁の欠陥である。

参照してよいのはこの文書の中の頁だけである。相対リンクで結ぶ。

[space](../reference/muro/space.md) · [koyu check](../reference/cli/check.md)

この掟はビルドの門番が機械的に検査する。

一頁一仕事​

その頁が何のためにあるのかを一文で言えなければ、二頁に割る。書いているうちに別の話に入ったら、それは別の頁の仕事である — 本文を膨らませずに、リンクを張る。

仕事の種類は四つあり、front matter の mode がそれを名乗る。

mode仕事読者の状態
tutorial手を動かして一周させるまだ何も知らない
howtoある目的を達成する手順を与える目的がある
reference事実を引けるように並べる答えを探している
explanationなぜそうなっているかを述べる納得したい

混ぜない。手順の途中に長い理由を挟むと手順が読めなくなり、理由の頁に手順を書くと理由が薄まる。

頁の形​

front matter はこの二つだけである。

---
title: <頁の題>
mode: tutorial | howto | reference | explanation
---

続けて title と同じ文の H1 を置き、そこから本文を書く。言語切替の行は書かない — 表示側が locale を扱う。

日本語と英語を同時に置く​

頁は必ず二つ書く。日本語を docs/ に、英語を同じパスの docs/en/ に置く。

docs/howto/write-as-built.md
docs/en/howto/write-as-built.md

片方だけ足すと、半分の読者にとってその頁は存在しない。ビルドの門番が両ロケールの過不足を検査する。

守る規律は四つ。

  1. 頁が対応していること。片方だけ足す・消すをしない。
  2. コードブロックが一致していること。例のコードが片方だけ直されると、読者は誤った例を手に入れる。コード中のコメントは訳してよい — 英語の読者に日本語のコメントを読ませない。
  3. 貼った出力は訳さない。ツールが実際に出す文字列であり、訳せば嘘になる。人向けの出力は英語なので、日本語の頁にもそのまま貼り、解説だけを日本語で書く。手で描いた図 (層の重なり、矩形の配置) は出力ではないので訳す。
  4. 見出しの構造が一致していること。節を片方だけに足さない。見出しの文は訳す。

英語は訳し下ろしではなく英語である。日本語の語順をなぞった文は書かない。

見出しの文を訳すと、その見出しへのアンカーが変わる。同じロケールの頁からリンクする — 英語の頁からは英語のアンカーへ、日本語の頁からは日本語のアンカーへ。

コードフェンス​

印の無い裸のフェンスは書かない。印を落とすのが、検証の最も起きやすい抜け方である。

.muro を囲むフェンスは六つある。

印中身検証されること
```muro通る完全なファイルcheck のエラーが 0 件
```muro-part断片検証しない
```muro-badcheck がエラーで落とすものerror の診断が 1 件以上
```muro-warncheck は通り --strict で落ちるものerror 0 件・warning 1 件以上
```muro-failvalidate が violation を出すものerror 0 件・violation 1 件以上
```muro-cautionvalidate が caution を出すものerror 0 件・caution 1 件以上

import を含むファイルは ```muro にできない。一枚のテキストとして読むと import が解決できないからである。合成の例は ```muro-part で書く。

.muro 以外はこの四つ。

印中身
```text貼った出力と、手で描いた図
```sh実行するコマンド
```tsTypeScript
```jsonJSON

出力は実行して得たものだけを貼る​

推測した出力を貼らない。これは頁ごとの礼儀ではなく、この文書が正典であることの条件である。

npx tsx src/cli.ts check examples/two-rooms.muro
✔ Consistent — 3 spaces / 3 boundaries
  Structural consistency only — architectural validity is what koyu validate says, separately

絶対パスが出るところは <absolute path> や <dir>/ と縮めてよい。縮めたことを頁のどこかで一度断る。それ以外の改変はしない — 数字を丸めない、順序を並べ替えない、都合の悪い行を落とさない。

出力が長すぎるときは、✔ Consistent — 3 spaces / 3 boundaries のように先頭から必要な行だけを抜く。抜くのはよいが、書き換えるのは駄目である。

数を手で書かない​

診断コードは 65、判定の規則は 15、CLI のサブコマンドは 14、MCP のツールは 12、公開 API は実行時の値 59 と型 77。これらの数は実装の台帳から来る。

台帳が動けば数も動く。だから数を書くときは、その場で実装から数え直す。書いた時点で正しかった数が古びて残る、というのがこの文書で最も起きやすい嘘である。

コード・規則・ツール名・サブコマンド名の全件が公開頁に載っていることは、テストが台帳と突き合わせて検査する。足したのに書かなければビルドが落ちる。

生成される頁は手で書かない​

サイドバーは公開された木から導かれる。手で並べた一覧ではないので、頁が在ればサイドバーに載る。登録の作業は無い。

同じ理由で、ビルドが生成した木 (website/.generated/) を編集しない。次のビルドで消える。原本は docs/ にある。

頁を足したときの確認​

  1. docs/ と docs/en/ の両方に置いたか。
  2. front matter は title と mode の二つだけか。H1 は title と同じか。
  3. リンクの先はこの文書の中の頁か。相対パスで届くか。
  4. フェンスに印が付いているか。```muro は本当に通るか。
  5. 貼った出力は実行して得たものか。
  6. 数を手で書いていないか。
  7. 他所へ預ける一文が残っていないか。

声​

  • 現在形で書く。「〜になる予定である」「v0.9 では〜だった」を積まない。版は git が持っている。
  • 断定する。「〜と思われます」「〜かもしれません」を書かない。分からないことは書かない。
  • その頁で一番効いている主張を太字にする。一節に一つか二つまで。多いと効かなくなる。
  • 同じ事実を二度書かない。二度書けば、いつか片方だけが直される。
  • 売り込まない。読者は既にここに来ている。

関連​