理系のための文書作成術(4) ―― 自分の「赤ペン先生」を持とう

あの女性タレント，デビュー当時は冴えない顔だったけれど，いつのまにか美人になったよね...．それと同じことが文書作成にも言える．今回は，自分の作成した文書を他人に査読してもらう効能について説明する．（編集部）

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

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

読者の皆さんは，自分が書いた文章を，ほかの人に査読してもらう機会があるでしょうか？

　多くの女性は，人から見られていることを意識すると，より美しく見られたいと考えます．テレビなどでも，これまであまり表に出てこなかった女性が，なにかの賞をとったり人気が出てきたりして，より多くの人に注目されるようになると，みるみる美しくなっていく様子に気付くことがあります．

　文章も同じです．人目に触れる機会を作り，さらに不備を指摘してもらう機会を得ることで，上達していくはずです．

●文書を査読してもらう機会を作ろう

　開発文書を含む技術文書は，何らかの目的を必ず持っています．多くの場合，その目的は，技術的な作業を実施した成果を表現するものです．また，開発文書の場合は，開発のプロセスの中で，次の工程に引き渡すものとしての役割も担っています．

　目的を持つということは，特定される読み手が存在するということです．読み手は文書を理解し，何らかの判断を下したり，読んだ文書に基づいて作業を実施したりします．つまり，技術文書は目的を持ち，何らかの機能を果たさなければならないのです．そのためには，機能を果たせるだけの水準のものでなければなりません．少なくとも，第1回で述べたような「分かりやすい記述」であることは，最低限の水準でしょう．

［開発文書の分かりやすさの要素］

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

　この分かりやすさの要素を，ぜひ第三者に確認してもらうことをお勧めします．文書を査読してもらい，分かりやすいものに改善することは，文書が本来果たすべき機能の実現を円滑に進めることにつながるはずです．

●「目次」だけでも改善点はこれだけ見つかる

　第三者から見た文書の改善点について，筆者が実際に改善点を指摘した，ある開発文書を例に説明します．図1は，ある組み込みソフトウェア開発プロジェクトで作成された「水漏れ検出プログラム要求仕様書」の目次です．皆さんもこの目次を見て，気になる点を挙げてみてください．いくつ挙げられるでしょうか？

図1　「水漏れ検出プログラム要求仕様書」の目次

　筆者がこの目次から改善した方がよいと考えた点を，見出しの不明確さ，文書の構造，タイトルと内容の対応，という観点で整理して，以下に挙げます．