10. ドキュメント

あなたは文が書けるようになり、段落も書けるようになりました。しかし、たくさんの段落を一つの筋の通ったドキュメントにまとめるにはどうすればよいのでしょうか？

ドキュメントの目的を述べる

良いドキュメントはその目的 (スコープ) を定めることから始まります。例を示します:

良いドキュメントは加えて目的でないことも定めます。目的でないこととはつまり、対象読者がドキュメントに期待する可能性のあるもののそのドキュメントが触れないトピックです。例を示します:

このように目的と目的でないことを述べておくと、読者だけではなく著者 (あなた) の役にも立ちます。執筆の間にドキュメントの内容が目的から逸れてしまったときに、ドキュメントの内容を再考するか、ドキュメントの目的を変えるかを迫られるからです。初稿の推敲では、最初に述べられた目的から外れる部分は全て削除 (あるいは他のドキュメントに移動) してください。

対象読者を述べる

良いドキュメントは対象読者をはっきりと示します。例を示します:

読者の肩書きだけではなく前提となる知識や経験を示すのも良い対象読者の示し方です。例を示します:

対象読者の説明に前提となるドキュメントを含めなければならない場合もあるでしょう。例えば次のようにします:

重要な点を最初にまとめる

エンジニアや科学者は忙しく、76 ページに渡るあなたのデザインドキュメントを全て読むとは限りません。あなたの同僚は最初のページの最初の段落しか読まないかもしれないと想像してみてください。ドキュメントをレビューするときは、ドキュメントの先頭部分が読者の抱える重要な疑問に答えていることを確認しましょう。

プロのライターは読者が二ページ目に進む確率を上げるために最初のページに非常な労力を費やします。しかしどんな長いドキュメントでも最初のページは最も書くのが難しいページです。最初のページは何度も推敲する覚悟をしておきましょう。

エンジニアリングに関係する長いドキュメントには必ず要約 (executive summary,TL;DR) を付けてください。要約は非常に短くなければなりませんが、書くのには長い時間がかかるはずです。退屈な要約や分かりにくい要約は未来の読者を遠ざけるレッドフラグです。

読者に向けて書く

このコースでは読者を定めることの重要性を繰り返し強調してきました。この節では、対象読者の設定をドキュメントを構成する手段として見ていきます。

読者を定める

次の質問に答えることで、ドキュメントに含めるべき内容を精査できるでしょう:

• 対象読者は誰ですか？
• 読者がドキュメントを読む前から知っていることは何ですか？
• 読者がドキュメントを読んだ後に理解すること、およびできるようになることは何ですか？

例えば、あなたが新しいソートアルゴリズムを発見したとします。このとき上の質問に対する答えの一例は次のようになります:

• 対象読者は同じ組織のソフトウェアエンジニア全員です。
• 対象読者の大部分は学生のときソートアルゴリズムを勉強したことがあります。しかし対象読者の 25% はもう何年もソートアルゴリズムを実装・評価していません。
• このドキュメントを読んだ後:
  1. 読者は新しいアルゴリズムがどのように動くかを理解します。
  2. 読者は好きな言語で新しいアルゴリズムを実装できます。
  3. 読者は新しいアルゴリズムが有名なクイックソートアルゴリズムを上回る状況を理解します。
  4. 読者は特定のエッジケースにおけるパフォーマンスの低下を理解します。

構成

対象読者を定めたら、次はドキュメントを読了した読者が理解・習得すべきことを提供するためにドキュメント全体を構成していきます。上の例では、ドキュメントのアウトラインは次のようになるでしょう:

1. アルゴリズムの概要
   1. ビッグオー
   2. 疑似コードを使った実装
2. C のサンプル実装
   1. 他の言語で実装するときのコツ
3. アルゴリズムのさらに詳細な解析
   1. 最適なデータセット
   2. エッジケースの問題

さらに、ドキュメントを執筆する正しいアプローチの選択には前もって定めた対象読者を役立ててください。例えば対象読者がソートアルゴリズムを勉強したことがあっても、その四分の一は様々なソートアルゴリズムの詳細を忘れているかもしれません。その場合には、クイックソートを説明するよりも既存のクイックソートのチュートリアルへのリンクを入れた方がよいでしょう。

トピックを節に分ける

コードはファイル・クラス・メソッドを使ってモジュール化し、モジュール化されたコードは読解・理解・保守・再利用が簡単になります。ドキュメントをモジュール化すれば同じ効果が得られます。コードの機能的なモジュール性についてあなたは鋭い直感を持っていると思いますが、その原理を執筆に適用するにはどうすればよいでしょうか？

空の瓶を持っていて、その中に大きな岩・粗い砂利・細かい砂を詰めなければならない状況を想像してください。瓶の中に全ての岩・砂利・砂を入れるには、どのように詰めるべきでしょうか？ もちろん最初に入れるのは大きな岩で、その次に砂利を注ぎ、最後に残った空間を砂で埋めるべきです。これと逆の順番で詰めようとすれば失敗するでしょう。

読者の頭headも空の瓶jarのようなもので、あなたが伝える情報もたいてい三つのサイズ (岩・砂利・砂) を持ちます。節 (section) が岩です。読者の頑固な頭jar-headに伝えたい情報を全て詰め込むためには、まず岩で頭の中に空間を作ってやらなければなりません。

どれが大きな岩でどれが砂であるかをどうすれば判断できるでしょうか？ 一つの方法は、ドキュメントのトピックについて少しの間自由に話す (または書く) 様子を録画するというものです ── 2 分から 5 分程度で十分でしょう。もちろん、これには鍛錬が必要です。こうして得られたものをよく見てください。次のことができていますか？

• 概念を詳細でない大まかな言葉で説明する。
• 読者が目標を達成するために完了すべきステップを挙げる。
• システムが持つ特徴を全て説明する。

あなたが言及した大まかな物事はおそらくトピックを形作る重要な概念です。もしあなたの話がそうなっていないなら、もう一度戻ってこの構造を意識してみてください。

練習問題

次の文章はあるドキュメントの最初の段落です。このドキュメントのトピックを節に分けるとき、ふさわしい節のタイトルを答えてください。