ドキュメント作成の基礎

伊東 輝

ドキュメントの良し悪しで、他者に意図が早く正確に伝わるかどうかが変わる。
良いドキュメントを作成するスキルは、スムーズに仕事をこなすには欠かせないスキルである。

この記事では、ドキュメント作成について、一般的な手法を紹介する。
ドキュメントには、設計書からユーザ向けのマニュアル、運用手順等、色々種類がありますが、今回の記事では、どのようなドキュメントにも共通する手法を紹介する。


(1)文章の構造化

意図の伝達を目的とするドキュメントにおいては、小説のように文章をつらつらと書くのではなく、適度に見出しを付けることが重要となる。
また、その見出しは、根→葉の流れで構造的に書くことが重要であり、見出しを見れば何がどこに書いてあるのかがわかる状態にすることが理想である。

プログラム改修の設計書を例に挙げると、以下のように書くのが良いだろう。

  1. 背景
    ……

  2. リリース日
    ……

  3. 修正箇所
    3.1.プログラムA
    　3.1.1.hoge対応
    　　……
    　3.1.2.fuga対応
    　　……
    3.2.プログラムB
    　……
    3.3.プログラムC
    　……

(2)簡潔な記述

意図を早く正確に伝える上では、簡潔な記述を心掛けることが有効である。
ここでは、箇条書きでの記載、表の使用、図の使用の３つの手法を紹介する。

【箇条書きでの記載】

並列である複数の事柄を書く時は、箇条書きを用いると文章が見やすくなる。
例えば、
「条件Aの時か、条件Bの時か、条件Cの場合に、hoge処理をする」
という文章は、以下のように書くとわかりやすくなる。

以下の何れかの条件に当てはまる時に、hoge処理をする。

  • 条件A

  • 条件B

  • 条件C

【表の使用】

2×2かそれ以上の項目・条件が絡み合う事象を書く場合は、表を用いると状況をわかりやすく整理することができる。

例えば、下記はリスクの対応策を表にまとめたものである。

図1-1：表の使用の例（リスクの対応策）

これを表を使わずに表現すると
「脅威に対しては回避と転嫁と軽減の戦略があり、回避とは…」
という冗長な文章になってしまう。

【図の使用】

複雑な事象を言葉で説明するのは難しいが、図解するとわかりやすく説明できることがある。

例えば、保守性や移植性の高さを示す設計上の概念である「モジュール強度」と「モジュール結合度」は、文章だけ読んでもイメージすることが難しい概念である。
しかし、これを以下のように図解することで、どのように設計すれば保守性や移植性を確保しやすくなるのか、容易にイメージできるようになる。

図1-2：図の使用の例（モジュール強度・モジュール結合度）

(3)誤解のない文章表現

意図を正確に伝えるためには、誤解を生まない文章表現を心掛けることが望ましい。
以下では、気を付けるべきポイントをいくつか紹介する。

【客観的な数値を示す】

「性能が大幅に良くなった」「キャパシティに与える影響は軽微である」
といった主観的な表現では、それぞれの受け手毎に異なる解釈をされる可能性がある。

ここは、異なる解釈をされないように
「平均応答時間が3秒から1秒に短縮された」「ディスク容量は100GBであるがデータ増加量は10MBである」
といった形で、客観的な数字で表すことが重要である。

【複数の意味で取られる日本語を避ける】

例えば、「私は何度もコンソールがエラーを出力する所を見ました」という文章の場合、「何度も」の係り受けが曖昧であるため、以下の２つの意味で取られる可能性がある。

  • 私は「コンソールがエラーを出力する所」を何度も見た

  • 私は「何度もコンソールがエラーを出力する所」を見た

このようなことが設計書や手順書を書く中でも起こり得る。

出来上がった文章を読み返して、複数の意味に取られないか考える癖を身に付けることが重要である。
複数の意味に取られかねない時は、上手く書き換える必要がある。

特に、文章を短く区切る書き換えは、文章が分かりやすくなる可能性が高くお勧めである。
例えば、上記の例の場合
「コンソールは何度もエラーを出力しました。私はそれを見ました。」
と書き変えると、意味が明確にになる。

【要件、仕様等を明確にする】

要件定義書であれば誰がいつどのようにシステムを使うのか定義する必要があり、画面設計書であれば画面項目のフォーマットや桁数等を定義する必要がある。
もし定義が不十分だと、情報の受け手に自分の意図とは異なる解釈をされてしまう恐れがある。

ドキュメントによって絶対に定義しなければならないポイントがあるため、そのポイントを落とさないようにすることが重要である。
作成するべきドキュメントの種類を定義し、それらドキュメントのひな型を作成・展開することが、定義漏れを防ぐ上では有効だろう。

(4)受け手に合わせた粒度

意図を早く正確に伝える上では、情報の受け手に合わせた粒度で情報伝達を心掛けることも重要である。

システムの利用者にとっては、システムをどのように操作すれば良いのかがわかれば良いため、詳しい仕様は冗長な情報となる。
もし、冗長な情報が含まれていた場合は、情報の理解や取捨選択に時間を取られることになり、スムーズな情報伝達が阻害される。
逆に、システムの開発者にとっては詳しい仕様こそが重要であるため、その重要な情報が欠落していた場合は、意図を十分に伝えられないことになってしまう。

このように、情報の受け手によって、どのような粒度で情報を求めているかが異なる。
ドキュメントを作成する際は、情報の受け手が誰であるかを想像して、適切な粒度で情報を提供することが重要になる。

この記事が気に入ったらサポートをしてみませんか？