ウェブ技術者がもらってうれしいバグ報告書のテンプレート
新たなバグの発見が技術者にとってうれしいことであるかどうかは状況によって変わりますが、もらってうれしいタイプのバグ報告書とそうでない報告書は明確に分かれます。
今回はいち技術者の立場から、ウェブ技術者といっしょに働く機会のある非技術者の方向けに ウェブ技術者がもらってうれしいバグ報告書のパターン についてお話しします。
対象読者
本記事の対象読者はウェブ技術者以外の方です。 具体的には次のような職種の方をイメージしています。
- IT 担当者
- サイト管理者
- サイト運用担当者
- ウェブデザイナー
- マーケター
前提
次の前提を措いています。
- 対象のバグはウェブサイトやウェブシステムに関するものであること
技術者はどのようにバグに対応するか
技術者がもらってうれしいバグ報告書がどのようなものなのかをお話しする前に、そもそもウェブ技術者はどのようにしてバグに対応するのか一連の流れをかんたんに説明します。 技術者がバグに対応するときの流れが把握できれば、技術者がどんなことを望みどんなことを嫌うか想像しやすいと思います。
細かい粒度で洗い出すと技術者はおおよそ次の流れでバグを解決します。
- 問題を記録する
- 問題（ WHAT ）を理解する
- 問題の原因（ WHY ）を特定する
- 解決策（ HOW ）を決める
- 解決策を実装する
- テストする
- 本番環境に反映する
- 報告する
- 結果を記録する
外から目に見えやすいのはこのうちのステップ 8 と 9 だけですが、実は技術者は他の職種の人たちに見えづらいところで多くの作業を行っています。
チームでバグ対応フローが標準化できていない場合や、バグの原因がひと目で明らかですぐにかいけつできる場合はこれとは異なる手順で進めることもあります。しかし、例外的なケースを除くとほとんどのケースではウェブ技術者はおおよそこの流れに沿って日々バグ対応を行っています。
ポイントは、一定のレベル以上の技術者は「問題が解決できたらそれで OK でしょ」という安易な考えではなく「 真の原因を正しく特定し、考えうる中でベストな方法を使って、深刻な副作用を出すことなくかつ再発を予防してバグを解決するべきだ 」という考えを持って対応を行っているという点です。 このような考え方をもって対応を行うと余計な手間やコストがかかって短期的には非効率なように見えますが、長期的には場当たり的・属人的な対応よりも費用対効果が高くなります。
傍から見るとほんのちょっとの作業のように思えても、目に見えないところで多くの努力が行われているということを、技術者と接する人たちは理解しておくべきだと思います。
バグ報告者が持つべき姿勢
続いて、バグ報告をする側の人が持つべき姿勢についてお話しします。
上述のバグ対応の流れを踏まえた上で、バグを報告する側が持つべきは 技術者といっしょにバグを解決しようとする姿勢 です。 これは問題解決の効率という「合理性」の面でも、対応する技術者の「心象・印象」という面においても重要なポイントです。
ソフトウェアのバグというのは要は ソフトウェアに対する「期待」と「現実」のギャップ のことなので、バグの原因はさまざまです。 バグの原因が技術者側にあるとはかぎりません。 仮に技術者側に原因がある場合でもたまたま対応を行った担当者に原因があるともかぎりません。
また、報告する側がバグだと思って伝えたものが実はバグではなかったということもよくあります。 ある程度以上キャリアの長い技術者であれば、「バグだろどうにかしろ！」と誰かから言われてかなりの時間をかけて調査をした結果、単なる報告者の思い違いだとわかったという経験を誰しもがしています。
そんなさまざまな可能性が考えられるバグに対して、「はい、バグだよ。お前の責任だろ。どうにかしろ」と一方的に投げ付けられるのは気持ちのよいことではありません。
次のような態度はバグの解決を阻害するだけで何もメリットはありません。
- 情報提供に非協力的である
- 技術者側に原因があると決めつける
- 問題の解決ではなく責任追及や批判にこだわる
「速やかかつ適切にバグが解決される」という共通のゴールに向けて積極的に関わることが、バグ解決のコストと時間を最小限に抑えるいちばんの秘訣です。
バグ報告で押さえるべきポイント
では実際にバグ報告の際に押さえるべきポイントとしてどのようなものがあるでしょうか。 箇条書きであげていきます。
- 具体的・正確に伝える
- できるだけ多くの情報を伝える
- 簡潔に伝える
- 事実と推測を分ける
具体的・正確に伝える : バグ報告は具体的で正確であることが望ましいです。 たとえばウェブサイトの場合は「どのページでどんなことをした結果、どんなことが起こったのか」を正確・明確に伝えましょう。
できるだけ多くの情報を伝える : バグ報告にはできるだけ多くの情報が含まれていることが望ましいです。 情報量が豊富であればあるほど、技術者側の対応作業はスムーズに進みます。 一般に、バグ報告者が伝えるべきだと思う情報量よりもバグ対応技術者が必要とする情報は多いものです。
簡潔に伝える : 説明は簡潔・ストレートであることが望ましいです。 情報量は豊富なほどよいですが、説明は簡潔にしないと、問題が何なのかを技術者が正しく把握できないことがあります。
事実と推測を分ける : 客観的に観測された「事実」とバグ報告者の「推測」は明確に分けることが望ましいです。 バグ報告書に書かれている情報が、実際に発生した事象なのか、報告者の頭の中の推測なのかがわからないと、技術者が状況を誤認識することがあります。
ウェブ技術者がもらってうれしいバグ報告書のテンプレート
以上のことを踏まえて、バグ報告書のいちテンプレートをご紹介します。
尚、ソフトウェアのバグに関して技術者が知りたいと思うことはある程度共通していますが、業界標準のフォーマットがあるわけではありません。 適切なテンプレートはプロジェクトやチームによって異なるので、これが絶対のものと思わないようにしてください。
- タイトル
- 発生した事象
- 問題点
- 再現手順
- 発生環境
- 期待する結果
- その他
各項目について説明していきます。
1. タイトル
バグをひとことで説明するタイトルです。 考え方はメールの件名や論文のタイトル等と同じで、 バグを説明するのに必要な情報を最小限のことばで記述する ことがポイントです。 目安として、日本語なら 10 字以上 40 字以下程度に収めることが望ましいでしょう。
よい例:
- 記事ページのパンくずリストの改行位置がおかしい
- 固定ページの投稿時に特定の文字を入力するとページが保存ができない
悪い例:
- バグ発生
- 【至急修正要】表示に問題あり
「バグ発生」というタイトルはバグを報告する側からすれば一見わかりやすいように思えますが、毎日のようにバグ対応をしている技術者にとってはそんな抽象的なタイトルから得られる情報量はゼロです。
また「【至急】」のようなタグ付けをしても何らメリットはありません。 もし報告者とバグ対応の窓口担当者の間で相当の信頼関係・あうんの呼吸ができているのなら「【至急】」と書くのはありなこともありますが、通常は付けるべきではありません。 十分な関係性が構築されていないのに「【至急】」とタイトルに付けるのは、人のデスクに書類を投げつけて「これ至急で！」と言う、昭和時代のコミュニケーションスタイルです。
タイトルがダメな報告書は中身もダメなことが多く、そのようなバグ報告に関わると事実確認だけでも多くの時間を取られてしまうことを技術者たちは知っています。 タイトルの第一印象が悪いとそれだけで優先順位を下げられる可能性もあることを知っておくとよいでしょう。
2. 発生した事象
発生した事象についての説明です。 具体的にどんなことが発生したのか、観測できた「事実」を記述します。 次に述べる「問題点」とあわせて説明した方がわかりやすければ、ふたつあわせて説明するようにするとよいでしょう。 何らかのエラー文が表示された場合は一連のエラー文をまるごとすべてコピーするか画面キャプチャを撮ります。
発生した事象に関しては「発生した事象≠問題点」である点に注意してください。
例えば、「今年は米が豊作である」という事象はそれだけでは問題ではありません。 豊作の結果としてたとえば「米が余るため廃棄する必要がある」ということが発生すると、はじめてそれは問題になります。 この問題は「米が豊作」という事象から演繹的に導き出せるものではなく、価値判断が加わった結果として初めて生じます。
発生した事象のどこに問題があるのか、なぜ問題なのかという問題認識も技術者にもわかるようにあわせて説明できるとなおよしです。
よい例:
記事 A のページ（ URL: https://example.com/article/a ）を Chrome ブラウザで開いたときに、メインメニューの「記事一覧」がハイライトされずに表示される。
悪い例:
記事のページをひとつ開いてみたら、ページの一部が正しく表示されない。
必要に応じて 5W1H のフレームワークを使って簡潔にわかりやすく伝えるとよいでしょう。
3. 問題点
発生した事象の問題点です。 前述のとおり、事象の説明だけでは何が問題なのか技術者が理解できないこともあります。 その事象のどこが問題なのか、なぜ問題なのかを記述しましょう。
例えば、発生した事象が「新しい記事を投稿したら、公開されてしまった。」の場合、問題点は次のように記述します。
サイトリニューアル時の仕様では、新しい記事を投稿したら一度非公開として保存され、改めて「公開」にチェックを入れて更新するとはじめて公開されることになっていた。 その仕様に反して、新しい記事が投稿直後に公開されてしまう点が問題である。
4. 再現手順
バグを再現するための手順です。 バグ対応に着手するときに技術者が真っ先にやることのひとつが「バグの再現」なので、具体的な再現手順というのはとても重要な情報です。 バグを再現すること、そして、バグを再現する手順を明確にすることで、技術者はバグとその原因を正しく把握できるようになります。
技術者のバグ対応の負担を軽減するため、「 どのような状況で、何をしたら、バグが発生したのか 」をわかりやすく伝えましょう。
いくつかポイントをあげます。
- 再現手順のフォーマットは、シンプルな箇条書きが望ましいです。
- ページを指す場合は、「○○なページ」というあいまいな説明は誤解のもとです。誤解の少ない URL を極力使うようにしましょう。
- ページ内のフィールドやボタン等のウィジェットを指す場合はそのラベルを正確に伝えましょう。
- ことばでの説明が難しい場合や誤解を招く可能性がある場合は、画像や動画のキャプチャを撮影して共有しましょう。
よい例:
- 「編集者」ユーザとしてログインする
- 記事の新規作成ページを開く（
https://example.com/admin/articles/article/add/）- 「タイトル」と「日付」を入力して、「保存して編集を続ける」ボタンをクリックする
- 「編集者」ユーザをログアウトする
- ログインしない状態のまま、作成された記事のページを開く（
https://example.com/articles/[新しいID]）- 記事が表示されてしまう（←問題が発生）
悪い例:
記事のページを開いて、フォームに適当に入力して、保存した。記事をチェックすると、記事が公開されている。
箇条書きの方が断然読みやすくわかりやすいことがお分かりいただけるかと思います。
5. 発生環境
バグが発生した環境です。 技術者以外の方はよく「自分の手元で発生したバグは、別の場所でも必ず発生するもの」と考えがちですが、実際にはそんなことはありません。 多くのバグは、特定の環境下、特定の場所でのみ発生します。 特に、ページのレイアウトやスタイル等の見た目の問題は環境に大きく依存するので、できるだけ詳細に情報を伝えるようにしましょう。
ウェブサイトのバグの場合は、最低限以下の情報を伝えるようにするとバグ対応がスムーズです。
- OS （ Windows 10 / macOS / Android x.x / iOS x.x 等）
- 端末（ iPhone 8 / Google Pixel 2 等）
- ブラウザ（ Chrome / Android ブラウザ 等）
- アカウント（ログインができるサイトの場合）
6. 期待する結果
バグが発生する状況で期待する結果です。 「本来はこうなることを期待していたのに、実際はこうなってしまった」と、期待と現実のギャップを示すことで、問題点を明確にすることができます。 問題点のところで十分に説明ができている場合はここは飛ばしてもよいでしょう。
オープンソースのソフトウェアでは、バグ報告のテンプレートにこの項目が含まれているものもよく見かけます。
7. その他
その他補足情報です。 上の項目のどれにもあてはまらないことで付け足すべき情報がもしあればあわせて共有します。 例えば、過去には発生していなかったバグが新しく発生するようになったのであれば、いつ頃からバグが発生したのかを正確に伝えてもらえると技術者は助かります。
以上、技術者がもらってうれしいバグ報告書のお話でした。
最後にまとめとして手順を再掲します。
- タイトル
- 発生した事象
- 問題点
- 再現手順
- 発生環境
- 期待する結果
- その他
「おおよそのテンプレートはわかったけれど、いざ書こうと思ってもうまく書けない」という場合には、技術者に過去の報告書を見せてもらうとよいと思います。 実際のサンプルを見ると多くの方はすぐに効果的なバグ報告書を書けるようになります。
バグが絶対に生まれないソフトウェアやウェブサイトはこの世には存在しないので、ウェブ技術者と関わるのであれば、バグ対応の流れについて取り決めをしておくと断然スムーズです。
技術者とよい関係を築いてウェブプロジェクトを成功させたい方のご参考になれば幸いです :D