最近筋トレにハマっている、アウトソーシングテクノロジーの神谷です。
誰でもやってるような事ですが、メモ代わりに。
１．できる限りナンバリングをする
悪い例
このシステムの以下の特徴について記載します。
・冗長性
・可用性
・拡張性
良い例
このシステムの以下の特徴について記載します。
(1)冗長性
(2)可用性
(3)拡張性
大体のドキュメントというものはお客様に出すものなので、お客様レビューで「この項目の○○番目の項目が●●番目の項目と違います」と指定されるより「(3)の表現が(5)と違います」と簡潔に、間違いなく指示できるので、お互いに楽です。
項目3つぐらいならいいじゃない、と思うかもですが、システムというものは拡大していくので、すぐ20、30と増えていきます。大体、少ないからナンバリングしない、多ければナンバリングするって、それってどれぐらいの数を指します？「個人の感覚」でしかないのでは？
そんなあやふやなルールに則るぐらいなら全部ナンバリングすべきです。今時のドキュメントエディタは全部自動でナンバリング振ってくれますし。
２．表にはタイトルを付ける
表の一番上には、その列で何のパラメータを記載するのかを示すタイトルを付けましょう。
タイトルが付けられない表があったとしたら、それは実は表にすべきではなかったり「この列は何なの？」とお客さんに聞かれたときに答えられなかったりしますし、書いていて自分でもよく判らなくなってきます。
逆にレビューしてもらう時は表はタイトルだけにして「中身はあとで埋めます。まずはドキュメントの方向性を意識を統一したいです」とかいうのさえアリだと思います。それぐらいタイトルは重要です。
３．「書面レビュー」をやる
最近はスピーディな対面レビューばかりが人気ですが、対面だと基本的に口語体になってしまうため、その時に書くように指示された文章を書面に起こすと変だったりします。口頭で説明されると判るけど、書面だけ見ると実は説明が抜けている、なんて事は珍しくありません。
冷静に物事を見るなら書面レビューが必須です。
少なくともお客様に見せるようなドキュメントであれば、一度は社内の書面レビューは経るべきではないか、と自分は思います。
また、書面レビューの経験を多く積むと、大体レビューで引っかかるような事は書かなくなっていきます。経験が大事です。
最近他人のドキュメントをよく読むので、その時に思ったことを挙げてみました。