こんにちは、開発部の山下と申します。
今年5月に入社し、初めてのブログ執筆になります。よろしくお願いします。
龍野情報システムでは、プロジェクトマネージャ（PM）を担当しておりまして、日々の業務では主にドキュメントの作成を行っています。
そこで今回の記事では、お客様や開発者に読んでいただいてわかりやすいドキュメントの書き方についてご紹介したいと思います。
目次はこちら
- １．要件定義書、仕様書について
- ２．わかりやすいドキュメントとは
- ３．ドキュメントをシンプルにする方法
- ４．図表を用いたドキュメントの構成
要件定義書、仕様書について
一般的に、要件定義書とはベンダーが顧客から出されたRFP（提案依頼書）を元に作成する「こういうシステムを作りますよ」というドキュメントのことです。
一方、仕様書はベンダー内部でコーディングの前段階のドキュメントとして作成されます（正確には詳細設計書といいます）。
弊社ではウォーターフォール型の開発はしていません。
また、社内から要望が挙がってくることも多々あります。
そういった理由もあってか、「要件定義書≒仕様書」という扱いになっていおり、PMが作成したドキュメントを元にプログラマがコーディングをしています。
したがって、弊社のPMが作成するドキュメントはかなりシステム寄りのものになっていると思います。
わかりやすいドキュメントとは
前置きはそれぐらいにしておきまして、本題に入りたいと思います。
わかりやすいドキュメントとは、「シンプル」。これに尽きます。
人間は、限られた時間で雑多な情報を処理します。その雑多な情報を極力取り払い、単純明快にすることにより、読みやすいドキュメントが完成します。
もちろん、文章として正しいことも重要です。主語が抜けていたり、「てにをは」が無茶苦茶だったり、表記ゆれがあったりするととても読みにくくなります。しかしそこはそれほど重要ではありません。話はそれますが、実は私、文章力を鍛えるために、かつて「編集ライター養成講座」というものに通っていました。しかしそこでは文章を添削してもらえることがなく、主に取材の方法と具体的な数字を入れ込むことについて教わっただけでした。横道にそれたついでに宣伝をしますが、learningBOXにはレポート機能があり、生徒が書いた文章を提出し、先生が添削してフィードバックするといった使い方ができます。本当にただの宣伝になってしまいました。ノルマを達成（？）したのでまた本題に戻ります。
ドキュメントをシンプルにする方法
これは簡単です。文章ではなく、図表を前面に押し出すことで、ドキュメントは格段にシンプルになります。
また体験談で恐縮ですが、以前勤めていた会社での話です。お客様先でドキュメントの説明をすることになっていました。意気揚々と説明を始めたのですが、お客様がドキュメントを読んでいる気配がありません。よく観察してみると、お客様は文章を読んでいるのではなく、話を聞きながらずっとフローチャートを見ているということに気が付きました。なるほど、自分に置き換えても、文章よりも視覚的な図表のほうがスムーズに頭に入ってきます。それ以来、私が作るドキュメントには序盤に必ず図表が来るようになりました。
図表を用いたドキュメントの構成
最後に、その序盤に図表が来るドキュメントが、具体的にどのような構成になっているのか、説明します。
弊社には5月まで私を含めてPMが2名いて、その後増員をしています。そのためドキュメントはこれから標準化され、テンプレートができることになります。それまでは私個人の流儀で作成することになります。以下の構成は私個人のものです。
１．システム概要（数行のシンプルな文章）
２．システムの全体図（フローチャートまたは画面遷移図とER図が合体したようなもの）
３．テーブル定義書
４．画面ごとの詳細
大体こんな感じです。視覚的な全体像から徐々に詳細な説明に入っていくようにしています。そうすることで、読む側の理解も高まると思います。しかし、あくまで私個人の場合です。今後どのように標準化されていくのかは決まっていません。もちろん、これが正解だとは思いません。今後も試行錯誤しながら、お客様、開発者さんともにスムーズにシステムを理解していただけるよう、ドキュメントづくりに取り組んでいきたいと思っています。
Japanese 
English