読み手が納得する開発ドキュメントを作るにはどうすればよいのか。本特集では日経SYSTEMSの過去記事を再編集。実用性の高い実践ノウハウを5日間で習得しよう。

 こんなドキュメントを見たことはないだろうか。

 「BPMとBAMによる業務リスクのマネジメント強化」といった、専門用語や抽象的な言葉が頻出する難解な要件定義書。システムの内部処理まで詳しく記述した画面仕様書。長々とした文章による説明が続く基本設計書──。

 こうしたドキュメントの読み手はたまったものではないだろう。しっかりと読み込むのは不可能。納得どころか理解もできず、勝手に推測して内容を補わざるを得ない。こうして生まれた誤解や勘違いは、やがてプロジェクトを危機に陥れる。

 プロジェクトマネジメント業務を多数手掛けるF氏はこう指摘する。「ドキュメントはトラブルを回避するための生命線。それなのに、目に余るようなドキュメントが増えている」。

読み手の多様化が背景に

 「ドキュメントの問題は昔から指摘されてきた。今さら取り立てて問題視する必要があるのか」。こう思う人がいるかもしれない。しかしドキュメントに求められる水準が高まり、「ドキュメントの問題は近年ますます顕在化している」(前出のF氏)と指摘する声は少なくない。今やITエンジニアのドキュメント作成力によって、プロジェクトの成功が大きく左右されるといっても過言ではない。その背景には、いくつかの要因がある。

プロジェクトにおいて、ドキュメントの役割が重要になっている主な背景
複雑化したシステムを専門特化したメンバーによる分業体制で構築するには、コミュニケーション手段としてドキュメントが生命線である。ドキュメントの品質を向上させることが、プロジェクト成功の大きなカギを握る
[画像のクリックで拡大表示]

 1つには、システム構築プロジェクトの関係者が広がり多様化したことが挙げられる。例えば、1つのシステムの利用者が複数の部門、関連会社、時には取引先にまたがることは今や珍しくない。そのときの要件定義書は、「視点や関心事の異なる多様な利用者が読んで納得するものにする必要がある」(大手SIerで金融向けのシステム構築を手掛けるK氏 )。

 ITエンジニアも、アプリケーション設計、データベース設計、基盤設計といった具合に専門分化した人がプロジェクトに参加する。このように読み手が多様化すれば、従来の画一的なフォーマットに沿ってドキュメントを書くだけでは通用しない。

 さらに、システムの業務への密着化が進んだり、システムが複雑化したりしたことで、そもそも説明の難しい内容をドキュメントに表さなければならないケースが増えた。このことも要因の1つに挙げられる。例えば、細かな使い勝手に配慮したユーザーインターフェースの操作や他システムとの入り組んだ連携機能を、ドキュメントで分かりやすく説明するのは容易ではない。

 また、人材の流動化やオフショア開発が進展したことにより、従来のような以心伝心を期待できなくなったことも大きい。「初めて協業するメンバーがいる場合、書かなくても分かるはずは通用しない。くどいくらいにドキュメントに記述しないと、読み手の勝手な解釈が入り、システムのバグに直結する」(大手SIerでプロジェクトの技術支援を担当するY氏)。