業務内容によってはドキュメントを作成する機会がなかなかないと思うので、ドキュメント作成のコツについて一般的なことを書いてみます。
ドキュメント作成にコツも何もあるのか、って感じかもしれませんが、ドキュメントの良し悪しで意図が早く正確に伝わるかどうかが変わってくるので、スムーズに仕事をこなすには欠かせないスキルです。
ドキュメントの質が悪い場合、わかりにくいと言われて怒られるだけならまだ良い方で、最悪の場合は情報の受け手の誤解によりシステム障害に繋がることすらあります。
ドキュメントには設計書からユーザ向けのマニュアル、運用手順等、色々種類がありますが、今回はどのようなドキュメントについても通じることを書きます。
【根→葉の流れで構造的に書く】
小説のように文章をつらつらと書くのではなく、適度に見出しを付けることが重要です。
また、その見出しは、根→葉の流れで構造的に書くことが重要で、見出しだけを見れば何がどこに書いてあるのかがわかるようにすることが理想です。
プログラム改修の設計書で言うと、以下のように書くのが良いでしょう。
１．背景
……
２．リリース日
……
３．修正箇所
３．１．プログラムA
３．１．１．hoge対応
……
３．１．２．fuga対応
……
３．２．プログラムB
……
３．３．プログラムC
……
【箇条書きや表や図で完結に書く】
・箇条書きの使用
並列である複数の事柄を書く時は、箇条書きを用いると文章が見やすくなります。
例えば、
「条件Aの時か、条件Bの時か、条件Cの場合に、hoge処理をする」
という文章は、以下のように書くとわかりやすくなります。
以下の何れかの条件に当てはまる時に、hoge処理をする。
・条件A
・条件B
・条件C
・表の使用
2×2かそれ以上の項目・条件が絡み合う事象を書く場合は、
表を用いると状況をわかりやすく整理できます。
例えば、下記はリスクの対応策を表にまとめたものです。
これを表を使わずに表現すると、
「脅威に対しては回避と転嫁と軽減の戦略があり、回避とは…」
といういかにも冗長な文章になってしまいます。
・図の使用
複雑な事象を言葉で説明するのは難しいですが、
図解するとわかりやすく説明できることが多いです。
例えば、理解が難しい概念である
「モジュール強度」と「モジュール結合度」
を図解したものが以下です。
https://akira2kun.hatenablog.com/entry/2018/07/07/144209
日本語を読んでも何が言いたいのかわかりにくいと思いますが、
図解することで意図を理解しやすくなると思います。
【誤解のない表現を使う】
・客観的な数値を示す
「性能が大幅に良くなった」「キャパシティに与える影響は軽微である」
といった主観的な表現だと、
それぞれの受け手毎に異なる解釈をされる可能性があります。
ここは、異なる解釈をされないように、
「性能が10倍になった」「ディスク容量が100GBであるがデータ増加量は10MBである」
といった形で、客観的な数字で表すことが重要です。
・複数の意味で取られる日本語を避ける
すみません、すぐに良い例が思い浮かばないので引用しますが…
日本語の難しさ：文法編（読点一つで意味が変わる？！）：ウェブ・コト
https://www.webkoto555.jp/column/?id=1514429008-408625
「私は何度も咳をする彼を見ました」
という文章が
「咳をする彼」を何度も見た のか、
「何度も咳をする彼」を見た のか、よくわからん！
…ということが設計書や手順書を書く中でも起こり得ます。
出来上がった文章を読み返して、
複数の意味に取られないか考える癖を身に付けることが重要です。
複数の意味に取られかねない時は、上手く言い換える必要があります。
・要件、仕様等を明確にする
要件定義書なら誰がいつどのようにシステムを使うのか定義する必要がありますし、
画面設計書なら画面項目のフォーマットや桁数等を定義する必要があります。
ドキュメントによって絶対に定義しなければならないポイントがあるので、
そのポイントを落とさないようにすることが重要です。
もし定義が不十分だと、
情報の受け手に自分の意図とは異なる解釈をされてしまう恐れがあります。
【情報の受け手に合わせて表現を変える】
システムの利用者にとっては、
システムをどのように操作すれば良いのかがわかれば良いので、
詳しい仕様は冗長な情報になります。
逆に、システムの開発者にとっては詳しい仕様こそが重要になります。
このように、情報の受け手によって、どのような情報を求めているかが異なります。
ドキュメントを作成する際は、情報の受け手が誰であるかを想像して、
適切な粒度で情報を提供することが重要になります。
