1ページ1トピック制の設計：学習コンテンツに「記事の粒度」を導入した理由
はじめに
このサイトを作り始めた初期、1つの記事の中に「Astroとは何か」「Astroのインストール方法」「最初のページを作る手順」の3つをまとめて書いていました。1記事で情報をまとめて提供しようという判断でした。しかしサイトに記事が増えてくると、読者がどの記事に何が書いてあるかわかりにくくなる問題が生じました。この経験から「1ページ1トピック制」という設計方針を導入しました。
1ページ1トピック制とは何か
1ページ1トピック制とは、1つの記事で1つのことしか説明しない、という設計方針です。
「Astroとは何か」と「Astroのインストール方法」は、それぞれ別の記事にします。読者が知りたいのが「Astroとは何か」という概念であれば、その記事を読む。インストール方法を知りたければ、その記事を読む。目的に応じて必要な記事に直接たどり着けるよう、記事の単位を小さく保つ方針です。
なぜこの設計方針を導入したか
読者が必要な情報に直接たどり着けない問題
複数のトピックをまとめた記事では、読者が目的の情報を探すために記事全体をスクロールする必要があります。「インストール方法だけ知りたい」読者にとって、記事の前半にある「概要説明」は確認不要な内容です。
1ページ1トピック制にすることで、読者はサイドバーやリンクから目的の記事を選び、記事全体がその目的に対応した内容であることを確認できます。
検索エンジンが記事の内容を判断しやすくなる
1つの記事に複数のトピックが混在すると、検索エンジンがその記事の主題を判断しにくくなります。「Astroとは何か」と「インストール方法」が混在した記事は、どちらの検索キーワードにも中途半端に対応した状態になります。
1記事1トピックにすることで、検索エンジンが記事の主題を正確に把握できます。
記事の更新・管理がしやすくなる
Astroのインストール手順が変わったとき、複数のトピックをまとめた記事を更新する場合、変更に関係のない部分（概要説明など）を含む記事全体を確認する必要があります。トピックごとに記事が分かれていれば、更新が必要な記事だけを確認すればよく、修正範囲が明確になります。
どこを「1トピック」とするかの判断基準
記事を分割するかどうかの判断で迷いやすい境界があります。私が実際に使っている基準を説明します。
「なぜそれをするか」と「どうやってするか」は別トピック
「Astroを選んだ理由」と「Astroのセットアップ手順」は目的が異なります。前者は判断・選択の根拠を知りたい読者向け、後者は実際に操作したい読者向けです。読者の目的が異なるものは、別の記事にします。
「概念の説明」と「操作の手順」は別トピック
「フロントマターとは何か」（概念）と「フロントマターに書く項目の一覧」（手順・参照情報）は、同じページにまとめることもできますが、記事が長くなってきたら分割の候補になります。「概念を理解する」と「操作する」は読者の目的として別です。
「同じ記事に入れるか迷ったら分割する」という原則
迷ったときは分割を選びます。後から記事同士に内部リンクを張ることで、関連する内容として読者を誘導できます。1記事にまとめると、後から分割するのが難しくなります。
実際の運用での変化
この方針を導入してから、サイドバーに表示される記事数は増えましたが、1記事あたりの文字数は減りました。読者が「これが知りたかった」という記事に直接たどり着きやすくなったという感覚があります。
記事の管理面では、更新が必要なトピックだけを特定しやすくなりました。バージョンアップに伴うコマンドの変更があったとき、変更が必要な記事が「インストール手順」「アップグレード手順」という形で明確になります。
まとめ
1ページ1トピック制は、「1つの記事で1つのことしか説明しない」という設計方針です。読者の利便性、検索エンジンへの対応、記事管理の効率という3つの観点から、この方針が有効だと判断しています。「同じ記事に入れるか迷ったら分割する」という原則を持つと、判断が速くなります。