「〜について」と書いてはいけない
文書のタイトルや見出しに、「~について」と書く人が多いが、「~について」という言葉はいかなる場合でも絶対に書いてはならない。
「~について」というボカし方をすると、中にどんなことが書いてあるのか推測できない。記載範囲が広過ぎると、何でもそこに書けてしまう。テーマをもっと狭めておかないと、「神クラス」ならぬ「神ドキュメント」になってしまい、情報の検索性・一覧性が逆に落ちる。
タイトルや見出しを適切に付けられず、「~について」と安易に書いてしまい、その悪影響に全く思考が至らぬ人間は、「概念化」「抽象化」「共通化」といった、物事を構造的に認識する能力が欠落している。こういう人はタスクの分割も正しく出来ないし、ディレクトリやファイルの整理も出来ない。コードも責務が分割出来ていなかったりして低品質極まりない。会話をしていてもまとまりのない話しをよくしていて、自分が何を分かっていないか理解できていない。あらゆる場面で迷惑な存在なので、まずは「~について」と書きたくなった時に複数の見出しに分割することから機械的にやってみよう。
- ex. 「コードレビューについて」
- 「コードレビューを依頼する側の手順」の説明なのか?それとも「コードレビューをする側が知るべきチェックポイント」の話なのか?が、タイトルから読み取れない
- 大抵はどうせ、どちらの内容も混ぜこぜに書かれている。そうすると、読み手が各々の立場で必要な情報を探し回りながら読まないといけなくなり、理解に時間がかかる
- 「レビューイがレビュー依頼時に行う作業手順」と、「レビューアがレビュー時に確認すべき代表的なチェックポイント集」といった複数の見出しに別けて書けば、レビューイとレビューアはそれぞれの章だけ読めば必要な情報が理解できる
- 関連ブログ記事 : 2018-09-24 文書や記事のタイトルに「〜について」は止めよう