Dyno

ウェブ技術者がもらってうれしいバグ報告書

技術者にとって、バグが見つかることがうれしいかどうかは状況によって変わりますが、うれしいバグ報告書とそうでない報告書は明確に分かれます。

今回はいち技術者の立場から、ウェブ技術者と接する機会のある非技術者の方に向けて ウェブ技術者がもらってうれしいバグ報告書 についてお話しします。

想定読者

本記事の想定読者はウェブの技術者以外の方です。 具体的には次のような職種の方をイメージしています。

  • IT 担当者
  • サイト管理者
  • サイト運用担当者
  • ウェブデザイナー
  • マーケター

前提

次の前提を措いています。

  • 対象のバグはウェブサイトやウェブシステムに関するものであること

技術者はどのようにバグに対応するか

技術者にとってうれしいバグ報告書がどのようなものなのかお話しする前に、そもそもウェブ技術者はどのようにしてバグに対応するのかをかんたんにご説明します。 技術者がバグに対応するときの大まかな流れが把握できていれば、技術者がどんなことを望みどんなことを嫌うか想像しやすいと思います。

細かい粒度で洗い出すと、技術者はおおよそ次のステップでバグを解決します。

  1. 問題を記録する
  2. 問題( WHAT )を理解する
  3. 問題の原因( WHY )を特定する
  4. 解決策( HOW )を決める
  5. 解決策を実装する
  6. テストする
  7. 本番環境に反映する
  8. 報告する
  9. 結果を記録する

外から目に見えやすいのはこの中のステップ 8 と 9 だけですが、実は技術者は目に見えないところで多くの作業を行っています。

たとえばバグ対応のフローが標準化できていない場合や、バグの原因がひと目で明らかな場合はこれとは異なる手順を踏むことはありますが、そのような例外を除きほとんどのケースにおいては、ウェブ技術者はおおよそこの流れに沿って日々バグ対応を行います。

ポイントは、一定のレベル以上の技術者は「問題が解決できればそれで OK でしょ」という安易な考えではなく「 原因を正しく把握し、考えうる中でベストな方法を選んで、深刻な副作用を出すことなくかつ再発を予防してバグを解決するべきだ 」という考えを持って対応を行っているという点です。 このようなアプローチでの対応を行うと短期的には手間やコストがかかって非効率に見えますが、長期的には場当たり的・属人的な対応よりも費用対効果が高くなります。

傍から見ると軽い対応作業のように思えても、一定の知識と努力が割かれているということを、技術者と接する人たちは理解しておくべきです。

バグ報告者が持つべき姿勢

続いて、バグ報告をする側の人が持つべき姿勢についてお話しします。

上述のバグ対応の流れを踏まえた上で、バグを報告する側が持つべきは 技術者といっしょにバグを解決しようとする姿勢 です。 これは作業効率という合理性の面でも、対応する技術者の心象・心理的な面においても重要です。

ソフトウェアのバグというのは言わば「ソフトウェアに対する期待と現実のギャップ」なので、さまざまな要因がバグの原因となりえます。 そもそも対象となるバグの原因が技術者側にあるとはかぎりませんし、仮に技術者側に原因があるものであってもバグ対応の担当者がそれに関係しているとはかぎりません。

また、報告する側がバグと思って伝えたものが実はバグではなかったということもよくあることです。 キャリアがある程度以上長い技術者であればおそらく、「バグだろどうにかしろ!」と言われてある程度時間をかけて調査をした結果、報告者のただの勘違いだった経験を誰しもしています。

そんなさまざまな可能性が考えられるバグに対して、「はい、バグだよ。どうにかしろ」と一方的に投げ付けられるのは気持ちのよいことではありません。

次のような態度はバグの解決を阻害するだけで何もメリットはありません。

  • 情報提供に非協力的である
  • 技術者に原因があると決めつける
  • バグの解決ではなく批判にこだわる

「バグが速やかに適切に解決される」という共通のゴールに向けて積極的に対応に参加することが、バグ解決のコストと時間を最小限に抑えるいちばんの秘訣です。

バグ報告で押さえるべきポイント

では実際にバグ報告の際に押さえるべきポイントとしてどのようなものがあるでしょうか。 箇条書きであげていきます。

  • 具体的・正確に伝える
  • できるだけ多くの情報を伝える
  • 簡潔に伝える
  • 事実と推測を分ける

具体的・正確に伝える : バグ報告は具体的で正確であることが望ましいです。 たとえばウェブサイトの場合は、「どのページでどんなことをした結果、どんなことが起こったのか」を正確・明確に伝えましょう。

できるだけ多くの情報を伝える : バグ報告にはできるだけ多くの情報が含まれていることが望ましいです。 情報量が豊富であればあるほど、技術者側の対応作業はスムーズに進みます。 一般に、非技術者であるバグ報告者が伝えるべきだと思う情報量よりも、バグ対応技術者が求める情報は多いものです。

簡潔に伝える : 説明は簡潔・ストレートであることが望ましいです。 情報量は豊富なほどよいですが、説明は簡潔にしないと、問題が何なのかを技術者が正しく把握できないことがあります。

事実と推測を分ける : 客観的に観測された「事実」とバグ報告者の「推測」は明確に分けることが望ましいです。 バグ報告書に書かれている情報が、実際に発生した事象なのか、報告者の頭の中の推測なのかがわからないと、技術者が状況を誤認識することがあります。

ウェブ技術者がもらってうれしいバグ報告書のテンプレート

以上のことを踏まえて、バグ報告書のいちテンプレートをご紹介します。

ソフトウェアのバグに関して技術者が知りたいと思うこと・求めることはある程度共通してはいますが、業界標準の絶対的なフォーマットがあるわけではありません。 適切なテンプレートはプロジェクトやチームによってまちまちなので、これが絶対のものと思わないようにしてください。

  1. タイトル
  2. 発生した事象
  3. 問題点
  4. 再現手順
  5. 発生環境
  6. 期待する結果
  7. その他

各項目について説明していきます。

1. タイトル

バグをひとことで説明するタイトルです。 考え方はメールの件名や論文のタイトル等と同じで、 バグを説明するのに必要な情報を最小限のことばで記述する ことがポイントです。 目安として、日本語なら 10 字以上 40 字以下程度に収めることが望ましいでしょう。

よい例:

  • 記事ページのパンくずリストの改行位置がおかしい
  • 固定ページの投稿時に特定の文字を入力するとページが保存ができない

悪い例:

  • バグ発生
  • 【至急修正要】表示に問題あり

「バグ発生」というタイトルはバグを報告する側からすれば一見わかりやすいように思えますが、毎日のようにバグ対応をしている技術者にとってはそんなぼんやりしたタイトルから得られる情報量はほぼゼロです。

また「【至急】」のようなタグ付けをしてもメリットはありません。 もし報告者とバグ対応の窓口担当者の間でそのような関係性・あうんの呼吸ができているのなら「【至急】」と書くのはありですが、そうでなければ通常は付けるべきではありません。 そんな関係性でも無いのに「【至急】」とタイトルに付けるのは、人のデスクに書類を投げつけて「これ至急で!」と言う、まさに昭和スタイルのコミュニケーションです。

タイトルがダメな報告書はだいたい中身も要領を得ずふんわりしているものなので、事実確認だけでも多くの時間を取られるのが常です。 技術者はタイトルがダメなバグ報告はつい優先度を下げて後回しにしたくなります。

2. 発生した事象

発生した事象についての説明です。 具体的にどんなことが発生したのかを記述します。 次の「問題点」とあわせて説明した方がわかりやすければ、ふたつあわせて説明するようにしましょう。 何らかのエラー文が表示された場合はそれをまるごとコピーするか画面キャプチャを撮ります。

発生した事象に関しては「発生した事象≠問題点」である点に注意してください。

例えば、「米が豊作」という事象はそれだけでは問題ではありません。 豊作の結果として「米が余って廃棄する必要がある」ということがあるとはじめて問題になります。 この問題は「米が豊作」という事象から必然的に導き出せるものではなく、価値判断が加わった結果として初めて生じます。

発生した事象のどこに問題があるのか、なぜ問題なのかという問題認識も技術者にもわかるようにあわせて説明できるとなおよしです。

よい例:

記事 A のページ( URL: https://example.com/article/a )を Chrome ブラウザで開いたときに、メインメニューの「記事一覧」がハイライトされずに表示される。

悪い例:

記事のページをひとつ開いてみたら、ページの一部が正しく表示されない。

必要に応じて 5W1H のフレームワークを使って簡潔にわかりやすく伝えるとよいでしょう。

3. 問題点

発生した事象の問題点です。 前述のとおり、事象の説明だけでは何が問題なのか技術者が理解できないこともあります。 その事象のどこが問題なのか、なぜ問題なのかを記述しましょう。

例えば、発生した事象が「新しい記事を投稿したら、公開されてしまった。」の場合、問題点は次のように記述します。

サイトリニューアル時の仕様では、新しい記事を投稿したら一度非公開として保存され、改めて「公開」にチェックを入れて更新するとはじめて公開されることになっていた。 その仕様に反して、新しい記事が投稿直後に公開されてしまう点が問題である。

4. 再現手順

バグを再現するための手順です。 バグ対応の中で技術者が真っ先にやることのひとつが「バグの再現」なので、これはとても重要な情報です。 バグを手元で再現すること、そして、バグを再現する手順を明確にすることで、技術者はバグとその原因を正しく把握できるようになります。

技術者のバグ対応の負担を軽減するため、「 どのような状況で、何をしたら、バグが発生したのか 」をわかりやすく伝えましょう。

いくつかポイントをあげます。

  • 再現手順のフォーマットは、シンプルな箇条書きが望ましいです。
  • ページを指す場合は、「○○なページ」というあいまいな説明は誤解のもとです。誤解の少ない URL を極力使うようにしましょう。
  • ページ内のフィールドやボタン等のウィジェットを指す場合は、できるかぎりラベルを正確に伝えましょう。
  • ことばでの説明が難しい場合や誤解を招く可能性がある場合は、画像や動画のキャプチャを撮影して共有しましょう。

よい例:

  1. 「編集者」ユーザとしてログインする
  2. 記事の新規作成ページを開く( https://example.com/admin/articles/article/add/
  3. 「タイトル」と「日付」を入力して、「保存して編集を続ける」ボタンをクリックする
  4. 「編集者」ユーザをログアウトする
  5. ログインしない状態のまま、作成された記事のページを開く( https://example.com/articles/[新しいID]
  6. 記事が表示されてしまう(←問題が発生)

悪い例:

記事のページを開いて、フォームに適当に入力して、保存した。記事をチェックすると、記事が公開されている。

箇条書きの方が断然読みやすくわかりやすいことがお分かりいただけるかと思います。

5. 発生環境

バグが発生した環境です。 技術者以外の方はよく「自分の手元で発生したバグは、別の場所でも必ず発生するもの」と考えがちですが、実際にはそんなことはありません。 多くのバグは、特定の環境の下で、特定の場所でのみ発生します。 特に、ページのレイアウトやスタイル等の見た目の問題は環境に大きく依存するので、できるだけ詳細に情報を伝えるようにしましょう。

ウェブサイトのバグの場合は、最低限以下の情報を伝えるようにするとバグ対応がスムーズです。

  • 使用 OS バージョン( Windows 10 / macOS / Android x.x / iOS x.x 等)
  • 使用端末( iPhone 8 / Google Pixel 2 等)
  • 使用ブラウザ( Chrome / Android ブラウザ 等)
  • 使用アカウント(ログインができるサイトの場合)

6. 期待する結果

バグが発生する状況で期待する結果です。 「本来はこうなることを期待しているのに、実際はこうなってしまう」と、期待と現実のギャップを示すことで、問題点を明確にすることができます。 問題点のところで十分に説明ができている場合はここは飛ばしてもよいでしょう。

オープンソースのソフトウェア(フレームワークや CMS )では、バグ報告のテンプレートにこの項目が含まれているものもよく見かけます。

7. その他

その他補足情報です。 上の項目のどれにもあてはまらないことで付け足すべき情報がもしあればあわせて共有します。 例えば、過去には発生していなかったバグが新しく発生するようになったのであれば、いつ頃からバグが発生したのかを正確に伝えてもらえると技術者は助かります。

...

以上、技術者がもらってうれしいバグ報告書のお話でした。

最後に、一覧をもう一度載せておきます。

  1. タイトル
  2. 発生した事象
  3. 問題点
  4. 再現手順
  5. 発生環境
  6. 期待する結果
  7. その他

「おおよそのテンプレートはわかったけれど、いざ書こうと思ってもうまく書けない」といったときには、技術者に過去の報告書をいくつか見せてもらったりしてください。 具体的でリアルな例を見ると、多くの方はすぐに効果的なバグ報告書を書けるようになります。

バグが絶対に生まれないソフトウェアやウェブサイトはこの世には存在しないので、ウェブ技術者と関わるのであれば、バグ対応の流れについて取り決めをしておくと断然スムーズですよ。

技術者とよりよい関係を築いてウェブプロジェクトを成功させたい方々のご参考になれば幸いです :)

参考