TIL スタイルガイドの設計 — 完璧主義を捨てて「30秒で伝わる」を目指す
目次
はじめに
ブログ記事のスタイルガイドを作った後、TIL（Today I Learned）セクションにも同じことが必要だと気づいた。ただし、ブログ記事のスタイルガイドをそのまま縮小コピーしても意味がない。TIL はブログ記事とは根本的に目的が違う。
ブログ記事は「深い知見を構造的に伝える」メディアだ。タイトル、冒頭のフック、本文の構成、まとめの抽出 — 読者の時間を最適化するために設計されたルールがある。一方、TIL は**「30秒で1つの発見を共有する」**メディアだ。最適化すべきは読者の時間だけでなく、書き手のハードルの低さでもある。
このバランスがスタイルガイドの設計で一番難しかった部分だ。
なぜ TIL に専用のスタイルガイドが必要か
TIL セクションを作って最初に気づいたのは、ブログ記事の書き方が身についていると、短い文章を書くのが逆に難しいことだった。「もう少し背景を書いた方がいいのでは」「代替案の比較も入れるべきか」「まとめセクションは要るか」— こういった衝動をすべて退ける必要がある。
TIL の最大の敵は完璧主義だ。「もう少し調べてから」「もう少し整えてから」と思っているうちに、発見の鮮度が失われ、結局書かれない。スタイルガイドの最も重要な役割は、「これで十分」の基準を明確にして、公開への心理的ハードルを下げることだ。
ブログ記事との境界線
TIL とブログ記事の最も実用的な境界線は2つ。
##見出しが必要になったらブログ記事 — TIL で見出しを使いたくなるのは、内容が1つの発見に収まっていないサインだ- 500語を超えたらブログ記事 — 日本語で原稿用紙1枚強。これを超えると「気軽に読める」とは言いにくい
逆に言えば、100〜300語で十分だ。コードブロック1つと数行の説明で完結する TIL は多い。「短すぎるのでは」と思ったら、それはたぶんちょうどいい。
このブログの既存 TIL を見てみると、prose-table-nowrap は約150語、use-cache は約200語。どちらも読者に十分な価値を提供できている。
タイトル: 発見そのものを書く
TIL のタイトルはブログ記事以上に重要だ。TIL は短いので、タイトルだけで読むかどうかを判断される。そしてタイトルが十分に情報量を持っていれば、タイトルだけで学べることもある。
パターンは [技術/文脈] + [学んだこと・解決策] だ。
| 避けるべき | 推奨 |
|---|---|
| テーブルの問題 | Markdown テーブルの列幅制御は CSS の white-space: nowrap で解決する |
| Next.js のキャッシュについて | Next.js の 'use cache' ディレクティブでコンポーネントレベルのキャッシュが可能 |
悪いタイトルは「何の話か」しか伝えない。良いタイトルは「何を学べるか」まで伝える。この差は検索結果での CTR に直結する。
自然な日本語パターンとしては 〜できる、〜で解決する、〜は〜だった、〜には〜を使う がある。英語では事実やテクニックをそのまま述べる形が自然だ。
構成: テンプレートではなく自然な流れ
TIL にはブログ記事のような厳密な構成ルールは要らない。ただし、自然な流れはある。
- 文脈（1〜2文） — 何をしていたときにこれを発見したか。読者が「あ、自分もやる」と思える場面設定
- 発見（本体） — 学んだこと。コード例があると説得力が増す
- ひとこと（任意） — なぜ重要か、何を置き換えるか。なくても成立するなら省く
「まとめ」セクションは書かない。TIL は十分に短いので、読者はすでに全体像を把握している。最後の有用な情報で終わる。
トーンの違い: Slack のメッセージに近づける
ここがブログ記事のスタイルガイドとの最大の差別化ポイントだ。
ブログ記事は「会話的だが正確」なトーンを求めている。TIL はそこからさらにカジュアル寄りに振る。チームの Slack に「これ知ってた？」と投げるくらいの気軽さが理想だ。
具体的には：
- 驚きをそのまま書く — 「
fetchだけじゃなくて任意の async 関数に使えるとは」「Markdown 側のアプローチは完全に効果なしだった」。この「へぇ」の瞬間を読者と共有するのが TIL の醍醐味 - うまくいかなかったことに触れる — 最初の直感的なアプローチが失敗した場合、1〜2文で言及する。読者を同じ行き止まりから救える
- コードに語らせる — 短いコード例はしばしば段落の説明より雄弁だ。コードが示していることを散文で繰り返さない
この「気軽さ」は単なるスタイルの問題ではなく、公開頻度に直結する。「もっと丁寧に書かないと」というプレッシャーが減れば、発見から公開までの時間が短くなり、結果として TIL の本数が増える。
検索可能性: 未来の自分のために
TIL は書いた本人が数ヶ月後に「あれ、あの解決策なんだっけ」と検索して見つけるケースが多い。このユースケースを意識すると、書き方が変わる。
- エラーメッセージはそのまま引用する — 開発者が検索エンジンに貼り付けるのはエラーメッセージそのものだ
- 技術用語を正確に使う — 関数名、ディレクティブ名、CSS プロパティ名、CLI フラグ。曖昧な言い換えは検索に引っかからない
- 症状を具体的に書く — 「テーブルのレイアウト問題」ではなく「日本語2文字の列が縦に折り返される」
prose-table-nowrap TIL がこのパターンの好例だ。「日本語2文字の列が縦に折り返される」という具体的な症状と、white-space: nowrap という正確な CSS プロパティ名の両方を含んでいる。
コードブロック: 1〜2個、最大3個
TIL のコードブロックは 1〜2個 が適量だ。「うまくいかなかった例 → うまくいった例」の2ブロックパターンが自然に機能する。
3個でも許容できるケースはある。「最初に試したこと → 設定の変更 → 結果」のような流れだ。しかし4個以上必要になったら、それはおそらくブログ記事として書くべき内容だ。
良い TIL のトピックとは
スタイルガイドでは6種類のトピックを挙げているが、共通するのは「公式ドキュメントを読んだだけでは気づきにくい」という性質だ。
- 非自明な API 挙動 —
use-cacheがfetchだけでなく任意の async 関数に使える - ドキュメントに埋もれた設定オプション —
cacheLifeのプリセットプロファイル - CSS レンダリングの回避策 —
white-space: nowrapでテーブル列の折り返しを防ぐ - バージョン間の挙動変更 — アップグレード時に気づく差異
逆に、TIL に向かないのはステップバイステップのチュートリアル、複数の選択肢の比較、すでに目立つ場所にドキュメントがあるもの。これらはブログ記事に書くか、単にドキュメントにリンクすべきだ。
スタイルガイド全体を振り返って
TIL のスタイルガイドの核心は、書くハードルを下げることが読む価値を上げることにつながるという逆説だ。
完璧に仕上げようとして公開されない TIL は、読者にとって価値ゼロだ。100語のラフな TIL でも、公開されていれば誰かの30分を節約するかもしれない。スタイルガイドはこの「十分」の基準を明確にすることで、発見から公開までの摩擦を最小化している。
ブログ記事が「読者の時間を最適化する」メディアだとすれば、TIL は「書き手と読者の両方のハードルを最小化する」メディアだ。どちらも最終的には読者に価値を届けるという目的は同じだが、そこに至るアプローチが違う。
