{ End Bracket }
文書を書くエンジニア
Richard Ward
私は、MSDN Magazine のスタッフがコラムの執筆を依頼してきたときに、少し愉快な気持ちになりました。エンジニアはコラムを書くなどと考えていないだろうから、こんな依頼をすると無愛想な対応をされてしまうのではないか、と言わんばかりのスタッフの不安な気持ちが垣間見えたからです。このような状況は予想よりも頻繁に起こりますが、これはもっと一般的な問題を暗示しています。
エンジニア、およびソフトウェアの作成にかかわるすべての人は、言葉でのコミュニケーションができる必要があります。ただし、これは話をするという意味ではありません。口頭でのコミュニケーションはすばらしいものです。ホワイトボードを使ったり、昼食をとりながら少人数で詳細について話し合うことは、設計を完成させるうえで非常に重要です。短時間でやり取りすることで、さまざまな意見を検討し、直ちにフィードバックを得ることができます。しかし、この方法は本質的に正確さに欠けています。会話の中で深められた理解や、会話の参加者によって築かれた共通の状況が、その会話の範囲を超えて影響を及ぼすことはまれです。会話に参加していない人々が使用できるのは文書化されたものだけです。
意見や考えを書き留めることは、開発プロセスにとって不可欠です。ソフトウェア製品の適切な設計レベルを構成する内容については多くの考え方がありますが、最終的に、設計のいくつかの部分は書き留めておく必要があります。バックアップ製品はその復元機能を検証しない限り役に立たないという考え方と同様に、文書化する内容は対象読者が理解できる内容でなければなりません。だれかがドキュメントを読み、その目的が理解できない場合、それどころかまったく間違って理解してしまった場合、プロセスは失敗に終わります。
エンジニアリング ドキュメントを記述するときに何を使用する必要があるかについては、さまざまな考え方があります。私は "目的に適した手段を使う" タイプの人間なので、それについて特に論争を起こすつもりはありません。高度に構造化された正確な言語から、それほど形式的でない自然言語に至るまで、さまざまな言語が使われる可能性があります。たとえば、正確なモデルは、2 つのインスタンス間のやり取り (ネットワーク プロトコルなど) を指定するときに役立ちます。これらの形式は、ある意味、設計を表現する実際のコードから抽出された 1 ステップであるため、設計方法を非常に効果的に表現できます。しかし、設計の理由については説明されません。
自然言語は、本質的に正確さには欠けていますが、実際の設計以外の考えを表現するうえで非常に優れています。建築にたとえると、建築家は、アトリウムの構造や土台、照明の特徴、およびその他の多くのサブシステムとディテールを正確に示す構想を持っている場合があります。これらはすべて、それぞれに特化した図面に描かれています。しかし同様に、建築家には、人々を建物の中に集め、階上に上がって窓のそばを通ってもらうというアトリウムの目的、およびその他の多くのディテールの目的に関して伝えたいことがあるかもしれません。このような目的を最もうまく表現するのは技術的でない言語です。これにより、読者は自分なりの理解を深め、設計の他の部分を理解するための基礎とすることができます。
このことは、検討されているドキュメントの対象読者の範囲が広いほど、より明確になります。あるエンジニアリング スタッフは、コンポーネントの動作について詳細に書かれた正確なドキュメントに感謝するかもしれませんが、チームの他のスタッフには別のニーズがあります。設計の構想は、原案から始まって、組織全体に至るまでには段々と広がってくるため、新しい読者とのコミュニケーションで求められるものは多くなっていきます。初歩レベルの設計文書を顧客に提供する必要はめったにありませんが、多くの場合、求められる内容を、多様な読者が理解しやすく、さまざまなレベルの読者にアピールできる方法で記述された形式にしておくと便利です。
最近、私は設計文書の中の、多くのコンポーネントに影響を与える変更の提案について確認するよう別のチームから依頼されました。この文書は非常に詳細に書かれており、変更されるほぼすべての機能、メモリ フットプリント、読み込み順序について明記されていました。すべてが慎重に調べられていました。しかし、1 つ不足していたのは、なぜこの変更が行われるかという説明です。提供されているデータはすべて申し分のないものでしたが、その評価の枠組みがありませんでした。このプロジェクトのエンジニアは作業にかなり深く携わっていたため、変更が提案された理由をすべての読者が把握していると思い込んでいたのです。この文書では、提案された変更 (高度に構造化された言語で記述) の説明を掲載した序文 (自然言語で記述) が大いに役立ちました。
エンジニアは文書を書くことに不信感を持つ必要はありません。書くことは、作業の重要な部分です。製品を完成させるには、他の人と情報をやり取りできる必要があります。より使い慣れた形式があるかもしれませんが、実際に必要なのは、伝えたい内容を読者が受け取って理解することです。そもそも、自然言語ほどわかりやすい表現で自分の言いたいことを伝えられなかったとしたら、まったく正確かつ厳格なコンピュータからあなたの望む結果が得られるでしょうか。
Richard Ward は、マイクロソフトの Distinguished Engineer です。コア オペレーティング システム部門の一環としてコア アーキテクチャ チームにも参加しており、そこで分量の多いドキュメントをよく執筆しています。