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

 「ドキュメントの目的は、その都度考える必要がある。それによって、そのケースにおけるドキュメントの要件が明確になり、標準フォーマットのままで事足りるか、どうアレンジすべきかが見えてくるからだ」(製造業向けITコンサルティング会社のM氏)。目的の明確化がドキュメント作成の出発点になる、というわけである。

 では、ドキュメントの目的をどう考えればよいのか。ドキュメントはコミュニケーションの道具であり、読み手がいて、その人に何かしてほしいという動機が必ずあるはず。例えば詳細設計書を作成する場合なら、読み手であるプログラマーに、プログラミングに必要な情報を正確に理解してもらって手戻りをなくしたい、という動機があるだろう。これが、ドキュメントの目的の簡単な例である。

どういう視点で読むのか?

 このようなドキュメントの目的を、もっと突き詰めて考える必要がある。その場合、2つの要素に切り分けるとよい。それは「読み手はどういう人か」と「読み手は(ドキュメントを)何にどう使うのか」である。これにより、ドキュメントは格段にわかりやすくなる。

ドキュメントの目的の考え方
目的の構成要素ごとの観点で考えたうえで、作成方針や項目の構成を決める。場合によっては、読み手ごとに、別のドキュメントを作ることも検討する
[画像のクリックで拡大表示]

 まず、ドキュメントの読み手となる人をリストアップする。そのうえで、「記述する内容に関してどれだけの前提知識を持っているか」「どういう視点でドキュメントを読むのか」「主体的にドキュメントをすみずみまで読んでくれそうか」といった観点で、読み手を具体的にイメージする。

 例えば「前提知識の乏しい人であれば、ドキュメントに詳しく説明を書き込んだり、専門用語を極力使わないといった配慮をしたりすることが必要になる」(中堅ITコンサルティング会社のI氏)。利用部門のキーパーソンやプロジェクトマネジャーなど、時間がなくて大ざっぱにしか読んでくれそうにない人ならば、ポイントを押さえた内容にする必要がある、といった具合だ。

 こうして読み手のイメージを明確化したうえで、「ドキュメントを何にどう使うのか」という利用場面を想像する。例えば「何のためにドキュメントを読むのか」「そのとき、どんな情報が必要か」「どのように書いていると分かりやすいか、内容に納得できるか」──といったことをイメージしていく。

 このとき重要なのは、「自分がドキュメントの読み手だったらどう考えるかという想像を巡らせて、ドキュメントの要件を明確化する」(大手コンサルティング会社のT氏)ことだ。こうして明確になった要件を基に、標準フォーマットや先例をたたき台にして、追加すべき項目や簡略化して構わない項目がないかどうかを考える。

三者三様の使い方をする

 要件定義書の例を挙げよう。要件定義書には、どのような読み手がいるだろうか。例えば重要な読み手として、要件定義の会議に参加した利用部門のキーパーソン、会議には参画せずヒアリングを受けただけの利用部門の主要メンバー、基本設計の担当者──といった人が挙げられる。この三者のドキュメントの読み方は大きく異なる。

 まず要件定義の会議に参加した利用部門のキーパーソンは、会議で決まった結果がきちんと反映されているかどうかを確認するだろう。この読み手の視点に立てば、結論と経緯を簡潔にまとめているのが望ましい。

 ただし同じ利用部門でも、要件定義の会議に参加せずヒアリングを受けただけの主要メンバーは異なる読み方をする。結論に至った経緯を詳しく知らないからだ。「どうしてこうなったのか」と疑問に思いやすいポイントについては、詳しい経緯の説明を必要とする。

 一方で、基本設計の担当者は、システムを設計するために要件定義書を読む。そのため、システムの機能や性能について、漏れのない詳しい情報が必要である。要件定義書を基にテストケースを洗い出すことを想定すると、利用する機能を業務ごとにまとめた一覧表があると便利だ。

 簡単なことではないが、実際に目的を突き詰めて考えたうえで、社内標準や先例のフォーマットをアレンジすれば、大きな成果を上げられる。以降で、3つの事例を紹介しよう。

この先は日経クロステック Active会員の登録が必要です

日経クロステック Activeは、IT/製造/建設各分野にかかわる企業向け製品・サービスについて、選択や導入を支援する情報サイトです。製品・サービス情報、導入事例などのコンテンツを多数掲載しています。初めてご覧になる際には、会員登録(無料)をお願いいたします。