理系のための文書作成術(6) ―― 仕事で文書を「書かされている」あなたへのメッセージ

●ドキュメンテーションで見えてくるプロセス，品質，自分の仕事

　開発作業とドキュメンテーションを連動させることによって，ドキュメンテーションの過程で見えてくるものがいくつかあります．

◆プロセスが見える

　作業内容とドキュメントの内容を一致させられるようになると，作業プロセスの中で「行うべきこと」，「行ったこと」，「進み具合」を，それぞれ明確にできます．「行うべきこと」は目次や各章節の見出しとして表現します．見出しを通して，作業事項や具体的な計画を明確にします（第3回を参照）．

　「行ったこと」は，まさに本文の内容です．あなたが，技術力を発揮して開発した成果を書き込みます．技術者であるあなたが，生み出す付加価値そのものとなります．そして，その本文がどこまで書けているか，すなわち，「行うべきこと」に対して「行ったこと」を書くことで，「進み具合」が明らかになります．進捗確認のミーティングなどで，「だいたい50％程度進んでいます」などと，その言葉を信じる以外すべのないような進捗報告と決別できます．文書を目で見ることで，客観的に作業の進み具合を確認できるようになります．

　これは，言うまでもなく，チーム管理に限ったことではありません．知的な作業を行うあなたに，自己フィードバックの機会を与えることになります．あなたは，書くことで自分の作業を可視化し，客観視できます．ひょっとすると，それほど重要ではないことに時間をかけすぎていることも見えてくるかもしれません．あなたは，仕事の進め方を改善するチャンスを得るのです．

◆品質が見える

　「行ったこと」をきちんと見える形で示せれば，その内容が正しいかどうかを検証して，妥当かどうかを判断することが容易になります．仕事のレビューをする（きちんとなされているかを調べる）際に，調べる対象を明確にすることが重要です（第5回を参照）．レビュー対象を明確にするためにも，作業の「行ったこと」を書いて文書で示すことは有効です．

　このようにして，ドキュメンテーションによって各工程の作業成果が明確になります．ソフトウェア開発の場では，品質問題の多くは工程間の情報伝達の不備にあると言われています．各工程の成果は，文書化して次の工程に渡します．ですから，その文書の品質を高めることは， 次工程への不具合の流出を減らすことになり，最終的な製品の品質を上げることにつながります．

◆自分の仕事が見える

　ドキュメンテーションで可視化される「プロセス」や「品質」は，もちろん自分にとっても，自身の仕事の「プロセス」や「品質」を明示することになります．自分の仕事をマネージするためには，自分を客観的に観察することが必要です．自分の仕事の「行うべきこと」，「行ったこと」，「進み具合」をはっきりと把握して，自分の仕事のプロセスと品質をしっかりとマネージしていきましょう．

　ここで注意していただきたいのは，これらの項目は文書を作成することによって「自ずと見えてくる」ということです．決して「見せるために文書を作成する」のではありません．レビューのために文書を用意してはいけないことを第5回「設計レビューでするべきこと，してはいけないこと」でもお伝えしました．レビューに限らず，仕事の内容，プロセス，品質を見せることを目的にして文書を作成すると，本稿の最初に触れたような「書かされ感」によって強いられるドキュメンテーションとなってしまいます．あなたには，ぜひ主体性を持って仕事に取り組んでいただきたいのです．

●見えてくるから検証できる

　対象が見えてくると，それを調べることは容易になります．調べた結果を，不備や不足の修正につなげることで，品質も高くなるはずです．

　仕事を文書という媒体によって可視化したら，その文書を調べることで，仕事の出来栄えを確認しましょう．自分と他者による査読の勧めを，第4回「自分の「赤ペン先生」を持とう」でもお伝えしました．そして，他者による文書の査読やレビューの一つの方法として，文書診断を紹介しました．

　文書診断では，次の点を調べます．

（1）正確であること ―― 文法が正しい，表記ルールに則っている，表現に間違いがない，伝える事柄に間違いがない，一意に理解できる，など
（2）読みやすいこと ―― 明快である，簡潔である，など
（3）目的に合っていること ―― 文書の目的が明確である，目的に対して必要十分な事柄が記述されている（例えば，ソフトウェア開発文書として，要求仕様書として，○○分野の設計書として...），など

　ここで，（1）（2）は，一般的な技術文書として備えていなければならない条件です．正確で読みやすい文を追求すれば，文書の中のあいまい性を排除することにつながります．筆者の経験では，記述のあいまい性は，思考のあいまい性を反映していることがしばしばあります（第4回を参照）．そのために，記述のあいまい性を排除することが自身の知的能力を高め，ひいては仕事自体のあいまい性をなくし，あらゆる品質を高めることにもつながってきます．

　また，（3）は，文書を仕事の成果として見たときに，文書を診断する際のより重要な項目になります．例えばソフトウェア開発の設計工程では，タスクの分割や大域変数の定義などが，開発要求に相呼応して行わなければなりません．もちろん技術的に正しくなければなりませんし，その設計を選択した理由が妥当でなければなりません．設計書の目的を正しく理解することが必要です．文書診断は，このような視点から記述の内容を意味的に，時には専門知識を駆使しながら調べるので，個々の作業の問題点，工程の問題点，プロセスの問題点を発見することにも発展します．

　このように，「文書が仕事の目的に合っているか」を調べることとは，つまりは「行った仕事が目的に合っているか」を調べることになります．これは，仕事の妥当性を確認することといえます．