10. ドキュメント

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

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

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

This document describes the overall design of Project Frambus.

(このドキュメントは Frambus プロジェクトの全体的な設計を説明する。)

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

This document does not describe the design for the related technology, Project Froobus.

(このドキュメントは関連する技術である Froobus プロジェクトの設計は説明しない。)

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

対象読者を述べる

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

I wrote this document for the test engineers supporting Project Frambus.

(私は Frambus プロジェクトをサポートするテストエンジニアのためにこのドキュメントを書いた。)

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

This document assumes that you understand matrix multiplication and how to brew a really good cup of tea.

(このドキュメントは読者が行列の掛け算と非常に優れた紅茶の淹れ方を知っていることを仮定する。)

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

You must read “Project Froobus: A New Hope” prior to reading this document.

(このドキュメントを読む前に、あなたは “Project Froobus: A New Hope” を読まなければならない。)

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

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

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

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

読者に向けて書く

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

読者を定める

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

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

構成

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

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

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

トピックを節に分ける

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

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

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

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

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

練習問題

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

AlienWarez is a large-scale machine learning system. AlienWarez is best at building models for high-dimensional, sparse feature spaces. AlienWarez automatically explores and learns feature crosses that explain your data. AlienWarez refers specifically to the model training system. You train a model by extracting features from your source (log) data, and writing a data source for the training system. The Seti infrastructure team also provides a complete serving system. You are responsible for starting your own serving cluster, and moving your model to serving. The Seti serving system can serve AlienWarez, Seti, and Sibyl models. This guide explains how to train a AlienWarez model, and how to serve the model in production.

(AlienWarez は大規模機械学習システムである。AlienWarez は高次元かつ疎な特徴量空間に対するモデルの作成に最も優れる。AlienWarez はデータを説明する特徴量交叉 (feature cross) の探索・学習を行う。AlienWarez はモデル訓練システムだけを特に指す言葉である。モデルの訓練はソースデータ (log) から特徴量を抽出し、訓練システムに対するデータソースを書くことによって行う。Seti インフラチームは完全なサービングシステムも提供する。ユーザーは自分用のサービングクラスターを開始し、モデルをサービング状態に移行させる責任がある。このガイドは AlienWarez モデルを訓練する方法とそのモデルをプロダクションでサーブする方法を説明する。)

解答例を示します:

  1. Training a model
    1. Developing features
    2. Creating a data source
    3. ...
  2. Serving a model
    1. Starting a serving cluster
    2. Moving your model into serving
    3. Retrieving a prediction from serving
    4. ...
  1. (モデルの訓練
    1. 特徴量の開発
    2. データソースの作成
    3. ...
  2. モデルのサーブ
    1. サービングクラスターの開始
    2. 自身のモデルのサービング状態への移行
    3. サービング状態のモデルから予測を取得する
    4. ...)