技術ブログのスタイルガイドを設計する — 読者の時間を最適化する8つの原則

はじめに

このブログで8本の記事を書いた時点で、自分の中に暗黙のルールが形成されていることに気づいた。タイトルの付け方、冒頭の書き出し、コードブロックの量、まとめの構成 — 毎回似たパターンで書いている。ならばそれを言語化して、再現可能なスタイルガイドにしよう。

スタイルガイドを作る目的は文章の均一化ではない。読者の時間を最適化することだ。技術ブログの読者は忙しい開発者で、記事を最初から最後まで読むことは稀だ。タイトルで判断し、冒頭で価値を見極め、見出しで飛ばし読みし、コードブロックで手を動かし、まとめで要点を回収する。このスキャンパターンに最適化された記事を書くのがゴールだ。

以下では、スタイルガイドの各ルールについて「なぜそのルールなのか」を解説する。ルール自体の詳細は CLAUDE.md を参照してほしい。

原則 1: タイトルで「何が得られるか」を示す

悪い例と良い例を並べると違いは明白だ。

ルールは3つ。技術名を入れる、成果から書く、フィラーを削る（「〜について」「How to」「Introduction to」）。

タイトルがこのフィルタを通過するだけで、検索結果やSNSでのクリック率が変わる。読者はタイトルだけで「自分の問題を解決してくれるか」を判断するからだ。逆に言えば、タイトルが曖昧な記事は、どれだけ中身が良くても読まれない。

原則 2: description は「固有の価値」を書く

description は検索結果とSNSカードで表示される120〜200文字だ。ここに汎用的な要約を書くのは機会損失になる。

# 避けるべき
"Next.js で OG 画像を動的に生成する方法を学びましょう。"

# 推奨
"opengraph-image.tsx と Satori でビルド時に記事ごとの OG 画像を静的生成する。
最大の落とし穴は Satori のインラインスタイル制約 — Tailwind も className も使えない。"

良い description には2つの要素がある。何をするか（OG 画像の静的生成）と固有の知見（Satori のインラインスタイル制約）。後者が決定的に重要で、「この記事を読む理由」を30文字で伝えている。

原則 3: 冒頭で「なぜ読むべきか」を3文以内に

記事の冒頭は読者が「続きを読むか閉じるか」を決める場所だ。「このブログは X を使っています」から始まる記事は、読者の関心に答えていない。

スタイルガイドでは2つのパターンを使い分けている。

• ## 課題 — 解決すべき明確な問題がある場合。読者が「あ、自分も同じ問題を抱えている」と共感できる
• ## はじめに — 新機能の追加やアーキテクチャの解説など、問題より動機が先にある場合

どちらのパターンでも、最初の1〜2段落で読者が得る価値を提示する。実装の詳細は本文で述べればいい。

このブログの記事を振り返ると、6本が ## 課題 で始まり、2本が ## はじめに で始まっている。問題駆動型の記事は冒頭が書きやすい — 問題を述べるだけで読者の関心を引けるからだ。

原則 4: 記事タイプを意識して構成を選ぶ

すべての記事がステップバイステップのチュートリアルではない。このブログでは主に5つのタイプを使い分けている。

• Build log — 何かを構築した過程を共有する（TIL セクション追加、注目記事セクション）
• Problem → Solution — 問題の調査から解決までを追う（レスポンシブ対応、backdrop-filter の罠）
• Deep dive — 仕組みの理解を段階的に深める（ブログ全体のアーキテクチャ解説）
• Migration — 移行の動機、手順、結果を示す（Serwist/Turbopack 移行）
• Comparison — 選択肢を評価し、判断理由を述べる（まだ未公開）

重要なのは、多くの記事が複数のタイプを混合していることだ。レスポンシブ対応の記事は「Problem → Solution」が主軸だが、ハンバーガーメニューの部分は「Build log」の要素を含んでいる。タイプは主軸の構成を選ぶためのガイドであり、厳密なカテゴリではない。

原則 5: 面白い部分を見せ、自明な部分を省く

技術記事で最も価値のあるコンテンツは、公式ドキュメントに書かれていないことだ。

含めるべきもの:

• ハマりポイント、驚いた挙動 — 読者のデバッグ時間を節約する
• 「X ではなく Y を選んだ理由」— 設計判断の背景
• ビフォー/アフターの比較 — 改善を具体的にする
• エラーメッセージや症状 — 検索でたどり着く人のために

省くべきもの:

• ファイル全体のコード — 面白い20%だけ見せて、残りは散文で要約する
• テストコードの全文 — テスト戦略自体がテーマでない限り、何をテストしたかを述べれば十分
• 変更ファイル一覧 — PR に書くべきもの
• ボイラープレートのセットアップ手順 — 公式ドキュメントにリンクする

コードブロックは 3〜5個 を目安にしている。7個を超えたら、一部を散文に置き換えるか、1つの注釈付きブロックに統合することを検討する。

原則 6: 「まとめ」で転用可能な知見を抽出する

まとめセクションは記事の要約ではない。読者が自分のプロジェクトに持ち帰れる知見を抽出する場所だ。

フォーマットは統一している。太字のリードフレーズ + ダッシュ + 説明文の箇条書きだ。

## まとめ
 
- **太字の知見** — その知見がなぜ重要か、どう応用できるかの説明。
- **太字の知見** — その知見がなぜ重要か、どう応用できるかの説明。

悪いまとめは「X を追加した」「Y を修正した」という行動の列挙になる。良いまとめは「default(false) でスキーマ変更を安全に」のように、記事の文脈を超えて適用できる原則を抽出する。

3〜4項目が適量だ。1記事に5つ以上の重要な知見があるなら、記事自体のスコープが広すぎる可能性がある。

原則 7: 1記事1アンカーインサイト

すべての記事には、読者が記憶する1つの核心的な知見が必要だ。

レスポンシブ対応の記事を例にとろう。この記事はハンバーガーメニュー、スペーシング、タイポグラフィ、タッチターゲットと複数のトピックを扱っている。しかしアンカーインサイトは明確で、「backdrop-filter が fixed 子要素の包含ブロックを作る」というCSS仕様のエッジケースだ。タイトルにも「backdrop-filter の罠で全部壊れた話」と入っている。

複数のトピックを1記事にまとめること自体は問題ない。ただし、それらを結びつけるアンカーが必要だ。共通のスレッドがなければ、別々の記事に分割すべきだ。

原則 8: バイリンガルは直訳ではなく並行

このブログは日英の2言語で公開している。スタイルガイドでは、2つのバージョンは並行だが直訳ではないと定めている。

技術的な内容、コード例、記事の構成は揃える。しかし文章の表現や例えは、それぞれの言語で自然に読めるように適応させる。日本語の読者と英語の読者が言語を切り替えたときに同じ情報が見つかることが重要で、一字一句の対応は重要ではない。

スタイルガイドを振り返って

8つの原則はすべて「読者の時間を尊重する」という1点に収束する。

• タイトルと description → 読むべきか5秒で判断できる
• 冒頭 → なぜ読む価値があるか3文以内でわかる
• 見出しと構成 → 飛ばし読みで全体像が掴める
• コード量 → 重要な部分だけ集中できる
• まとめ → 持ち帰れる知見が一目でわかる

スタイルガイドは完成品ではない。記事を書くたびに暗黙のルールが更新され、それを言語化するサイクルが続く。ただし、「読者の時間の最適化」という中心原則は変わらないと考えている。このフィルタを通して判断すれば、個々のルールは自然に導き出せるからだ。