不具合報告に添えるスクリーンショットの作り方

エンジニアが実際に必要としているものは、たいてい切り落とされた側にあります。何を写すか、何を隠すか、再現手順に番号を振る方法、そして拡大しすぎた画像の何が問題か。

不具合の報告に添えられた画像を見て、担当者が最初にすることは、たいてい「これはどの画面ですか」と聞き返すことです。報告した側は問題の箇所を丁寧に拡大して切り抜いていて、その丁寧さがそのまま、必要な情報を落としています。往復が一回増えて、修正が翌日に回る。

この記事は、その往復を減らすための画像の作り方です。何を写すか、何を隠すか、そして手順をどう示すか。順に書きます。技術的な難しさはひとつもありませんが、優先順位が日常のスクショとは逆になります。

エンジニアが見ているもの

受け取る側は、その画像から問題そのものを見ようとしているのではありません。問題が起きた状況を再現しようとしています。だから必要なのは、症状よりも文脈です。

• ウィンドウ全体、または画面全体。どの画面のどの状態か。切り抜かれていると、まずそこから聞き直しになります。
• エラーの文言。全文が読めること。要約して書き写さないでください。「エラーが出ました」と実際の文言では、検索できる情報量が違います。
• 画面の識別子。ブラウザなら URL、アプリなら画面の名前やタブの位置。
• 時刻。ステータスバーの時計で足ります。サーバー側のログと突き合わせるとき、時刻がわかっているかどうかで作業量が変わります。
• バージョンやビルドの表示。設定画面の隅に出ているものを、別の一枚として添えるだけで十分です。
• 直前の状態。押す前の画面と押した後の画面を二枚並べると、言葉での説明がほぼ要らなくなります。
• 一度きりか、毎回起きるか。これは画像ではなく本文の話ですが、画像の枚数がその答えになっていることがあります。

拡大して切り抜いた画像が失うもの

ボタンひとつを大きく切り出した画像は、そのボタンがどこにあるかを教えてくれません。同じ形のボタンが画面に三つあれば、受け取った側は三通りの再現を試すことになります。

もっと厄介なのは、切り落とした部分に原因があった場合です。上部の警告バー、別のタブに残っていた古い画面、右側の何かが読み込まれていない領域。報告した側は問題ではないと判断して切り、その判断が間違っていると、画像は問題を隠す働きをします。

だから順序は逆です。まず画面全体を撮って、そのうえで問題の箇所を四角で囲うか矢印で指す。切り抜きは、囲ってもまだ何を見ているかわからない場合の追加の一枚として使ってください。一枚に詰め込むより、全体の一枚と拡大の一枚のほうが速い。

共有のチケットに載せる前に隠すもの

ここは日常のスクショと事情が違います。不具合の報告は共有のトラッカーに入り、閲覧範囲が広く、検索でき、そして何年も残ります。

• 本番のデータ。顧客の氏名、メールアドレス、電話番号、住所、注文の内容。再現に必要ないなら全部隠してください。
• 認証に関わるもの。画面に出ているトークン、セッションの識別子、URL に埋め込まれた鍵、開発者ツールに表示された値。
• 他の人の情報。管理画面の一覧を撮ると、問題と無関係な行が全部一緒に写ります。
• 自分の身元に関わるもの。社員証、内線番号、個人の連絡先。
• 関係のない社内システム。ブラウザのタブに並んだ他のシステムの名前は、報告に必要ありません。
• 画面の外。ウィンドウの後ろに見えているデスクトップ、通知、別のアプリ。ウィンドウ単位で撮れば、この多くは最初から入りません。

再現に必要な識別子だけは残してください。注文番号や利用者の ID を全部隠すと、担当者はその事象を探せなくなります。隠すのは中身で、残すのは参照です。判断に迷うなら、隠したうえで「必要なら別途お伝えします」と本文に書けば、往復は一回で済みます。

再現手順に番号を振る

文章で書いた手順と、画像に振った番号が一致していると、受け取る側は読む順番を考えなくて済みます。本文の 3 と画像の 3 が同じものを指している、というだけで、説明の量は目に見えて減ります。

1. 手順を先に文章で書く。画像はそれに合わせて作る。逆順にすると、画像に写っている都合で手順が歪みます。
2. 画面が切り替わる境目で画像を分ける。ひとつの画像の中に押す前と押した後を同居させない。
3. ひとつの画面の中の複数の操作にだけ、番号を使う。順序のない指示に番号を振ると、順序があると読まれます。
4. 番号は対象に重ねず、すぐ横の余白側に置く。全部の番号を同じ側に揃えると、視線が迷いません。
5. 最後に、本文の番号と画像の番号を突き合わせて読み直す。ここで一致していない報告は本当によくあります。

途中の手順が要らなくなって番号を消したとき、1 と 3 と 4 が残っている画像は、読み手に「2 を見落とした」と思わせます。手順書と同じで、これは誤りとして読まれます。Marka の番号マーカーは削除したときに残りを自動で振り直します。基準は置いた順で、どのマーカーが上に重なっているかは関係ありません。

道具の話

この用途で必要なのは、速いことと、隠せることの二つです。Marka の Mac 版なら、範囲をクリップボードへ撮って貼り付け、m を押して本番データをなぞって隠し、r で問題の箇所を囲い、n で手順に番号を置き、クリップボードへコピーしてチケットの入力欄に貼る。ツールの切り替えは修飾キーなしの一文字なので、ポインタはキャンバスから離れません。

Mac 版にはもうひとつ、Pro の「機微情報を探す」があります。開いている画像を Apple の Vision フレームワークで調べ、電話番号、メールアドレス、カード番号らしき数字列、顔、URL を候補として並べます。管理画面の一覧のように隠す対象が多い画像では、見落としを拾うのに向いています。ただし提案するだけで、チェックしたものだけが隠され、そして必ず取りこぼします。自分で一周見たあとの二周目として使ってください。この機能は iPhone と iPad にはありません。

ひとつ注意があります。Marka は作業中の一枚だけを持っていて、閉じたあとに控えを残しません。一件の報告に画像を四枚添えるなら、一枚ずつ仕上げて、その都度チケットに貼るか書き出してください。

よくある質問

関連記事

• スクリーンショットに手順の番号を振る
• Mac でスクリーンショットに注釈を入れる
• スクリーンショットから個人情報を隠す

記事一覧