どういう視点でドキュメントを書けばいいのかな

仕事柄、人が作るドキュメントに対して、あれこれと注文をつけて差し戻したり、まぁ、いいんじゃないですかと同意することで外に出て行くドキュメントを見送ることをしているのです。

その、見る側の視点を知っていたら書くドキュメントは何か変わるのでしょうか。

ワタシは変わると思います。ドキュメントの仕上がり具合が断然良くなります。ドキュメントを見る人が何を感じて、何を基準にして差し戻しや修正を依頼しているかを知って書くことで、断然アウトプットするドキュメントの仕上がり具合は良くなるし、修正の手間が減るのです。

レギュレーションは守っているかな
組織の規定やガイド類があればそれに沿っているかどうかを見ますね。だって、違反している状態だったらドキュメントとしてエラーですから。ある意味、その規定・ガイド類はプロトコルなわけです。それを満たさないと意思疎通できないぞ、と。

プロトコルの仕様は法対応なものもあるでしょうし、組織のノウハウのようなものもあるでしょう。ドキュメントを作った人はそれを他の人に見てほしいという目的があって作っているのですから、その目的を達成するために守らないといけない最低限のルールということが言えます。

ドキュメントの構成の抜けはないかな
ドキュメントの体系や目次構成はドキュメントの骨格ですから、ある目次が抜けているとなると内臓がないようなものです。つまり、機能しないわけで、ドキュメントとして役に立たないばかりか、ドキュメントを作った目的を達成することができないんですよ。

そういう意味では、ドキュメントの定義でドキュメントの記述範囲を規定しまえば目次が欠けていても目的を達成することはできますね。

標題と内容が一致しているかな
目次を決めて内容を書き始めると、標題と内容がずれていくことがあります。そういうときは、スパッと内容を捨てる覚悟をした方がいいです。無理に標題に合わせようと修正しようとしても、頭の中では書き出したようにまだ整理が仕切れていないんです。

その整理が仕切れていない文章を直して苦労するくらいなら、標題を見て何を書かないといけないのか整理してから一から書き直すのが良いです。

あっちとこっちで不整合していないかな
目次ごとに章立てされて、それぞれに書かれる内容は単体では一見、尤もらしくても、相互参照をすると矛盾を記述していることがあります。これは、書く人が書きたい章立てから書き始めると起きやすいです。

それはなぜ起きるかというと、書きたい章立ては大概、書けるコンテンツだから。だから、その目次だけがドキュメントの目的を超えて詳細に書いてしまうんですね。

一方、書く気が進まないところは全くもって検討もしていないので目次だけだってあり得るのですね。好きなところから書いてもいいのですが、ドキュメントの目的に沿って書くレベルまでで揃えることが必要です。

てにをはも稀にあぶないよ
てにをは、は形式確認としての代表のようなものですが、これは最後です。基本的に誰も死なないので。ただ、ごく稀に死ぬかもしれないときがあります。死ぬとは意味が曖昧なままになる、意図しない意味を持つということです。

まぁ、それよりもその前に見ないといけない優先順位の高い方が多いですけど。