「過不足なく書いたつもり」なのに伝わらない——ドキュメントの書き漏れをどう防ぐか

「そこが伝わってなかった」と言われるということは、伝えたつもりなのに穴があって、「え、そういうつもりだったの?」みたいなことが起こってるということですよね。

よくある話だと思います。

ただ、過不足なく書いてるつもりなのに、というところに意識が向いていると、これはけっこう悩ましい問題なんです。

いわゆるMECEMECE ── 漏れなくダブりなく整理されている状態になっているか、というところですね。

設計書や運用マニュアルを書くことが多い方なら、たぶん何を書かなきゃいけないのか、本でいう章立てや構成みたいなものが、なんとなく頭の中にあるんじゃないかと思うんです。

そこで私がおすすめしたいのは、過去に自分が書いたものを元に「ひな形」を一回作ってしまうことです。

「そこが伝わってなかったって何なんだろう」というものをちゃんと洗い出して、項目を整理しておく。

自分の勘に頼ってる限りは、やっぱり抜け漏れは出ますからね。

もう一つ感じたのが、要件は書いてるんだけど、前提条件や設定されている値、環境の違いみたいなところが抜けてしまってるんじゃないか、ということです。

「自分はそこ理解できてるよね」「この流れなら本番環境の話だって読み取れるよね」という感じで、つい書かなくなってしまってるのかもしれません。

なんでこうなるかというと、ドキュメントって自分は上から順番に書いていくじゃないですか。

だから書いてる本人の頭の中では、何の話をしているのかストーリーが全部つながってるんです。

でも、設計書や運用マニュアルって一定の文書量になりますよね。

そうなると何が起こるかというと、読む人は上からちゃんと読んでくれないんですよ。

自分が探している単語がどこにあるかな、と間をすっ飛ばして「あった、ここかな」と読んでしまう。

その時に、前提条件が「上から読んでいること」を前提に書かれていると、言葉の抜け漏れが出てしまうんですよね。

じゃあ前提条件をぜんぶ名詞で書けばいいのかというと、それはそれで本当にくどい文章になります。

書いてる本人からすると「本番環境で、次も本番環境で、その次も本番環境で」なんて、「わかっとるわ」となりますよね。

なので、指示代名詞で済ませてしまうのも、認識のズレの原因になりがちなポイントなんです。

私が思うのは、大きな塊、つまり段落の中くらいはいいと思うんですけど、見出しのレベルが変わるタイミングですね。

見出し2から見出し3に入っていくような区切りのところでは、一回くらい前提条件に立ち返って書いておく方が、読み間違いをされづらくなるんじゃないかと思います。

書いた本人からすると、ちょっと冗長に感じてしまうかもしれません。

でも、自分が上から下まで全部理解しているという状態のほうが、共有するドキュメントではむしろマイノリティなんですよね。

そのことを理解した上でドキュメントを書けるようになると、ちょっと見え方が変わってくるんじゃないかと思います。

ここまでの話を、私なりに整理してみますね。

まず、今まで作ってきたので頭の中にあるはずの「どんな項目で書いているか」を、一旦全部洗い出してみる。

これは自分で使うのはもちろん、後輩の方にお見せする資料としても、たぶんいいものになると思うんです。

• 書いている項目を全部洗い出して、抜けている項目を充当する
• 前提条件になるものを、適切に名詞として書き連ねる
• 見出しが変わる区切りでは、一度前提条件に立ち返る

そして、他の人はドキュメントを初見で見た上に、ページ内検索でそれっぽい単語の箇所を直接フォーカスして読んでしまう。

自分もそうですし、私自身もけっこうやってると思うんですよね。

だからこそ、読む人の読み方を前提にドキュメントを組み立てておく、というのが大事なんじゃないかなと思っています。

まとめ

結局のところ、書き手は全部わかっているけど、読み手はそうじゃない、というギャップにどう向き合うかなんだと思います。今の私はそんなふうに考えていますが、皆さんのドキュメントはどうでしょうか。

• 「過不足なく書いたつもり」でも抜けるので、過去の自分の文書からひな形を作って洗い出す
• 読む人は上から読まず拾い読みするので、前提条件が「上から読む前提」だと抜け漏れになる
• 見出しが変わる区切りでは、くどくても一度前提条件に立ち返って書いておく
• 自分が全体を理解している状態はドキュメント上ではむしろ少数派、と意識して書く