ドキュメント作成のコツについて一般的なことを書きます。
ドキュメントの良し悪しで意図が早く正確に伝わるかどうかが変わってくるので、スムーズに仕事をこなすには欠かせないスキルです。
ドキュメントには設計書からユーザ向けのマニュアル、運用手順等、色々種類がありますが、今回はどのようなドキュメントについても通じることを書きます。
【根→葉の流れで構造的に書く】
小説のように文章をつらつらと書くのではなく、適度に見出しを付けることが重要です。
また、その見出しは、根→葉の流れで構造的に書くことが重要で、見出しだけを見れば何がどこに書いてあるのかがわかるようにすることが理想です。
プログラム改修の設計書で言うと、以下のように書くのが良いでしょう。
１．背景
……
２．リリース日
……
３．修正箇所
３．１．プログラムA
３．１．１．hoge対応
……
３．１．２．fuga対応
……
３．２．プログラムB
……
３．３．プログラムC
……
【箇条書きや表や図で完結に書く】
・箇条書きの使用
並列である複数の事柄を書く時は、箇条書きを用いると文章が見やすくなります。
例えば、
「条件Aの時か、条件Bの時か、条件Cの場合に、hoge処理をする」
という文章は、以下のように書くとわかりやすくなります。
以下の何れかの条件に当てはまる時に、hoge処理をする。
・条件A
・条件B
・条件C
・表の使用
2×2かそれ以上の項目・条件が絡み合う事象を書く場合は、表を用いると状況をわかりやすく整理できます。
例えば、下記はリスクの対応策を表にまとめたものです。
これを表を使わずに表現すると、
「脅威に対しては回避と転嫁と軽減の戦略があり、回避とは…」
といういかにも冗長な文章になってしまいます。
・図の使用
複雑な事象を言葉で説明するのは難しいですが、図解するとわかりやすく説明できることが多いです。
例えば、理解が難しい概念である「モジュール強度」と「モジュール結合度」を図解した記事がこちらです。
「モジュール強度とモジュール結合度」の図解
日本語を読んでも何が言いたいのかわかりにくいと思いますが、図解することで意図を理解しやすくなると思います。
【誤解のない表現を使う】
・客観的な数値を示す
「性能が大幅に良くなった」「キャパシティに与える影響は軽微である」
といった主観的な表現だと、それぞれの受け手毎に異なる解釈をされる可能性があります。
ここは、異なる解釈をされないように、
「性能が10倍になった」「ディスク容量が100GBであるがデータ増加量は10MBである」
といった形で、客観的な数字で表すことが重要です。
・複数の意味で取られる日本語を避ける
例えば、「私は何度もコンソールがエラーを出力する所を見ました」という文章の場合、「何度も」の係り受けが曖昧であるため、以下の２つの意味で取られる可能性があります。
・私は「コンソールがエラーを出力する所」を何度も見た
・私は「何度もコンソールがエラーを出力する所」を見た
このようなことが設計書や手順書を書く中でも起こり得ます。
出来上がった文章を読み返して、複数の意味に取られないか考える癖を身に付けることが重要です。複数の意味に取られかねない時は、上手く書き換える必要があります。
特に、文章を短く区切る書き換えは、文章が分かりやすくなる可能性が高くお勧めです。
例えば、上記の例の場合、「コンソールは何度もエラーを出力しました。私はそれを見ました。」と書き変えると、意味が明確になります。
・要件、仕様等を明確にする
要件定義書なら誰がいつどのようにシステムを使うのか定義する必要がありますし、画面設計書なら画面項目のフォーマットや桁数等を定義する必要があります。
ドキュメントによって絶対に定義しなければならないポイントがあるので、そのポイントを落とさないようにすることが重要です。
もし定義が不十分だと、情報の受け手に自分の意図とは異なる解釈をされてしまう恐れがあります。
【情報の受け手に合わせて粒度を変える】
システムの利用者にとっては、システムをどのように操作すれば良いのかがわかれば良いので、詳しい仕様は冗長な情報になります。
逆に、システムの開発者にとっては詳しい仕様こそが重要になります。
このように、情報の受け手によって、どのような粒度で情報を求めているかが異なります。
受け手にとって粒度が細かすぎる場合は知りたい情報を誤解なく手早く知ることが困難になりますし、粗すぎる場合は知りたい情報を十分に知ることができなくなります。
ドキュメントを作成する際は、情報の受け手が誰であるかを想像して、適切な粒度で情報を提供することが重要になります。
いかがでしたでしょうか。
今回は、私がドキュメントを書く時に意識していることを列挙してみました。
ドキュメントはチームで仕事を進めていく上では欠かせないものですし、未来の自分が内容を思い出すためにドキュメントを読むこともあるので、今までドキュメントを重視してこなかった方は是非意識して書いてみてください。
なお、Slackのようなチャットツールでの会話でも、この記事で挙げたドキュメント作成のスキルを活かすことができます。
特に昨今はテレワークが普及しており、チャットツールでの会話も増えているかと思いますので、チャットでの意思疎通がスムーズにできるだけでも仕事ができる人だとみなされやすくなると思います。