 |
特集：ツールを使ったドキュメント作成技法（前編）価値のある開発ドキュメントを効率的に作成するには？アバナード株式会社 市川 龍太（Microsoft MVP 2008 for XML）2008/05/20 |
|
|
システム開発の現場では、さまざまなドキュメントを作成する必要がある。しかし昨今では開発の短期化に拍車がかかっており、ドキュメントを作成するための工数を十分に取れないことが多くなってきている。そこで本稿では、限られた工数の中で価値のある開発ドキュメントを効率的に作成するための技法について解説していく。
本題に入る前に、まずウォーターフォール型開発の各フェイズにおいて、一般的にどれだけのドキュメントを作成する必要があるのかについて以下の表にまとめてみた。
| フェイズ | ドキュメントの種類 |
| 要件定義 | 要件定義書 |
| 基本設計 | 基本設計書、機能仕様書、ネットワーク設計書、SW/HW（SoftWare/HardWare）構成書、セキュリティ設計書、性能・信頼性設計書、データ構造定義書（ER図）、テーブル定義書、画面定義書、画面遷移定義書、帳票定義書、開発標準書 |
| 詳細設計 | 詳細設計書、クラス設計書、構成管理定義書、インターフェイス設計書 |
| 開発／単体テスト | 単体テスト仕様書 |
| 結合テスト／システム・テスト | テスト計画書、結合テスト仕様書、システム・テスト仕様書 |
| 本番／運用 | 環境構築手順書、運用定義書、障害対応手順書、移行仕様書、移行手順書 |
 |
|
| ウォーターフォール型開発において作成されるドキュメント一覧 | |
| ※これらドキュメントはあくまで一例であり、実際には開発現場ごとに、呼び名、種類などが大きく変わることがある。 | |
ざっと洗い出しただけでもけっこうな数があることが分かると思う。しかしこれらすべてのドキュメントを作成することは時間的に難しいことが多いため、実際にはこの中から最低限必要なドキュメントのみが作成されていることが多いが、作成対象のドキュメントを限定したとしても、まだ工数が足りないというのが現実ではないだろうか。このような現状の中で、開発側（つまりドキュメントを作成する側）は、いかにしてドキュメント作成の工数を減らすかについて試行錯誤を繰り返してきた。こういった現状が、アジャイル宣言にある「包括的なドキュメントよりも動くソフトウェア」の間違った解釈と相まって、「アジャイル開発を採用すれば、ドキュメントを作成しなくてもよいのだ」という間違った認識が生まれる原因にもつながっている。
本来われわれが考えるべきことは、ドキュメント作成にかかる工数をただ減らすことだけではなく、いかにして価値のあるドキュメントを効率的に作成するかだ。つまり、アジャイル（＝良いものを素早く無駄なく作ること）なドキュメント作成技法（＝アジャイル・ドキュメント）が必要なのである。
ちなみに、前述の「包括的なドキュメントよりも動くソフトウェア」とは、ドキュメントにも価値を認めるが、ソフトウェアの方にこそより価値があるという考え方であり、決して「ソフトウェアがあればドキュメントはいらない」といっているわけではない。
■アジャイル・ドキュメントとは何か？
アジャイル・ドキュメントは、『アジャイルモデリング』の著者であるスコット・アンブラー氏によって、以下のように定義されている（主要な項目のみ抜粋）。
- ドキュメントは必要十分でなければならない
- ドキュメントは、ソース・コードと同じでシステムの一部である
- チームの第2の作業は次の作業への備えである
- ドキュメントを持つことによる利点は、ドキュメントを作成および保守するためのコストを上回らなければならない
- ドキュメントを信用してはならない
- システムごとにドキュメントに対するニーズは異なる
- ドキュメントがなぜ必要かを尋ねるべきである
- ドキュメントに投資するかどうかは、技術上の判断ではない
- 必要なときだけドキュメントを作成するべきであり、ドキュメントのためのドキュメントを作成してはならない
- ドキュメントが十分かどうかを決めるのは、開発者ではなく、顧客である
つまりアジャイル・ドキュメントとは、ドキュメントを作成、保守、参照をするに当たっての心構えのようなものなのだが、ここで書かれていることは特に目新しいことではなく至極当たり前のことである。しかし実際にこれらの定義を実践しようとすると、なかなか思うとおりにはいかないのも事実である。そこでこれら各項目を踏まえ、「価値のあるドキュメントを作成するためのコツ」「ツールを使って効率的にドキュメント作成する方法」について順に解説していく。
 |
| INDEX | ||
| [特集] | ||
| ツールを使ったドキュメント作成技法（前編） | ||
| 価値のある開発ドキュメントを効率的に作成するには？ | ||
 |
1. アジャイル・ドキュメントとは何か？ | |
| 2. 価値のあるドキュメントを作成するコツ | ||
| 3. ツールを使ったドキュメントの作成技法 | ||
| ツールを使ったドキュメント作成技法（後編） | ||
| マイクロソフトも実施しているドキュメント作成技法 | ||
| 1. 柔軟なXMLドキュメント・コメントを生成する「GhostDoc」 | ||
| 2. GhostDocとSandCastleを組み合わせたドキュメント作成技法 | ||
| 3. マイクロソフトも活用する「patterns & practices Documentation Tools」 | ||
|
||
- 第2回 簡潔なコーディングのために （2017/7/26）
ラムダ式で記述できるメンバの増加、throw式、out変数、タプルなど、C# 7には以前よりもコードを簡潔に記述できるような機能が導入されている - 第1回 Visual Studio Codeデバッグの基礎知識 （2017/7/21）
Node.jsプログラムをデバッグしながら、Visual Studio Codeに統合されているデバッグ機能の基本の「キ」をマスターしよう - 第1回 明瞭なコーディングのために （2017/7/19）
C# 7で追加された新機能の中から、「数値リテラル構文の改善」と「ローカル関数」を紹介する。これらは分かりやすいコードを記述するのに使える - Presentation Translator （2017/7/18）
Presentation TranslatorはPowerPoint用のアドイン。プレゼンテーション時の字幕の付加や、多言語での質疑応答、スライドの翻訳を行える
 |
|
|
|
|
