見出し画像

伝わりやすい不具合報告の書き方 #Zaim

はじめに

こんにちは。Zaim で iOS エンジニアをしている @akatsuki174 です。

バグ報告ってどんな情報をどこまで渡せばいいのかの加減がうまくつかめず、意外と難しいですよね。会話の往復が増えると、タイムロスしたり、ちょっと険悪なムードになりかねません。

そこで、いちエンジニアの立場から「こんな風に言ってもらえると嬉しいよ!」という話をしようかと思います。ただ、あくまでもこれは一例です。プラットフォーム、会社などによっては別のことを伝えた方がいい場面もあるかと思うので、「こんな記事あったんだけれど、うちではどんなコミュニケーションが最適なんだろう?」と社内に問いかけてみてください

絶対に伝えてほしいこと

発生環境

具体的に言うと OS、OS のバージョン、ブラウザの種類、ブラウザのバージョン、スマホの機種、アプリのバージョン、実行環境(本番/ステージング etc)などがこれに当たります。「iOS 11.1 では発生しないけれど、iOS 12.0 では発生する」など、環境の違いによって該当の現象が起きたり起きなかったりすることがあります。現象を確認する上で前提となる情報なので、忘れずに伝えてほしいです。

例:iOS 12.0, iPhone X, Zaim v7.1.0 本番環境で発生

再現手順

調査をする上で「再現できるかどうか」は大きなポイントになります。再現さえできれば、デバッグで具体的な処理の流れを確認して「本来この処理を実行したら、この値が来ているはずだったのに、来てないぞ?」「その条件だった時のことが、考慮されていなかった!」などの欠陥を発見するスピードが早くなります。

ということで、どのような動作をしたら問題となる現象に遭遇したのかを伝えてほしいです。

例:
1. 履歴タブをタップ
2. 任意の履歴をタップ
3. 「よく使う」をタップ ← この時に発生

ちなみに画面やボタンの名称がはっきり定まってないと「つまりそれってどこのこと??」となりかねないので、社内であらかじめ名称の認識を統一しておくことが重要です。

がどうおかしいのか

例えば単に「分析グラフがおかしい」と言われただけでは、グラフの UI が崩れているのか、グラフの値が間違っているのか分かりません。「こうなると思っていたんだけれど、実際はこうなっていた」という、期待値との乖離状況を教えてください

例:
1. 記録タブの「レシート」から新規明細を作成
2. 記録完了画面で「つづけて記録」をタップ

この時「レシート」画面に戻ると思ったら「手入力」画面に戻ってしまった

できれば伝えてほしいこと

発生条件

可能であれば、どんな時にその現象が発生するのかを教えてほしいです。以前ゲームアプリを作っている人との会話で「あるデッキが揃った時だけ発生する不具合の指摘があって…」という話がありました(つらそう…)。

特定の動作で必ずしも発生しない現象は、再現性を確保するのに苦労します。「発生条件が不明」という場合でも、「こんなユーザーで発生したよ」という情報が分かると、どんなデバッグをしたらいいかを考える材料になるので、できれば教えてください。

例:アプリを起動して、分析タブをタップしたらクラッシュした。アプリを再度立ち上げてもう一回見てみたら正常に動作した。以降、クラッシュは再現していない。

ちなみに検証に協力してくれる場合は、次の点に気をつけてみてください。

・もう一度、同じ動作をした時に再現するか
・別のアカウントでも再現するか
・別の環境(OS など)でも再現するか
・問題の箇所まで複数のルートがある場合、他のルートでも再現するか

あると嬉しいもの

スクリーンショット

UI が崩れている場合など、言葉で表しづらいものはスクリーンショットをもらえると意思疎通が楽です。それでも分かりづらい場合は、そのスクリーンショットに「←この部分」など箇所の指定をすると神です。あなたは神になれます。

動画

再現手順をスムーズに伝えられますし、現象が正確に伝わります。 Mac だと QuickTime Player などで簡単に動画を撮影できます。

おまけ:それは「バグ」なのか?

何か自分の想定と反することが発生した時「バグ」と言ってしまいがちですが、それは本当に「バグ」なのでしょうか?約 1 年前、こんな記事が流行りました。

「バグ」という言葉はマイナスワードですが、そのマイナスが実は虚構であったり、そのエンジニアの責任ではない可能性もあります。エンジニアは「バグ」という言葉に非常に敏感です(たぶん)。なので「バグ」という主観的な表現はとりあえず置いておいて、まずは「こんな現象が発生しました!」という事実を報告してもらえるとありがたいです。

最後に

今回は「どうやったらエンジニアにとって分かりやすいバグ報告になるか」という観点で記事を書きました。上述のポイントを抑えていれば、コミュニケーションコストが減って改善サイクルが早く回せるはずです。

ぜひ、良きバグ報告でチーム全体の効率と品質を上げていきましょう。

P.S.

壁┃_・)ジー


共感した、他の人にも知ってもらいたい等々思ったら、ぜひTwitterなどでシェアしてください。