わかりやすいドキュメントを書くコツ(2):章立てを考える

今回は実際にドキュメントを書く時のコツについて説明します。
(ちなみに、ここでいう「ドキュメント」とは、要件定義書や機能仕様書、取扱説明書など私たちSEが開発工程でよく作成する文書のことを指します。)

ドキュメントを書く時にいきなり文章を書き始めてはいけません。

最初にやるべきことは、文章全体の章立てを考えることです。

章立てはドキュメントの骨組みです。章立てを考えることはドキュメントの全体像を把握する上で重要な作業となります。

良い章立てを組み立てるコツとして、以下の点を参考にしてみてください。

概観から詳細へ

いきなり細かい内容に触れず、まずは概観を示しましょう。概観を示すことで、これから何が書かれているのかを読み手がイメージしやすくなり、より細かな内容も理解しやすくなります。

また、章が進むにつれて概観→詳細へと落とし込むような構成で組み立てることで、読む人が必要とする情報量に合わせていつでも読むのをやめることができる、というのもポイントです。

最後まで読まないと言いたいことがわからない構成は読み手にとって優しいドキュメントとは言えません。

知りたいことがまとまっている

知りたいことを探す時に、情報があちこちに散らばっていると探すのに時間がかかったり見落としてしまい、結果思ったような情報収集ができないことがあります。

1つのテーマはできるだけ一箇所でまとめるようにし、複数にまたがる場合は参照先を記述するなどの工夫をしましょう。

以下の2つの文章を見比べてください。

バターチキンカレーの作り方

  1. 玉ねぎ中1個はみじんぎりにする
  2. 鶏もも肉 300g を一口大に切ってヨーグルト 100g に1時間漬けておく
  3. 玉ねぎと鶏もも肉フライパンで炒める
  4. トマトの水煮1缶、カレー粉 大さじ1、バター20g を加えて20分煮込む
  5. 完成までの所要時間は1時間30分です
バターチキンカレーの作り方

  1. 所要時間 1時間30分(準備含む)
  2. 材料
    ・鶏もも肉 300g
    ・ヨーグルト 100g
    ・カレー粉 大さじ1
    ・玉ねぎ 1個
    ・トマトの水煮 1缶
    ・バター 20g
  3. 準備
    ・鶏もも肉を一口大に切ってヨーグルトに1時間漬けておく
  4. 手順
     4-1 玉ねぎはみじん切りにする
     4-2 玉ねぎと、3で用意した鶏肉をフライパンで炒める
     4-1 トマトの水煮1缶、カレー粉、バターを加え20分煮込む

前者の場合、必要な材料が何なのか、所要時間がどのくらいかだけを知りたかったとしても最後まで読まないとわからないのに対し、後者は、必要な情報が章ごとにまとまっているため、すぐできる料理かどうかや、材料だけを知りたい場合は該当する章だけを読めばよくなっています。

まとめ

私たちがどこかを訪ねる時は住所を元にして場所を探しますが、章立ても同じです。

大きな情報から小さな情報へと辿ることで迷うことなく目的地へ到着できるような章構成にしましょう。

前の記事
わかりやすいドキュメントを書くコツ」の目次
  1. 読み手をイメージする
  2. 章立てを考える

Follow me!

この記事を書いた人

伊藤いづみ
伊藤いづみ
トラスティアの受託開発メンバー。
好きな言葉は“死ぬこと以外、かすり傷”