質問の答えを書く | 悪態のプログラマ
2010年12月05日(日)

質問の答えを書く

テーマ:ブログ

ビジネスによくあるシーン。


 1. ドキュメントを作る
 2. 誰かに見せる
 3. 質問される
 4. 質問に答える
 5. 納得してもらう


例えば、報告書の類とか、我々の仕事なら設計書のレビューなどもそうだ。また、ソースコードのレビューも同じである(以下、「ドキュメント」にはソースコードも含むものとする)。


さて、上記の流れの後でそのまま終わってしまう人も多いのだが、それはよくない。


単純に考えると、質問された内容というのは、「作成したドキュメントから読み取れなかったこと」である。しかも、少なくとも聞き手が質問せずにはおられない程度に「重要なこと」なのである。


そのため、今後、別の人(たとえば上司のそのまた上司)がこのドキュメントを読んだら、同じ質問をしてくる可能性が高い。質問の機会がなければ誤解されてしまうかもしれない。また、説明を受けた人ですら、後になってその内容が思い出せなくなって、違う解釈をしてしまうかもしれない。


「質問をする人に知識や読解力がないせいだ」と言いたい時もあるだろう。しかし、読ませる相手のレベルに合っていないドキュメントは悪いドキュメントである。幼児向けの絵本を漢字ばかりで書いているようなものだ。



ドキュメントの説明で質問があったなら、口頭で説明しておしまいにせず、説明した内容をドキュメントから読み取れるように、追記や修正をしておきたい。


ソースコードの場合なら、構造を見直す(リファクタリング)、変数名やクラス名・関数名を見直す、コメントを見直す、といった対応を検討すべきだろう。


特に、品質管理のために行うレビューの場合は、レビューアにドキュメントの内容を伝えることが目的ではなく、ドキュメントを良くすることが目的なのだから、なおさらである。





■関連記事
この文書は誰が読むのか
どこまで書くか設計書
書かずに伝える
ドキュメントへの「朱筆」について考える




ついてきなぁ!『設計書ワザ』で勝負する技術者となれ!
國井 良昌
日刊工業新聞社
売り上げランキング: 83877

リファクタリング―プログラムの体質改善テクニック (Object Technology Series)
マーチン ファウラー Martin Fowler 児玉 公信 平澤 章 友野 晶夫 梅沢 真史
ピアソンエデュケーション
売り上げランキング: 5343

argvさんの読者になろう

ブログの更新情報が受け取れて、アクセスが簡単になります

コメント

[コメントする]

Ameba人気のブログ

Amebaトピックス

    ブログをはじめる

    たくさんの芸能人・有名人が
    書いているAmebaブログを
    無料で簡単にはじめることができます。

    公式トップブロガーへ応募

    多くの方にご紹介したいブログを
    執筆する方を「公式トップブロガー」
    として認定しております。

    芸能人・有名人ブログを開設

    Amebaブログでは、芸能人・有名人ブログを
    ご希望される著名人の方/事務所様を
    随時募集しております。