株式会社 ソフテック
制御用ソフトウェアの受託開発を手がけて５３年の経験と
受注案件７０７９件（2024年9月末時点）の実績
受注案件７０７９件（2024年9月末時点）の実績
「ソフテックだより」では、ソフトウェア開発に関する情報や開発現場における社員の取り組みなどを定期的にお知らせしています。
さまざまなテーマを取り上げていますので、他のソフテックだよりも、ぜひご覧下さい。
ソフテックだより（発行日順）のページへ
ソフテックだより 技術レポート（技術分野別）のページへ
ソフテックだより 現場の声（シーン別）のページへ
ソフトウェア開発にはドキュメント作成がつきものです。作成するドキュメントとしては、顧客要求仕様書、外部設計書、内部設計書、テスト項目書、作業手順書、取扱説明書・・・と様々あります。1つの開発の中でもたくさんのドキュメントが作成され、開発の規模が大きくなるとそれだけたくさんのドキュメントが作成されています。
私は文章を書くのが苦手なので、ドキュメントを作成する時にはいつも「ドキュメントを作成するのには時間も手間もかかるし、大変だなあ」と思ってしまいます。なので、本号では改めてそんなドキュメントの重要性について考えてみたいと思います。このソフテックだよりを読んでくださっている方の中にも、私のように文章を書くことが苦手な方もいらっしゃるのではないかと思います。（特に学生や新入社員の方など）そのような方にとって本号がなにかのご参考になれば、と思います。
そもそもなぜドキュメントを作成する必要があるのでしょうか？ドキュメントの利点や有効な点にはどんなものがあるでしょうか？私は以下の点があると考えます。
ひとつの開発の中では、たくさんの情報を取り扱うことになります。たくさんの情報は分類して整理しないと頭の中だけでは処理し切れません。また、情報を整理しているうちに頭の中も整理することができ、情報の過不足、矛盾等の発見をすることができます。
（1）で情報が整理されるので、その後の作業がスムーズにできます。事前に情報の過不足、矛盾等を発見・修正できているので後戻りも少なくなります。
作成したドキュメントを公開（ソフテック社内であればLotus Notes※で公開）すれば、複数人で作業する場合に同一の情報を共有できます。（1）（2）の利点も同時に共有されることになります。
お客様に提出するドキュメントの場合でも、広く考えれば「お客様と情報の共有をしている」ということになります。
開発時のみだけではなく開発後にも内容を振り返ることができます。例えば同じような開発を行う場合、内容や方法の流用ができたり、反省点・改善点を組み入れたりすることができます。
なるべく1つの開発に関わる担当者は変わらないのが理想ですが、種々の理由で担当者が変更になることがあります。そんな時でもドキュメントを作ってあると、それを基に他の担当者に開発の引継ぎを行うことができます。
これらの利点を生かすには、必要な情報が適切な形で記載されているドキュメント、つまり『質の良いドキュメント』が必要になってきます。
ところで、冒頭で告白したように私は文章を書くことが苦手です。これまでの人生で文章を書いたり説明をしたりする機会があまりなかったこと、また避けてきたことが原因だと思います。
そのような私がいつもドキュメント作成でよく注意を受ける悪い点をあげます。
私と同じように文章を書くことが苦手な方には、当てはまることがいくつかあるのではないでしょうか？
誤字脱字があると意味が通じないばかりか、読み手の読む気が失せます。
インデントやフォント、文字揃え等がバラバラでは、見た目が悪く、また読みづらくなってしまいます。
同じ意味の違う言葉を複数使用すると、「使い分けしている」と思われ、誤解を招きます。
一文が必要以上に長いと、読みづらく、意味を追えなくなってしまいます。
どれも基本的な事項ですがなかなか改善できず、ドキュメントを審査してくださる上司からはいつも「分かりづらいよ！」とお叱り＆ご指摘を受けています。特に私がよく作成するドキュメントはページ数が多く（多いものだと100ページ以上）、上記のような悪い点が延々と続いてしまうと、とても読みづらいです。
更に、（4）のような問題があるとドキュメントを読むのにとても時間がかかってしまいます。そのため上司から「じっくり読まなくても分かるように書かないと」とご指導いただいています。いつも同じ様なミスを繰り返してしまうため、最近は自分がやりがちなミスを表1〜3のようにチェックリストにまとめて、改善を行っています。
| 項目 | 詳細 | チェック |
|---|---|---|
| 表紙 | 文書番号 | |
| 日付 | ||
| Rev番号 | ||
| 文字 | 半角全角の統一（数字や括弧、「、」「。」等にも注意） | |
| 連続括弧をしないこと | ||
| 2進数や16進数を使用するときはそう分かること（0bや0xと書く） | ||
| 数値が連続していない場合は〜を使用しないこと。ex）1〜2→1、2 | ||
| データ等を文書内に図として入れる場合はMSゴシックにして文字をそろえること | ||
| フォントがあっているか？ | ||
| 本文が変な書式（標準インデントやヘッダ）に勝手になっていないか？ | ||
| 箇条書きの左揃えがあっているか？ | ||
| 表 | 表の幅は見やすいか？ | |
| 表のインデントはあっているか？ | ||
| 文字プロパティの左の絶対値がそろっているか？ | ||
| 線抜け・線不ぞろいはないか？ | ||
| 図や表が対応しているか？（クロスリファレンスも注意） | ||
| 数字は右そろえの方が見やすい | ||
| 小数点を使用する場合は桁をそろえること | ||
| 印刷 | 印刷レイアウト（エクセル表の場合はページの変わり目に注意・縦／横にした方が見やすい・印刷ページサイズ文字が小さすぎないか、見切れていないか） | |
| ヘッダ（文書名・文書番号名）・フッダ（ページ番号）の設定 | ||
| 見出しマップ | 項目番号、項目名が全てあるか？ |
表1. 私が使っている文書チェックリスト（フォーマット編）
| 項目 | 詳細 | チェック |
|---|---|---|
| − | 正式名称を使うこと | |
| 文言や省略名があっているか？ | ||
| 仕様書や回路図・CPU等で型番と違っている場合は理由を明記すること | ||
| 使用規格のバージョン番号を書くこと（文書作成後に規格が変わってしまってもわかるように） | ||
| お客様との相談の上処置したことは明記すること | ||
| 項目番号を参照する場合は、「1何とか項目」なら「1 何とか項目」のようにスペースを空けること | ||
| 項目番号に順位があるときに違う種類の文字を使うこと（1の小項目に a など） | ||
| 文言の統一・文書内で同じような形式の文章がある場合はそれに合わせること | ||
| 担当を明示すること | ||
| 文書参照の場合は使用文書を明示すること |
表2. 私が使っている文書チェックリスト（その他）
| 項目 | 詳細 | チェック |
|---|---|---|
| − | テスト項目で実施しない項目があっても削除せず、理由を書いて未実施等書くこと | |
| テスト結果に実施日を書くこと | ||
| テスト結果が読み手にとってわかりやすいか？（一目で「OK／NG」がわかるように） |
表3. 私が使っている文書チェックリスト（テスト編）
上述したような問題を抱えた「質の低い」ドキュメントでは、ドキュメントの利点を十分に生かすことができません。
それではどのような点に注意すれば「質の良いドキュメント」となるのでしょうか？私なりに考えてみました。
質の良いドキュメントを作成するためには、以下の点に注意することが必要と考えます。
読み手がどのような立場なのか、どのような視点でドキュメントを読むのかを意識することが大切だと思います。ドキュメントの読み手は、社内の担当者、お客様、一般の方（ホームページをご覧になる不特定多数の方等）等様々います。
また、「お客様」と一口に言っても、プログラムについて詳しい方もいれば、プログラムには詳しくないけれどそれ以外の専門技術には詳しい方もいます。作成したドキュメントが取扱説明書であればそれを読みながら操作をする方（オペレータ）もいますし、見積書であればそれを読んでソフテックにご発注してくださるか検討する方もいます。
読み手によって知りたい情報は異なりますので、読み手が異なればドキュメントの書き方を変える必要があります。（どのような形式にするべきか、どの部分にどの程度の説明が必要か等）また、読み手が重要視する部分がわかっていると、読み手にとってより有益な情報を盛り込むこともできます。
複数ドキュメントがあると「どれを見れば何が分かるのかが分からない！」ということになってしまうことがあります。そんな時には各ドキュメントの位置づけが分かる表や図があると便利です。
ドキュメントは開発時にだけ使用するとは限りません。
何年もたってからシステムの改修が必要になったりすることもあります。そんな時には当時のドキュメントを見ても「あれ？ここはどうだったっけ？確か何か理由があってこうしたような気はするけど・・・」となることもあるかもしれません。更に担当者が変更になるとドキュメントに載っていない書き手の意図は失われてしまいます。そうならないように、ドキュメントには結果だけではなく、方針や意図、理由、特記事項等を記載し、読み手が書き手の意図をスムーズに汲み取れるように意識した記述にすることが大切です。
ドキュメント内であいまいな表現を使うと誤解を招き、書き手と読み手で認識が異なってしまうことがあります。そのようなことのないよう、「受け取り方の異なる表現を使わない」、「同じ意味の違う言葉を使わない」等の配慮が必要です。
いくら正しいことを書いていても、結論に至るまでが長いと読み手も疲れてしまいます。また、前半に書いていたことを忘れてしまうかもしれません。複雑なことを書く場合は、図や表を用いて視覚的に分かりやすくすると親切です。
以上、質の良いドキュメントを作成するための注意点を挙げてみましたが、その他にも様々あると思います。ですが、共通して言えることは、「いかに読み手に気を使えるか」だと思います。更に「読み手に気を使える」ということは、まず「読み手が気になる部分に気がつく」ということが大切になります。「気を使う」、「気がつく」ということはなかなか無意識では改善されない部分ですので、日常的に意識して改善していく必要があります。
また、文章は書かないとうまくなりません。ソフテックでは、Lotus Notesを使用した文書での報告が義務となっています。私はこれを文章の練習として積極的に利用し、より良いドキュメントを作成できるよう取り組んでいます。
本号が文章を書くことが苦手な方のご参考、励ましになれば幸いです。
（Y．D．）
関連ページへのリンク
関連するソフテックだより