バグ報告文の基本を見直す
こんにちは、株式会社フィラメント、プログラマーの西です。
私も新人ブログを書くのは今回が最後となります。1年以上続いたブログの
最終テーマは「バグ報告の文章」について書きたいと思います。
実はこのテーマ、以前にも書こうと思いましたが、文章作成が苦手なためまとめ切れず没にしておりました。しかし、最近『まんがでわかる理科系の作文技術』という文章術の書籍を読みまして、文章を書く際の心構えやエッセンスがバグ報告の文章を作成する際の参考になり、解りやすかったので書籍に手助けして頂きながら、まとめていきたいと思います。
必要なことだけ漏れなく記述する
書籍では”仕事の文書”を書く際の心得は、以下のように記述されています。
①主題について述べるべき事実と意見を十分に精選
②それらを、事実と意見とを峻別しながら順序よく明快・簡潔に記述すること
バグ報告書でも同じように主題（報告したいバグ）の事実を抜き出し、なるべく明快・簡潔に記述する必要があります。というより、すべての報告書や文書における超基本的な心得ですので、バグ報告書を書く時以外も常に意識するように心がけています。
一文書一主題
文章を明確にする心得として”一文書一主題”というのもありました。
別の主題が混入すると、読む相手に与える印象が散漫になり、文章の説得力が低下する。
本来の目的以外のことで重要な情報が得られたときには、それを調査報告書の本体に書き込むのではなく、本体と分離できる付録にするか、あるいは別の報告書にまとめたほうがよいでしょう。
これもバグ報告ではとても重要な要素でした。バグの調査を行っている際、他のバグも同時に見つかることがあります。その時、同じ報告書で記述したくなる気持ちもありますが、そうしてしまうと情報が散漫になってしまいますので別の報告書として新規に作成するようにしています。
重点先行主義
書き出し（リード）を読めば、文書に述べてあるもっとも重要なポイントが分かるように配慮する。
これもバグ報告の際に意識する必要のある項目です。報告書の題名や書き出しだけで、ある程度の情報が共有できるように心がけています。どんなバグが起こっているのか、そのバグはゲームが停止してしまう危険な物なのか、そうでないのか等、緊急性や重要性がわかるように意識しています。
情報の伝達は「概観から細部へ」
まず大づかみな説明をして読者に概観を示してから、細部の説明に入る。
最初からバグについて細かく情報を記述しても、いまいち相手に伝わらないことがあります。その場合はこの項目が守れていないことが多いです。報告の際は相手が必ず分かる部分から記述をする必要があります。例えば、動作手順の記述の際も横着して途中から工程を書いた時に、動作のズレから情報の共有がうまくいかない場合があるので注意しています。
事実と意見の区別
事実を書いているのか、意見を書いているのかをいつも意識して、両者を明らかに区別して書く。
書いた後で逆にとられる心配はないかと入念に読み返す。
事実の記述には、意見を混入させないようにする。
この項目はバグの原因がどこにあるか、ある程度推測できた時に特に注意しています。推測をはらむ状態で報告書を作成すると、調査した事実の中に推測の意見が混じってしまうことがあります。そうすると誤解や間違いを生む危険性が高くなります。そのため、調査した事実と推測による意見を分けてから書き始めるようにしています。また、書き終わった後も解釈が複数になる可能性のある文や句点の位置で意味が変わる文はないか、確認も忘れないようにしています。
書籍には他にもためになることが書いてありましたが、今回記述したのはバグ報告書を書く際、特に参考になった項目です。文を書く際の意識はまだまだ未熟で、気を抜くと変な文になることがあります。これからも今回書いたことを忘れないように、日々意識して文書を書いて行きたいと思います。
