誤解を生まないドキュメンテーション

ソフトウェアやハードウェアなどの開発作業には、仕様書や設計書などの文書（ドキュメント）を読んだり書いたりすることが欠かせません。ビジネスの多くのシーンでも、文書は必ず出てきますし、そのほとんどがお堅い記述となっています。

通常、開発文書は、読み手が理解しやすいように、正確で明快であることが求められます。さらに、開発文書としての内容が必要十分であることも求められます。それは、読み手が、開発文書の内容を理解するだけでなく、理解した情報を次に続く開発作業につなげなければならないからです。

読み手にとって分かりにくい開発文書は、読み手の理解を妨げ、さらには開発作業の進み具合や作業そのものの成否にも影響を及ぼします。この点は文書（ドキュメント）が開発のための中間成果物であると同時に"工程間のコミュニケーションツール"である、という自覚がなければ理解することは難しいでしょう。

観点として重要なのは、

　・どんな文書が開発を妨げるのか
　・分かりやすい開発文書を書くにはどうしたらよいのか
　・どのように開発業務に組み入れていけば、品質と生産性が上がるのか

と言う点です。もちろん、こうした観点はソフトウェア開発に限った話のことではなく、仕事（ビジネス）においてはすべて当てはまるのではないでしょうか。

ただ、一般的な会話コミュニケーションとは違い、一人ひとりの読み手にあわせてドキュメントの構成や品質を変えていたのでは、大変なことになってしまいますので、一般的にはドキュメントの「テンプレート（ひな形）」や「記述ルール」を設けて、書き手、読み手にそれぞれ半歩ずつの負担を分担させ、意識を合わさせやすくしている現場が多いと思います。

分かりやすい記述とは

開発の妨げとなりうる記述とはどのようなものかを考えるために、分かりやすい記述とは何かを整理してみましょう。開発文書としての分かりやすさの要素を挙げてみると、こんなところでしょうか。

　正確性（正確であること）
　　　文法が正しい、表記ルールに則っている、表現に間違いがない、
　　　伝える事柄に間違いがない、一意に理解できる、など
　可読性（読みやすいこと）
　　　明快である、簡潔である、など
　合目的性（目的に合っていること）
　　　文書の目的が明確である、
　　　目的に対して必要十分な事柄が記述されている、など

これらの分かりやすさの要素に適合しなければ、分かりにくい記述と考えられます。