アーキテクチャ/設計文書
出典: フリー百科事典『ウィキペディア（Wikipedia）』 (2021/09/20 16:08 UTC 版)
「ソフトウェアドキュメンテーション」の記事における「アーキテクチャ/設計文書」の解説
設計文書は様々な形式がある。どのように（HOW）使うのかよりも、なぜ（WHY）そのように設計されているかを解説することに注力していることが多い。例えば、データ構造がそのようになっている背景となる原理を解説したり、特定オブジェクトのメンバー関数をリストアップしたり、コードの追加方法を記述したりする。あるクラスがなぜそのように構成されているかを説明し、パターンを示し、よりよい方法の概略を提案したり、今後の改善を提案したりする。これらは、コードに関する文書やユーザー向け文書には不適切だが、設計にとっては重要である。 アーキテクチャ文書は設計文書の特殊例である。ある意味で、アーキテクチャ文書はコードからの第3の生成物（第1はコードに関する文書、第2は設計文書）である。アーキテクチャ文書にはコードに固有な部分はほとんどない。特定のルーチンのプログラム方法を説明することはほとんどなく、あるルーチンがなぜ現在のような形になっているかさえ説明しない。代わりにそのルーチンの存在意義や動機となった要求仕様などを解説する。よいアーキテクチャ文書は詳細に関しては紙幅を費やさず、解説に重きをおく。下位の設計の方針を示唆することもあるが、そこに踏み込むことはせず、他の文書に任せる。 その他の設計文書として類似製品との比較文書がある。これは「ホワイトペーパー」の形式となることが多い。ある特定の観点でシステムを論じ、代替手法を示唆する。その観点はユーザーインターフェイス、コード、設計、アーキテクチャなど様々である。現状を概説し、複数の代替手法を説明し、それぞれの長所と短所を列挙する。よい比較文書はしっかりした研究の上に成り立ち、考えを明確に述べ（読者を戸惑わせる専門用語を使わず）、何よりも公平である点が重要である。比較文書の目的は、特定の観点を押し付けるというよりも、最善の解決法を見出すことである。結論に至らない場合でも全く問題はなく、現在の状況を改善するような代替案が全くないという結論であっても構わない。比較文書はマーケティングの道具として最初から執筆するのではなく、あくまでも科学的な考察の上で書かれるのがよいとされる。
※この「アーキテクチャ/設計文書」の解説は、「ソフトウェアドキュメンテーション」の解説の一部です。
「アーキテクチャ/設計文書」を含む「ソフトウェアドキュメンテーション」の記事については、「ソフトウェアドキュメンテーション」の概要を参照ください。
- アーキテクチャ/設計文書のページへのリンク
