現役QAエンジニアが語る！不具合起票のヒ・ケ・ツ

こんにちは。現在所属している会社で、前半の3年をソフトウェアエンジニアとして、後半の3年をQAエンジニアとして過ごしているTMRです。
　
不具合チケットは、不具合を修正するソフトウェアエンジニアに対して、正確に内容を伝える必要があります。
不具合チケットの記載の仕方について、勉強したことや先輩から学んだことをまとめます。

■不具合チケットについて

不具合チケットは、最も関わる人間の多い開発文章であり、開発時のコミュニケーションの要と言える文章のひとつです。
理解しやすい不具合チケットは、チケットを読む人はもちろんのこと、自分の仕事の負担軽減にも繋がります（余計な問い合わせが減るので）。自分も周りもみんながハッピーになります。
本記事では、チケット全体感での記載ポイントとチケット内の項目ごとの具体的な記載ポイントを述べます。

■チケット全体でのポイント

不具合チケット全体で共通する記載ポイントです。
技術文章の書き方そのものですが、そのなかでも不具合チケットに直結するものです。

事実のみを記載し、意見は記載しない

自分の意見…例えば「～思われる」「～と考えられる」のような文言は禁句です。 あくまで発生した現象を記載するので、意見は不要です。
「事実のみ記載し、意見は記載しない」ということは難しいですが、「仕様書にXXと記載しているので不具合である」のように、ドキュメントベースな根拠があれば、おのずと事実のみ記載されていきます。

また、不具合チケットは不具合発生の事実を書く「開発文章」であり、相手を批判する場や意見を戦わせる場ではないです。他の事例で、不具合チケット上でQAが設計を煽ったばかりに論争になったという残念な事象もありました。

使用する用語は統一する

製品仕様書のような設計ドキュメントに記載されている用語に統一することは重要です。ソフトウェア開発理論のことばでいうなら「ユビキタス言語を用いましょう」です（社内やチーム内でも用語統一を推進できるとなお良いです）。
微妙な用語の違いで、チケットの関係者に意図が伝わらず、不具合の再現ができないという事例が実際にありました。

1文を短く記載する

1文には、ひとつの事柄・情報・手順を記載しましょう。2つ以上の情報は文を分割するのが良いと思います。
また日本語は英語と違って無限に文を連結できる言語ではありますが、主語と述語が離れすぎていると何を伝えたいかわからなくなります。読点が3個を超えだしたら文の分割を検討しましょう。ただ、1文が短すぎてもわかりづらくなります。目安として 1文は40～60字程度でまとめましょう。

二重否定を使用しない

二重否定の表現は肯定文に修正しましょう。
二重否定は曖昧になりやすく、読み手に誤解を招きやすいためです。

1チケットに報告する不具合は１つ

基本的に、異なるモジュールそれぞれで不具合が発生している場合はチケットを分割します（さじ加減は検査リーダーの采配によります）。例えば「更新ボタンを連打すると、サイト全体がテキストが文字化けし、注文ボタンがdisableのママになる」ような現象が発生した場合、文字化け（UI部分）と注文ボタンがdisable（機能部分）でチケットを分けると良いと思います。
1つのチケットに複数現象を記載しても、どちらかが見落とされて不具合修正されないケースが多いためです。

■チケットの具体的内容

各不具合管理システムで記載する内容が異なるかもしれませんが、おおむね不具合チケットで記載が義務付けられている各種項目それぞれで記載するべきポイントを記載します。

タイトル

不具合の内容や重要度を判断するための入り口です。
タイトルで不具合のポイントがズレていると、適切に不具合修正してもらえない場合があります。
不具合とわかる、的確なタイトルをつけましょう。

タイトルの基本構文
バリエーションはありますが、基本的には下記の構文でタイトルを構成します。最大50文字程度が目安ですが、短く記載できるならできるだけ短く記載します。

「[When/Where（状態）]→[What（条件）]→[How（手順）]→[be（期待値に反する結果）]」

• When/Where（状態）：「～のとき」「〜で」「〜の場合」
  不具合の再現に必要な検査機材などの状態を書きます。
• What（条件）：「なにを～」
  不具合の再現に必要な設定などの条件を記載します。
• How（手順）：「～すると」
  不具合再現の決め手となる操作を記載します。
• be（期待値に反する結果）：「～になる」
  実際に発生した、期待結果とは異なる現象を記載します。

例）
　NG：ボタンをクリックするとフリーズする 
　OK：「ポイントを使う」チェックボックスがTrueのとき、注文ボタンをクリックすると注文画面がフリーズする

前提条件

不具合を発生させるために必要な静的な条件や状態を列挙します。
基本的に箇条書きで記載します。「～しておく」の表現はせず、体言止めや「～すること」で良いです。

書くべきこと

• 不具合に関わる検査機材の設定
• PCやスマートデバイスが必要なら、検査で使用したOSのバージョン
• インストール済みであるべきソフトウェアやアプリケーション
• オプション品があるならその装着の有無
• 画像ファイルのような入力ファイルの情報

書かなくて良いこと

• 「PCが電源ONである」といった当たり前のこと
• 手順（手順の項目で記載する）

手順

チケットを読んだ人が迷わずに現象を再現させるための手順を記載します。
「まぁわかるだろー」と省略しがちですが、手順を省略されると読む人が途端にわからなくなることが多いです。読む人の前提知識や背景知識がまったくない前提で記載しましょう。

必要な条件や手順を省略せずに書く
必要な条件や手順を省略せず、1ステップごとに記載します。
目安として、前提知識不要かつチケットを読む人（イメージとして新人）が、記載されている前提と手順を読んだことだけで理解・再現できるくらいに細かく記載します。省略するか詳細に書くか迷ったならば、詳細に書くほうに倒すほうが良い場合が多いです。

例）
 　NG：ボタンをクリックする 
 　OK：注文画面で注文確定ボタンをクリックする 

手順の文章の中に動作は一つ
手順の一文に、動作を一つのみ記載します。
何個も動作があると、再現するひとが手順を抜いてしまう可能性があります。

例）
　NG：配送先に東京都を選択し、ポイントを使うを選択し、ボタンをクリックする 
　OK：① 配送先コンボボックスで「東京都」を選択する 
　　　  ② ポイントを使うコンボボックスをEnableにする 
　　　  ③ 注文ボタンをクリックする

数値を用いるなどして具体的に記載する
「いつ（タイミング）」「何を」「どうする」を具体的に書きます。数値が記載されているとより良いです。

例）数値を用いた具体的な手順
　　※操作にタイミングがある場合。タイミングが不要な場合はNGに書いてある記載で構わないです
　 NG：ブラウザバックしたあと、少したった後にボタンをクリックする 
　 OK：ブラウザバックしたら、約5秒後にボタンをクリックする

例）具体的なタイミングを記載した手順
　　※操作にタイミングがある場合。タイミングが不要な場合はNGに書いてある記載で構わないです
 　NG：確認ダイアログでOKボタンをクリックする 
 　OK：確認ダイアログ内に「Are you OK？」が表示されたら、OKボタンをクリックする

実施対象を明記する
検査機材やPCなど、手順が複数のデバイスやアプリケーションにまたがっているときは、手順の中に検査機材やPCを明記しましょう。いろんなデバイスやアプリケーションがあると、どの検査機材のUIやアプリケーションで手順を実行するべきなのか混乱するためです。
また画面名称やUI名称も記載してあるとより良いです。

例）PCとスマホの両方で操作が必要な場合
　NG：① OKボタンをクリックする
　　  　② 表示されたメッセージを確認する
　OK：① スマホに表示された確認ダイアログでOKボタンをクリックする
　  　　② PCのWebブラウザに表示されたメッセージを確認する

結果・期待結果

手順の最後に対して、どうなったかという「現象としての結果」を記載します。冗長のため、結果や期待結果には手順を繰り返し書かないようにします。
また、結果と手順をできるだけ対比させて記載しましょう （対比すると、何が悪くて何が正しいのか理解しやすいです）。ただし対比不要な場合もあります。無理に対比しなくて良いときは、対比で記載しなくて問題ありません。

例） 
 　結果　　　： 注文画面がフリーズし、注文開始しない 
 　期待結果　： 注文画面がフリーズせず、注文開始する

現象発生時の証拠画像
現象発生時のスクリーンショット・画像・動画を撮影できる場合、撮影したそのファイルをチケットに添付して参照案内すると良いです。文字だけでは、不具合のイメージが伝わらない場合がありますが、画像などあると現象が伝わりやすくなります。
画像を不具合の発生箇所を赤い丸などで囲い、不具合発生箇所を判別しやすくするとなお良いです。
例外発生などでエラーコードが画面に表示されている場合、その番号とエラーメッセージが映った写真も添付すると良いです。解析に重要な手がかりとなるエラーコードの情報が正確に設計に伝わるためです。

結果補足

手順や結果に書ききれない補足情報はすべて結果補足に記載します。

書くと良いこと

• 根拠となる仕様書の記載
• 同条件である検査機材・PCでの結果
• 他のPCや機体での結果
• 他の状態や条件、設定で確認した結果
• 過去の類似機種の動作
• 不具合チケットを起票した背景

添付するべきこと

• ログファイル
• 設定ファイル
• 複雑なテスト条件で他にも試した場合、試した結果をまとめたファイル

テスト環境

検査機材の情報を細かく記載します。
ソフトウェアエンジニアが解析に用いる重要な情報ですので、記載できることは記載しましょう。記載内容は事前にテンプレート化しておくと良いです。

書くべきこと

• 評価日や評価時間
  ログの解析で使用することがあるため、不具合の発生時刻を記載します。
  検査機材の時刻設定を事前に正確に合わせておきましょう。
  アプリ系検査の場合、PCや検査デバイスに表示されている時刻や標準時刻を設定している地域も併記しましょう （OSで設定している地域が異なる場合）。

• 検査対象ソフトウェアのバージョン・リビジョン・ビルド番号
  これは必ず記載するべきです。
  特定のバージョン・リビジョン・ビルド番号でのみ発生する現象の特定に有意義な情報になります。

• 評価機材
  機材固有の問題や機材の設定による不具合があるときの分析に使用することがあります。

• 機材のシリアルナンバー
  機材固有の不具合の場合に解析に使う場合があります。
  アプリ系検査では不要だと思います。

• 接続方法
  USB/有線LAN/無線LANのような、検査で使用中の方法を記載します。
  特定接続でのみ発生する現象の解析に使う場合があるためです。

• オプション有無
  検査機材に取り付けできるオプション品がある場合、その有無を記載します。
  オプション装着有無によって発生する/しない現象があります。

• PC・スマートデバイス
  検査で使用したPCやスマートデバイスのハード（CPU・メモリ・検査機材との接続経路）やソフト（OS・使用アプリ・言語と地域）の情報を記載します。
  PCやスマートデバイスの特定条件固有の不具合があるときの分析に使用することがあります。

■まとめ：みんなハッピーになるチケット5ヶ条

1. 事実のみ記載する
2. 1文に情報は1つにし、短くする
3. 手順や条件を省略せずに記載する
4. 現象発生時の画像やログファイルを添付する
5. 環境情報は細かく記載する

■最後に

今までの仕事や先輩の指導、勉強で学んできた不具合チケットの書き方をまとめました。
「ココをこうしたらもっと良い」などの意見があれば、ぜひいただけると嬉しいです。もっと良い文章を書きたいのでとても歓迎です。

■参考資料

• 『理科系の作文技術（リフロー版）』中公新書　木下是雄 著
• 『ソフトウェアテスト 293の法則』日経BP社 Cem Laner・James Bach・Bret Pettichord著
• 20180421 Issueの書き方と伝えかた勉強会
• なんじゃこりゃ！このバグ票なんか腹たつ ～バグ票の失敗から学ぶソフトウェア開発のための幸せなコミュニケーション術～