文書や記事のタイトルに「〜について」は止めよう
技術ブログの記事や業務の説明資料などは、タイトルが重要だ、という話。
目次
文書のタイトルの重要性
文書のタイトルとは、
- 読み手に何を知って欲しいか (読み手はその文書を読むと何が分かるか)
- 読み手にどんなアクションを取って欲しいか (読み手がその文書を読むと何ができるようになるか)
ということを一発で伝える、キャッチコピーのようなモノだ。
それと同時に、文書のタイトルを決めることで、
- その文書に掲載する情報
- その文書には含めない情報
の境界ができるワケだ。
以上のことから、タイトルが持つ役割・重要性はその文書全体、そしてその文書が果たす効果に大きな影響があることが分かる。
「〜について」という悪いタイトル
しかし、どうも文書のタイトルというモノを軽視しているか、そもそも何を書くべきか分かっていないままぼんやり書いている文書が多く、読み手にとっては知りたいことが分からず迷惑極まりない。
中でも一番よくあるのが、「〜について」というタイトル。これは物凄く分かりづらい。
- ユニットテストについて
- Android アプリ開発について
といったタイトルだ。
こうしたタイトルは、その文書がどこまで話をするのか推測しづらい。ユニットテストとは〜という話をするのか、ユニットテストツールの話をするのか、それとも方法論やテストコードの良い設計について話すのか、範囲が分かりづらい。
こうしたタイトルを付けたくなっている場合、大抵は以上のような話題を全て盛り込んだ文書になっていて、コレという話題を一つに絞り切れていないから、大雑把なタイトルを付けてしまうものと思われる。
分かりやすいタイトルに変える対策
「〜について」というタイトルを付けないようにする対策としては、以下のような方法が考えられる。
- メインのネタをタイトルに添え、それ以外の話題はタイトルに含めない
- 「ユニットテストツールの比較」がメインならそれをタイトルにし、「その前にユニットテストとは…」といった定義の話は文書中にあったとしてもタイトルには書かない
- 特にスライド資料の場合は、このように「メインの話題」を頑張って絞る方が、聞き手の印象に残りやすい
- タイトルが付けられる話題ごとに文書を分ける
- 「ユニットテストとは」で一文書、「テストコードを書く時のベストプラクティス」で一文書、と分ける方法
- 社内 Wiki に残す文書であれば、一つの文書は一つの話題に絞り、「ユニットテスト」という大きなジャンルは、親ページやタグでまとめる
対象のドキュメントがどのような媒体・場面で使われるモノか、という点も、タイトルの付け方に影響する点だ。
社内 Wiki に残したり、技術ブログに書く記事のタイトルであれば、「コレを読むと何が分かるか」に焦点を当てたタイトルの方が良い。例えば「ユニットテストツール Jasmine で時間を操作する方法」というように、中身を具体的に推測できるモノにする。
一方、Qiita の「ポエム」タグに投稿したり、スライド資料にするのであれば、「センセーショナル」なタイトルでまず興味を惹かせる方が面白い。例えば「ユニットテストは本当に必要なのか」といったタイトルで、その重要性を分析・説明する、とか。
もちろんこの場合も、「ユニットテストは CI のために書こう」と、結論を直接書いても間違いではないし、聞き手は内容を推測しやすくなって楽になる。このように結論・要点を先に話す「アンチクライマックス法」は、結論を最後に持ってくる「クライマックス法」より早く要点を説明できるものの、要点の後に話される補足や詳細を聞いてもらえなくなる可能性も高いので、プレゼン資料などの場合は注意が必要。社内 Wiki などであれば「アンチクライマックス法」の方が時間が削減できるのでベターだ。
「〜について」というタイトルを付けたくなった時は、そのドキュメントで扱う話題が整理できていないことの表れ。話題を整理し、ドキュメントの用途に応じて適切なタイトルを付けるようにしたい。