技術文書作成に関するメモ
何というか一応エンジニア的なお仕事をしているもので、職業柄製品検証とかそういうのやるんですよ。で、理系修士卒入社2年目な若手がやって検証報告書書いたんでレビューつきあえ言われてレビューやるんですね。なんかもう大学4年生が初めて書いた卒論の初稿レビューみたいな感じなんですよ。このレベルの添削からスタートかよと。おまえどうやって卒業したんだよと。報告書真っ赤にして3時間くらい突っ込む作業を繰り返す訳ですよ。
というあれこれで奴に言っておきたいこととかモロモロをここではき出して憂さを晴らそうと思います。
- 大前提として、自分の考えや意図は、他人には伝わりません。人に誤解を与えず、必要最低限の情報量で何かを伝えることは非常に難しい作業だと言うことを認識してください。特に共通する知識や背景がない場合は困難です。あなたが検証したもの(こと)についての知識を、私は持っていません。あなたが作業を進める中で常識だと思っていることを、私は知りません。読者が知っていると思わないでください。読者は何も知りません。というか知っている人ならこんな報告書を読む必要がありません。言わなくてもわかると思いました? 私もあなたもテレパシストではありません。
- 読者を、早く、確実に誘導する努力を端折らないでください。
- あなたのその判断は、グラフや図のどのポイントを見て説明していますか? 見るべきポイントがあるのであれば明示してください。読者に探させると読者の時間を浪費させる上、議論や判断の根拠を曖昧にします。
- 変化はグラフにして示してください。数表を読ませるのは不親切です。
- 図や表を書くことを面倒くさがらないでください。図や表で表現せずにこじらせた文章を書いたあげく、読者の時間を浪費させた上、結局口頭で解説する羽目になる方がよほど面倒です。
- ドキュメントの量を水増しするだけの無駄な図や解説、重複した内容を記載しないでください。ドキュメントは短く簡潔であること望ましいです。とはいえ、はじめから短く書こうと意識しすぎて必要な内容まで省かれてしまうようでは意味がありません。多少冗長になろうとも、必要な情報を、なるべく簡潔な文で記述するようにしてください。
- 技術ドキュメントの骨格を正しく押さえてください。エンジニアが検証を行う場合、解決したい問題や見たい現象があったはずです。そしてその問題が導かれた背景があるはずです。そこから説明してください。何らかの背景のもとに、解決したい問題が起き、問題を解決することで何らかの利益が見込まれます。問題を解決するために何らかの方法が想定され、その方法や達成できることなどに不明点があり、検証をしていたのではないのですか? ストーリーを組み立ててください。
- 問題をもとに検証・調査すべきことを決めます。製品を使って何らかの問題を解決したいのであれば、その製品のどういう機能をどう使えば問題を解決できるのか、詳細化していきます。
- あなたが確認すべき問題は何でしょうか。機能でしょうか。性能でしょうか。観点はたくさんあります*1。詳細化した内容ごとに、解決したいこと、解決方法、実際にやってみた結果、結果に対する判断、考察・評価があります。ドキュメントは常に問題提起・対処・結果・判断の入れ子構造になります。問題に対して解決策が示されていない、判断に対してその根拠が示されていない、といった対応付けのミスマッチがないかどうかを常に確認してください。
- 「問題なく動作した」とは何を持ってそう判断したのですか? あなたの言う「問題なく」とは具体的に何ですか? 判断は証拠(エビデンス)をもとに議論をしてください。証拠のない結論は信用されません。根拠が示されないまま「問題なく」と言われても、ただの自己満足にしか見えません。逆に、証拠として掲載されている(ように見える)のに何も解説されないデータは意味がありません。報告書に載せるすべてのデータはその解釈と評価があるべきですし、解釈や評価にはすべてその根拠があるはずです。
- 判断や行動にはすべて理由があります。「何故こうしたのですか?」「なんとなくです」は最低の回答です。根拠や理由なく検証を進めて意味があるのでしょうか?
- 作業を行う際には、あらかじめ結果を予測してください。製品検証であれば、解決したいこと・製品の操作方法・操作による動作の想定・動作の確認方法を事前に組み立てておく必要があります。想定に対してその通りに実行できたかどうかで作業ごとに正否を確認してください。自分の認識とのズレを確認せずに、「とりあえずデータはとれたから後で確認しよう」という作業の進め方をしないでください(手戻りが増えます)。また、結果と予測のズレを感じたのであれば作業を止めて、自身の認識が違うのか製品の動作が問題なのかを切り分けてください(放置するとその後の作業がすべて無駄になる可能性があります)。「PDCAサイクル」くらいご存じかとは思いますが、知っているのであれば実際にやってください。
- 参照すべき情報・書籍は正しくリファレンスを記載してください。あなたが検証や作業に当たって必要としたドキュメント類は、読者も読む必要があるのではありませんか?
- 「この製品あるいは技術について検証しろ」と言われたからやってみたと言うだけなのですか?
- たいてい、起点は特定の製品や技術ではありません。順番を間違えないでください。技術も製品も手段であり、解決すべき問題が先にあるはずです。問題を解決するための手法の一つが製品や技術なのです*2。
- 「なぜ」: なぜ、その問題を解決すべきなのでしょうか? なぜ、その製品や技術に着目したのでしょうか。何故、その手法を選択したのでしょうか? なぜ、このような結果が得られたのでしょうか?
- 大本の理由付け・動機付けが曖昧なまま検証を進めないでください。
- 再現性を考慮してください。
- 低コストで高品質の作業・成果物を再現することで利益は発生します。あなたの書いた検証報告書を読むと、読んだ人が同様の検証や作業を、短時間で行えますか? 行えないのであれば何が不足しているのでしょうか?
- 操作手順を書く際は、必ず設定方法・設定の確認方法・動作状況(たとえば機器の内部状態)の確認方法を明記してください。
- 単なるコマンドだけでなく、運用のシナリオ、同時に行われる操作も想定してください。
- 検証の前提条件を明記してください。
- あなたが使った機器は、ソフトウェアのバージョンは、設定は、測定方法は、使用したツールは、実験した際に設定したパラメータは、何でしょうか? あなたの検証の前提条件において、変動する要素、変動しない要素は何でしょうか?
- 現時点での制約、将来的に変化することがわかっている機能、などは「いつ時点の情報なのか」が重要になります。バグ情報、製品使用、ロードマップなどを記載する情報は「時点」を必ず明記してください。
- 想定される読者には未来の自分を含めてください。たとえば1年後に自分が再び同様の実験を行い、過去の実験と比較するとして、自分がかつて書いたドキュメントを読んで再実行できるでしょうか?
- 曖昧な表現や誤解・誤読されそうな表現を使わないでください。たとえばこういった表現が出たら黄色信号です:
- 「数十」「おおよそ」「おおむね」「約」「一部の」 : 値や範囲に幅があるのであればその幅を明確に書いてください。
- 「だと思われる」「と考えられる」 : あなたの感想ですか?
- 「など」: ほかにもあるということですか?
- 「充分」: どの量がどういった基準を満たしたから充分なのでしょうか?
- 用語・単語を組み合わせて、勝手に新しい言葉を作らないでください。辞書や類語検索などを活用してください。
- 用語、固有名詞は正しく記載してください。
- 略語が多い場合は用語一覧などを記載して、略語を定義してください。
- 一般化・抽象化してください。
- 問題に対して、解決策を考え、実行し、できた・できなかった、という結果を得るのは最初のラインです。
- 実際に行ってみた結果を基に一般化・抽象化をして議論を広げられないかどうか考えてください。得られた結果はどういった原理、理論、アーキテクチャから解釈できますか? その解釈は、いま使っている製品だけでなく、将来的に現れるであろう製品、あるいは他社の製品にも適用できるものでしょうか? 同一の構成で 100 倍や 1000 倍のキャパシティにしたときにも通用するものでしょうか? 今後3年・5年・10年たったときにも同様の考え方が使えないでしょうか? どんなケースでも使える「型」「パターン」はありませんか?
- 対照実験を行うようにしてください。特に性能の評価は前提事項に基づく相対的な評価が必要になります。変えたときに何がどのように変化しますか? 変化を定量的に説明してください。その変化を原理・原則に基づいて説明できますか? 逆に変化しないものはありますか? どのパターンにも適用可能な評価基準はありませんか?
- 「検証」「実験」は、限られたリソースでどこまで一般的な構成を解説できるかどうかが評価ポイントになります。使うものが変わればまた同じ検証をしてみなければいけないのでしょうか?
- 口頭で説明することを想定してください。
- 文章は一度口に出して読んでください。「の」ばかり続く、「と」を2つも3つも使って連結する、一つの文章が3行以上もある、など不自然な文章がないかどうかくらいはあらかじめ確認してください。
- 図表には必ず図表番号を振ってください。口頭で参照しやすくなります。
- 表には項番を振ってください。口頭で参照しやすくなります。
- ドキュメントの内容を説明する際、文章の内容を図を書いて説明し始めるのであれば、その図は最初から必要なのではありませんか?
- 検証・実験にあたり、実際に作業して初めてわかった知識はありませんか? 予想通り・仕様通り・理想的な動作をする製品ばかりではありません。イレギュラーな動作(あるいはバグ)、そのワークアラウンド、製品マニュアルに記載されていない制限事項や動作、利用にあたって検討すべきポイント、ベストプラクティス、自分がはまった落とし穴、など、実際に手を動かして初めて理解できたことはありませんか? そういった情報は、あなたのドキュメントを読んで同様の作業を行う人も知りたい情報なのではありませんか?
- 「どう説明したら良いのかわからないので」という気持ちはわかりますが、それが難しいからこそドキュメントで表現することに価値があります。複雑なもの、抽象的な概念を適切に表現し、他人に伝達できるということに価値があります。表現を工夫することをあきらめないでください。難しいからといってドキュメントから削らないでください。あなたが得た知見を自分一人で抱え込まないでください。知識を蓄え、それを広く伝達させるのが検証・実験実施と報告書作成の目的です。
- 検証や実験の報告書の評価は、あなたが書いて満足したかどうかではなく、報告書を読む人がどれだけの知見を得られるかにあります。読者があなたと同じ技術・知識レベルに到達するために、あなたの書いたドキュメントを読めば、必要な時間が短縮されますか? あなたのドキュメントを読めば、あなたがいなくても仕事が進められますか?
- それが、求められた期日までに達成できないのであれば、価値がありません。あなたがどれほど苦労して作業を行い、報告書を書いたとしても、期日に間に合わなかったり、知識の伝達という用をなさないのであれば、無価値になってしまいます。
- 何が言いたいのかというと、期限の前日になって初稿のレビューとかあり得ないということです。あなたのその原稿のレベルで、1日ですべて修正して完成させられる訳がありません。すべてが手遅れでした。
はあ。とりあえず勢いだけではき出してみたら何となくすっきりした。
それにしてもなあ……震災後の初エントリがこれかよ。まあそんなものか。
