ソフトウェア開発にはドキュメント作成がつきものです。作成するドキュメントとしては、顧客要求仕様書、外部設計書、内部設計書、テスト項目書、作業手順書、取扱説明書・・・と様々あります。1つの開発の中でもたくさんのドキュメントが作成され、開発の規模が大きくなるとそれだけたくさんのドキュメントが作成されています。

私は文章を書くのが苦手なので、ドキュメントを作成する時にはいつも「ドキュメントを作成するのには時間も手間もかかるし、大変だなあ」と思ってしまいます。なので、本号では改めてそんなドキュメントの重要性について考えてみたいと思います。このソフテックだよりを読んでくださっている方の中にも、私のように文章を書くことが苦手な方もいらっしゃるのではないかと思います。（特に学生や新入社員の方など）そのような方にとって本号がなにかのご参考になれば、と思います。

そもそもなぜドキュメントを作成する必要があるのでしょうか？ドキュメントの利点や有効な点にはどんなものがあるでしょうか？私は以下の点があると考えます。

（1） 情報の整理ができる
（2） スムーズに作業ができる （3） 情報を共有できる （4） 振り返ることができる （5） 担当者の変更が可能 これらの利点を生かすには、必要な情報が適切な形で記載されているドキュメント、つまり『質の良いドキュメント』が必要になってきます。

ところで、冒頭で告白したように私は文章を書くことが苦手です。これまでの人生で文章を書いたり説明をしたりする機会があまりなかったこと、また避けてきたことが原因だと思います。
そのような私がいつもドキュメント作成でよく注意を受ける悪い点をあげます。
私と同じように文章を書くことが苦手な方には、当てはまることがいくつかあるのではないでしょうか？

（1） 誤字脱字 （2） フォーマットがそろっていない （3） 文言の統一がされていない （4） 文言の統一がされていない どれも基本的な事項ですがなかなか改善できず、ドキュメントを審査してくださる上司からはいつも「分かりづらいよ！」とお叱り＆ご指摘を受けています。特に私がよく作成するドキュメントはページ数が多く（多いものだと100ページ以上）、上記のような悪い点が延々と続いてしまうと、とても読みづらいです。

更に、（4）のような問題があるとドキュメントを読むのにとても時間がかかってしまいます。そのため上司から「じっくり読まなくても分かるように書かないと」とご指導いただいています。いつも同じ様なミスを繰り返してしまうため、最近は自分がやりがちなミスを表１〜３のようにチェックリストにまとめて、改善を行っています。

項目 詳細 チェック 表紙 文書番号 　 日付 　 Ｒｅｖ番号 　 文字 半角全角の統一（数字や括弧、「、」「。」等にも注意） 　 連続括弧をしないこと 　 ２進数や１６進数を使用するときはそう分かること（０ｂや０ｘと書く） 　 数値が連続していない場合は〜を使用しないこと。ｅｘ）１〜２→１、２ 　 データ等を文書内に図として入れる場合はＭＳゴシックにして文字をそろえること 　 フォントがあっているか？ 　 本文が変な書式（標準インデントやヘッダ）に勝手になっていないか？ 　 箇条書きの左揃えがあっているか？ 　 表 表の幅は見やすいか？ 　 表のインデントはあっているか？ 　 文字プロパティの左の絶対値がそろっているか？ 　 線抜け・線不ぞろいはないか？ 　 図や表が対応しているか？（クロスリファレンスも注意） 　 数字は右そろえの方が見やすい 　 小数点を使用する場合は桁をそろえること 　 印刷 印刷レイアウト（エクセル表の場合はページの変わり目に注意・縦／横にした方が見やすい・印刷ページサイズ文字が小さすぎないか、見切れていないか） 　 ヘッダ（文書名・文書番号名）・フッダ（ページ番号）の設定 　 見出しマップ 項目番号、項目名が全てあるか？

表1. 私が使っている文書チェックリスト（フォーマット編）

項目 詳細 チェック − 正式名称を使うこと 　 文言や省略名があっているか？ 　 仕様書や回路図・ＣＰＵ等で型番と違っている場合は理由を明記すること 　 使用規格のバージョン番号を書くこと（文書作成後に規格が変わってしまってもわかるように） 　 お客様との相談の上処置したことは明記すること 　 項目番号を参照する場合は、「１何とか項目」なら「１　何とか項目」のようにスペースを空けること 　 項目番号に順位があるときに違う種類の文字を使うこと（１の小項目に ａ など） 　 文言の統一・文書内で同じような形式の文章がある場合はそれに合わせること 　 担当を明示すること 　 文書参照の場合は使用文書を明示すること

表2. 私が使っている文書チェックリスト（その他）

項目 詳細 チェック − テスト項目で実施しない項目があっても削除せず、理由を書いて未実施等書くこと 　 テスト結果に実施日を書くこと 　 テスト結果が読み手にとってわかりやすいか？（一目で「ＯＫ／ＮＧ」がわかるように）

表3. 私が使っている文書チェックリスト（テスト編）

上述したような問題を抱えた「質の低い」ドキュメントでは、ドキュメントの利点を十分に生かすことができません。
それではどのような点に注意すれば「質の良いドキュメント」となるのでしょうか？私なりに考えてみました。

質の良いドキュメントを作成するためには、以下の点に注意することが必要と考えます。

（1） 読み手を意識すること （2） ドキュメントの位置づけが分かること （3） 何年後かに見ても分かること （4） あいまいな表現は使わないこと （5） 簡潔であること 以上、質の良いドキュメントを作成するための注意点を挙げてみましたが、その他にも様々あると思います。ですが、共通して言えることは、「いかに読み手に気を使えるか」だと思います。更に「読み手に気を使える」ということは、まず「読み手が気になる部分に気がつく」ということが大切になります。「気を使う」、「気がつく」ということはなかなか無意識では改善されない部分ですので、日常的に意識して改善していく必要があります。
また、文章は書かないとうまくなりません。ソフテックでは、Lotus Notesを使用した文書での報告が義務となっています。私はこれを文章の練習として積極的に利用し、より良いドキュメントを作成できるよう取り組んでいます。

本号が文章を書くことが苦手な方のご参考、励ましになれば幸いです。