Dyno

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

2018/05/29

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

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

想定読者

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

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

前提

前提は次のとおりです。

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

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

技術者がもらってうれしいバグ報告書がどんなものかを考える前に、ウェブ技術者がどのようにしてバグに対応するのかを見ておきましょう。 技術者がバグに対応するときの全体の流れが把握できていれば、技術者がどんなことを望みどんなことを嫌うか想像することができます。

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

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

外から目に見えるのはこのうちのステップ 8 と 9 だけですが、技術者はその他にも多くのステップを踏んでバグに対応します。 バグ対応フローが標準化できていない場合やバグの原因がひと目でわかるシンプルな場合をのぞき、ほとんどのケースにおいては、ウェブ技術者はおおよそこの流れに沿って日々バグ対応を行っています。

ポイントは、「問題が解決できたらそれでいい」という考えではなく、「 バグの原因を正しく把握し、考えうる中でベストな方法を選んで、深刻な副作用が出ないことを確認した上で、再発を防いだ上でバグを解決するべきだ 」という考えのもとにバグ対応を行っているという点です。 この一連の作業にはどんなに短くても 30 分〜 1 時間という一定の時間がかかります。

傍から目に見える作業がたとえささいなものであったとしても、そこに至るまでには少なくない知識と努力が割かれているということを、技術者と接する人たちは理解しておかなくてはなりません。

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

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

上述のバグ対応の流れを理解した上で、バグを報告する側の人が持つべき姿勢とはどのようなものでしょうか。 それは 技術者といっしょにバグを解決しようとする姿勢 です。

対象となるバグの原因が技術者にあるとはかぎりません。 バグというのは「システムのふるまいにおける、期待と現実のギャップ」なので、さまざまな要因がバグの原因になりえます。 また、たとえバグの原因が技術者にあったとしても、バグによって実際に困っていてその解決を望むのはバグ報告を行う側の人たちです。

ですので、次のような態度は効率的なバグ対応を阻害し、結果としてバグ報告をした人の不利益に繋がります。

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

「バグが適切な形でできるだけ早く解決される」という共通のゴールに向けて積極的に対応に参加することが、バグ解決までにかかるコストを最小に時間を最短にするいちばんの秘訣です。

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

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

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

具体的・正確に伝える: バグ報告は具体的で正確であることが望ましいです。 「どのページでどんなことをしたら、どんなことが起こったのか」を正確・明確に伝えましょう。

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

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

事実と推測を分ける: 客観的な事実とバグ報告者や作業者の推測は明確に分けることが望ましいです。 バグ報告書に書かれている情報が、実際に発生した事象についてのものなのか、報告者の頭の中の推測なのかがわからないと、技術者が事実を誤認する可能性があります。

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

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

業界標準の絶対的なフォーマットがあるわけではなく、適切なテンプレートはプロジェクトやチームによってまちまちです。 ただ、バグ報告において技術者が知りたいこと・求めることはある程度共通しているので、このテンプレートではそれらのポイントを押さえています。

  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. その他

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

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

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

参考