Transcript 分かりやすいドキュメントの書き方

分かりやすいドキュメントを目指
して
張小鋒
• このドキュメントは・・・を目指す。
• 表現は簡潔にすることを心がけましょう。
• 現状を説明する
・・・が正しいはず。→・・・が正しいはずだ
が、・・・になってしまいました。
質問の書き方
•
•
•
•
•
•
読む人の立場になって作る
問題を明確、簡単に説明する
例、手順を挙げる
環境に関わることは、こちらの環境を詳しく説明必須
短い文で表現する
データ量に関わることは明確にする ２０MのデータでCPUMEMで10秒で処理完
了…
• 選択肢を挙げて、質問する
• 選択肢があれば、自分をやりたい選択肢を誘導する
お進み：
・・・について（に関して）、・・・の質問があります。
・・・の場合、・・・のように処理してよろしいでしょうか？
・・・が正しいと思います。
下記の手順で、異常がありました。
①・・・
②・・・
•
•
•
•
•
•
図、表を使う
色で分ける
短い文を使う
説明点を挙げる
文章の章・節確定してから、書く
概要を説明する
質問の回答
• 簡単に回答する
• 回答できない場合、理由を説明する
・・・に対して、こちらは再現できません。
ご確認お願いします。
→・・・に対して、こちらは再現できませんでした。
・・・の環境で、・・・設定が異なると思いますが、そちらの設定を・・・
再現用データはこちらに送付してよろしいでしょうか？
こちら再現用データを送付して、データの作成方法は間違っていないでしょう
か？
指摘の書き方
• 指摘理由を明確する
• 指摘の内容を簡単にする
• 指摘箇所を明確する
• 指摘意見を挙げる
お進み：
…ので、修正してください。
…ため、・・・のように修正したほうがいい。
悪い指摘： ・・・のコードが分かりにくいです。修正してください。
→のコードが分かりにくいです。 If for等・・・関数を抽出し
て・・・