わかりやすいドキュメントを書くコツ(2)：章立てを考える
今回は実際にドキュメントを書く時のコツについて説明します。
（ちなみに、ここでいう「ドキュメント」とは、要件定義書や機能仕様書、取扱説明書など私たちSEが開発工程でよく作成する文書のことを指します。）
ドキュメントを書く時にいきなり文章を書き始めてはいけません。
最初にやるべきことは、文章全体の章立てを考えることです。
章立てはドキュメントの骨組みです。章立てを考えることはドキュメントの全体像を把握する上で重要な作業となります。
良い章立てを組み立てるコツとして、以下の点を参考にしてみてください。
概観から詳細へ
いきなり細かい内容に触れず、まずは概観を示しましょう。概観を示すことで、これから何が書かれているのかを読み手がイメージしやすくなり、より細かな内容も理解しやすくなります。
また、章が進むにつれて概観→詳細へと落とし込むような構成で組み立てることで、読む人が必要とする情報量に合わせていつでも読むのをやめることができる、というのもポイントです。
最後まで読まないと言いたいことがわからない構成は読み手にとって優しいドキュメントとは言えません。
知りたいことがまとまっている
知りたいことを探す時に、情報があちこちに散らばっていると探すのに時間がかかったり見落としてしまい、結果思ったような情報収集ができないことがあります。
１つのテーマはできるだけ一箇所でまとめるようにし、複数にまたがる場合は参照先を記述するなどの工夫をしましょう。
以下の２つの文章を見比べてください。
- 玉ねぎ中１個はみじんぎりにする
- 鶏もも肉 300g を一口大に切ってヨーグルト 100g に１時間漬けておく
- 玉ねぎと鶏もも肉フライパンで炒める
- トマトの水煮１缶、カレー粉 大さじ１、バター20g を加えて20分煮込む
- 完成までの所要時間は１時間30分です
- 所要時間 １時間30分（準備含む）
- 材料
・鶏もも肉 300g
・ヨーグルト 100g
・カレー粉 大さじ１
・玉ねぎ １個
・トマトの水煮 １缶
・バター 20g - 準備
・鶏もも肉を一口大に切ってヨーグルトに１時間漬けておく - 手順
４－１ 玉ねぎはみじん切りにする
４－２ 玉ねぎと、３で用意した鶏肉をフライパンで炒める
４－１ トマトの水煮１缶、カレー粉、バターを加え20分煮込む
前者の場合、必要な材料が何なのか、所要時間がどのくらいかだけを知りたかったとしても最後まで読まないとわからないのに対し、後者は、必要な情報が章ごとにまとまっているため、すぐできる料理かどうかや、材料だけを知りたい場合は該当する章だけを読めばよくなっています。
まとめ
私たちがどこかを訪ねる時は住所を元にして場所を探しますが、章立ても同じです。
大きな情報から小さな情報へと辿ることで迷うことなく目的地へ到着できるような章構成にしましょう。
- 読み手をイメージする
- 章立てを考える
この記事を書いた人
-
トラスティアの受託開発メンバー。
好きな言葉は“死ぬこと以外、かすり傷”
最新の投稿
仕事術2017年10月4日わかりやすいドキュメントを書くコツ(2)：章立てを考える
仕事術2017年7月6日わかりやすいドキュメントを書くコツ(1)：読み手をイメージする
