一つのドキュメントの書き方

各ページの自己完結

検索や直接リンクから、どのページにも最初に到達しうる。各ページは前後を読まなくても理解できるよう、必要な文脈を自前で備える。関連するページへは、後述の「リンクの貼り方」に従って誘導する。

各ページは、frontmatter の description にそのページの役割を一文で書く。Fumadocs がこれをページ上部へ表示するため、本文に同じ役割文を重ねて書かない。規範を定めるページは「…を定める」、事柄を説明するページは「…を示す」で締める。

情報の順序

重要なことを先に書く。概要や結論、参照頻度の高い情報を上に置く。理由や詳細は、その後に続ける。こうすれば、読み手は途中で離脱しても要点をつかめる。この並べ方を逆ピラミッドと呼ぶ。

• チュートリアルとハウツーでは、ゴールや課題を冒頭に示し、手順を番号付きで上から順に並べる。
• リファレンスでは、対象の構造に合わせて整理し、よく引く項目を上にまとめる。
• 解説では、まず結論を示し、理由はその後に厚く展開する。理由は省かず、並べる順番を変えるだけである。

文体

文体の機械的な規約は lint を正本とする。ここでは lint で検出できない規約だけを補う。

• 本文では体言止めを使わない。文は述語で終える。
• 用語の表記はそろえる。揺れを見つけたら prh/dict.yml へ追記する。

見出しの付け方

Fumadocs は見出しから目次を自動生成する。見出しだけを並べて読めば、ページの構造が分かる状態を目指す。

• 見出しは内容が分かる具体的な語にする。「概要」や「その他」のような曖昧な語を避ける。
• 同じ階層の見出しは形をそろえる。本文では体言止めを使わないが、見出しは体言止めでそろえる。
• 見出しのレベルを飛ばさない。本文の見出しは ## から始める。

段落とページの読みやすさ

• 段落は1つの主題に絞る。段落の冒頭に主題を示す一文を置き、後続の文で詳細を補う。
• 文・段落・セクションは論理的につながなければならない。前の内容を前提に次へ進み、飛躍した結論や脈絡のない転換を置かない。
• 箇条書きは並列する項目にだけ使う。説明や論理の流れを箇条書きで代用しない。
• 中身のない前置きと要約の節を置かない。読み手の判断材料にならない一般論を削る。
• 常套句・華美な語・過剰な敬語を避け、具体的な事実を書く。
• 「A ではなく B だ」という対比や、同じ構文を繰り返す言い回しを多用しない。

リンクの貼り方

リンクは関連を伝える助けになる。ただし数を増やすほど読み手の負担も増える。主題のつながりに沿って抑制的に貼る。

• 本文中のリンクは、正本となる概念や用語の初出だけに貼る。
• それ以外の関連は、ページ末尾の「関連項目」へまとめる。
• 内部リンクは自動検証の対象とする。リンク先のページや見出しが存在しないと検査で失敗する。

書いたあとの検証

ドキュメントを編集したら、次のコマンドで検証する。

pnpm run lint:docs

自動で直せる範囲は pnpm run lint:docs:fix でそろえる。内部リンクの切れは pnpm run lint:links で検査する。この検査は push 前にも自動で走る。

関連項目

• ドキュメントの位置づけ — 何を残すか
• ドキュメント体系のつくり方 — どこに置くか