理系のための文書作成術(1) ―― 開発文書を分かりやすく記述する

　ソフトウェアやハードウェアなどの開発作業には，仕様書や設計書などの文書（ドキュメント）を読んだり書いたりすることが欠かせません．通常，開発文書は，読み手が理解しやすいように，正確で明快であることが求められます．さらに，開発文書としての内容が必要十分であることも求められます．それは，読み手が，開発文書の内容を理解するだけでなく，理解した情報を次に続く開発作業につなげなければならないからです．読み手にとって分かりにくい開発文書は，読み手の理解を妨げ，さらには開発作業の進み具合や作業そのものの成否にも影響を及ぼします．

　本連載では，ソフトウェア開発を例にして，仕様書や設計書に散見される分かりにくい記述例を紹介しながら，次の論点を考察していきます．

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

　紹介する例としては，筆者の経験から，組み込みソフトウェア開発文書の記述を取り上げます．しかし，本連載で述べる文書作成や記述表現のヒントは，ソフトウェア開発に限定されるものではありません．ほかの開発文書や，技術的な内容の文書を作成する際にも，多くの点で当てはまります．さらに，しごとのやり方にも通じる点を見つけていただけるかもしれません．

技術解説・連載「理系のための文書作成術」 記事一覧
第1回　開発文書を分かりやすく記述する
第2回　図表を表現手段として活用する
第3回　開発文書の書き方はしごとのやり方を示す
第4回　自分の「赤ペン先生」を持とう
第5回　設計レビューでするべきこと，してはいけないこと
第6回　仕事で文書を「書かされている」あなたへのメッセージ

●お知らせ
　連載「理系のための文書作成術」が電子書籍になりました！
　ご購入は「Tech Village 書庫＆販売」のページから．

　今回は，開発を妨げる危険性を持つ記述の例を紹介します．

●分かりやすい記述とは

　開発の妨げとなりうる記述とは，どのようなものかを考えるために，分かりやすい記述とは何かを整理してみましょう．筆者が考える開発文書としての分かりやすさの要素を挙げてみます．

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

　これらの分かりやすさの要素に適合しなければ，分かりにくい記述と考えられます^注1．

注1：筆者は，これらの要素を，ソフトウェア開発文書の改善点を指摘するためのいくつかの種別に整理して，文書の改善活動につなげる活動も行っている^（1）．