スクリーンショットドキュメント：ソフトウェアチームのためのベストプラクティス

うまく作れば、どのボタンをクリックすべきか、そこに到達したとき画面がどう見えるはずかを正確に示せます。作り方を誤れば、製品と一致しなくなった画像の寄せ集めへと劣化していきます。

このガイドでは、ドキュメント用スクリーンショットをどのようにキャプチャし、注釈を付け、整理し、維持すれば、次のリリース後も古びることなく正確さを保てるのかを説明します。難しいのはスクリーンショットを撮ることではなく、製品の変化に合わせて正しい状態を保ち続けることです。この維持の問題は、不十分なプロセスドキュメントが招く隠れたコストの背景にあるものと同じです。

解決策は、キャプチャの方法を標準化し、装飾ではなく意味のために注釈を付け、すべての画像をレビューサイクルに結び付けて、UIの変更を再キャプチャのトリガーとして扱うことです。手作業での再キャプチャを減らしたいチームは、入力不要のキャプチャファースト型ワークフロードキュメントのガイドをご覧ください。

スクリーンショットドキュメントとは何ですか？

スクリーンショットドキュメントとは、ソフトウェアのインターフェースをキャプチャした画像を使い、各ステップで何をすべきか、何が表示されるはずかをユーザーに示す手法です。文章による手順と、読み手が実際に見ている画面そのものの画像を組み合わせることで、言葉と現実のあいだにずれが生じないようにします。

優れたドキュメント用スクリーンショットは装飾ではありません。それは証拠です。次の操作に進む前に、読み手が正しい場所にいることを確認させてくれます。この確認の有無が、自信を持ってガイドをたどれるユーザーと、クリックのたびに迷うユーザーを分けます。

問題は、スクリーンショットは撮るのは簡単でも、正しい状態に保ち続けるのは高くつくという点です。土台となるUIが変わった瞬間、その画面に紐づいたスクリーンショットは誤りになります。そして誤ったスクリーンショットは、何もないよりたちが悪いのです。すでに存在しないものを信じるよう、読み手に告げてしまうからです。

ソフトウェアドキュメントにおいてスクリーンショットドキュメントが重要な理由

文章だけでは、読み手は書かれた言葉を自分の画面に置き換える作業を強いられます。スクリーンショットはこの変換の手間を取り除きます。読み手が置かれているべき状態をそのまま示すため、サポートへの問い合わせや作業の放棄につながる曖昧さが減ります。

よくある管理タスクを考えてみましょう。顧客の多要素認証（MFA）をリセットする作業です。文章で「セキュリティ設定を開き、第2要素を無効にする」と書いた場合、読み手がセキュリティ設定の場所を知っていて、そのトグルの名称も分かっていることが前提になります。同じ一文に、実際の管理コンソールのスクリーンショットと、該当するトグルを囲むコールアウトを添えれば、曖昧さは大きく狭まります。読み手は推測をやめ、手を動かし始めます。

この価値は本物ですが、条件付きです。スクリーンショットが役に立つのは、それが正確であるあいだだけです。誤りになった瞬間、害をもたらします。だからこそスクリーンショットドキュメントは、装飾の予算ではなく規律なのです。

スクリーンショットドキュメントの構成要素

スクリーンショットドキュメントは画像だけではありません。文書化された各ステップは決まった形を持つ小さな単位であり、その一部を欠くところからガイドは崩れ始めます。

文書化されたステップの構造

• 手順の文章：平易な言葉で書かれた操作内容。何を探せばよいかが分かるよう、画像より前に置きます。
• スクリーンショット：手順が示す状態そのものを写した画面。関連する範囲にトリミングします。
• 注釈：そのステップで重要な唯一の要素に注意を向けさせる、コールアウト、矢印、ハイライト。
• 代替テキスト：スクリーンリーダーの利用者や、画像が読み込まれなかった読み手のための説明文。
• バージョン情報：最終キャプチャ日やリリースタグ。画像が最新かどうかをオーナーが一目で判断できます。

手順のない画像は謎かけです。画像のない手順は、そもそも解決しようとしていた元の問題そのものです。両方が必要であり、加えて後から鮮度を確認できるようにする情報も欠かせません。

スクリーンショットと画面録画の比較

静的なスクリーンショットと画面録画は重なり合う課題を解決します。どちらを選ぶかは、どちらが見栄えがするかではなく、読み手が何をする必要があるかによって決まります。

本当に動きが必要な一部のステップには録画を使い、それ以外はすべてスクリーンショットで対応しましょう。これらを組み合わせて完全な手順書にまとめる方法については、分かりやすい作業手順書の書き方のガイドをご覧ください。

ドキュメント用スクリーンショットのベストプラクティス

優れたドキュメント用スクリーンショットは、毎回同じように適用される基準から生まれます。以下の3つの実践は、キャプチャの品質、フレーミング、そしてすべてが劣化するのを防ぐ維持の規律をカバーします。

高解像度で一貫性のあるスクリーンショットを撮る

スクリーンショットに一貫性がないと、情報が正しくても雑な印象を与えます。ある画像は精細なのに、次の画像はズーム倍率の違うぼやけた半端なウィンドウ、という状態では、読み手はその継ぎ目に気づき、ガイドへの信頼を下げます。最初の1枚を撮る前にキャプチャ設定を固定し、ドキュメント全体で維持してください。

固定すべきキャプチャ基準

1. 解像度とスケール：デバイスのスケーリングを固定し、一貫した高解像度でキャプチャします。埋め込んでリサイズしても文字が鮮明に保たれます。
2. ビューポートのサイズ：すべてのキャプチャで同じブラウザーまたはウィンドウサイズを使い、要素が毎回同じ位置に来るようにします。
3. テーマと状態：ライトモードかダークモードかを決めて統一します。通知バッジや中途半端なデータで画面が散らからないよう、きれいなデモアカウントを使いましょう。
4. マスキングの基準：顧客名、メールアドレス、口座番号をどのようにぼかす、または隠すのかをあらかじめ決め、既定でマスキングを適用して、実データが公開ガイドに漏れないようにします。
5. ズーム倍率：拡大した細部を意図的に見せる場合を除き、アプリケーションのズームは100パーセントに保ちます。

重要なのは一貫性です。1つのガイドの中の画像を、3人の別々の担当者が撮ったと読み手に気づかれてはいけません。

適切な範囲にトリミングし、文脈を整える

最もよくあるフレーミングの失敗は、読み手に必要なのは1つのパネルだけなのに画面全体をキャプチャしてしまうことです。デスクトップ全体のスクリーンショットは、目的の操作対象を読み手に探させることになり、画像を見せる意味そのものを損ないます。

自分がどこにいるかを読み手が把握できる最小限の範囲にトリミングしましょう。多くの場合、それは操作中のパネルに加えて、ページタイトル、タブのラベル、セクション見出しといった手がかりが1つある状態です。それ以外は削ります。1つのトグルについてのステップなら、ナビゲーションのサイドバー全体が注意を奪う必要はありません。

判断は簡単です。画像の一部を取り除いても、読み手が操作対象を見つける力が損なわれないなら、取り除いてください。フレーミングは足し算ではなく引き算です。

スクリーンショットを最新に保つ

ほとんどのスクリーンショットドキュメントは、ここで静かに死んでいきます。設定ページのリニューアルが公開され、旧レイアウトに紐づいたすべてのスクリーンショットが誤りになります。しかしガイドの中でそれを知らせるものは何もありません。画像は変わらず表示され、ただ、もはや存在しない製品を説明し続けます。

解決策は、誰かが気づいてくれることを期待するのではなく、UIの変更を陳腐化チェックのトリガーとして扱うことです。維持の規律をプロセスに組み込みましょう。

機能する再キャプチャの規律

• オーナーを割り当てる：すべてのガイドに、スクリーンショットに責任を持つ担当者を明記します。オーナーのいない画像は劣化します。劣化が誰の仕事でもないからです。
• レビューの頻度：最低でも四半期ごとの定期的な鮮度チェックに加え、該当機能のリニューアルが公開されたときのレビューを設定します。
• キャプチャ日：各画像に最終キャプチャ日またはリリースバージョンを保存し、ガイド全体を開き直さなくても古い素材を見つけられるようにします。
• リリースノート：ドキュメントのレビューを製品のリリースプロセスに組み込み、UIの変更が影響を受けるガイドを浮かび上がらせるようにします。

繰り返し発生するコストはスクリーンショットそのものではありません。スクリーンショットを正しい状態に保ち続けることです。古い画像が100枚あるガイドは、新しい画像が30枚のガイドより劣ります。古い画像は、ガイド全体を信用しないよう読み手に教えてしまうからです。手作業で撮り直すのではなく、インターフェースの変更に合わせてガイドを再生成する方法については、各回の作業をやり直さずに繰り返し作業を文書化する方法をご覧ください。

ユーザーガイド向けのスクリーンショットへの注釈

注釈のないスクリーンショットは、読み手にすべてを見せます。注釈のあるスクリーンショットは、重要な1点だけを見せます。注釈こそ、ドキュメント用スクリーンショットがその価値を証明する場所であり、同時に善意が視覚的なノイズに変わる場所でもあります。

注釈のツールと手法

うまく注釈を付けるのに専用ソフトウェアは必要ありません。ただし専用ツールは一貫性を保つ助けになります。重要なのはエディターの銘柄ではなく、繰り返し適用できる手法です。

ツールは、OS標準のマークアップや軽量なキャプチャアプリから、チーム全体で注釈スタイルを統一できる専用のドキュメントプラットフォームまで幅があります。自社の環境に合うものを選んでください。重要なのは、すべての執筆者が同じ注釈の語彙を使うことです。同じ線の太さの矢印、同じコールアウトの色、同じフォント。執筆者ごとに注釈スタイルがぶれると、ガイドは委員会が寄せ集めたように見え、その不統一は不注意として読み取られます。選択肢を比較検討している場合は、プロセスドキュメントソフトウェアの比較でトレードオフを解説しています。

小さく固定された注釈キットを定め、それを守りましょう。ハイライトの色は1つ、矢印のスタイルは1つ、連番バッジのスタイルは1つ。制約のあるキットのほうが適用しやすく、マークアップの選択肢が野放しの状態よりはるかに一貫性を保ちやすくなります。

コールアウト、矢印、ハイライトを効果的に使う

注釈の目的は装飾ではなく誘導です。追加するすべての印は読み手の注意を奪い合うため、一つひとつがその場所を勝ち取らなければなりません。

ログインと権限の画面を例に考えます。悪い例は、ユーザー名の欄を四角で囲み、パスワード欄に矢印を引き、「ログイン状態を保持する」のチェックボックスをハイライトし、送信ボタンを丸で囲むことです。画面全体がマークアップで覆われ、何も際立ちません。良い例は、そのステップが対象とする唯一のコントロールをコールアウトで1つだけ囲み、それ以外はきれいなまま残すことです。読み手の視線は、狙ったとおりの場所に向かいます。

画像をすっきり保つ注釈のルール

• 1画像につき焦点は1つ：そのステップが依存する唯一の要素をハイライトします。3つのコールアウトが必要なステップは、おそらく2つのステップです。
• 誘導する、覆い尽くさない：矢印は手順から対象へと向けるものです。それを補強する2本目の矢印は必要ありません。
• 意味のためのコントラスト：UIに対して目立ちながら、すべての画像で一貫した色を使います。赤は本当の警告のために取っておき、通常のハイライトには使いません。
• 注釈と同時にマスキングする：同じ作業の中で機微なデータを隠し、公開されるスクリーンショットが実在の顧客名やトークンを漏らさないようにします。

すべてをハイライトした注釈付きスクリーンショットは、何もハイライトしていないのと同じです。抑制こそが技術です。

注釈付きスクリーンショットのアクセシビリティと代替テキスト

視覚だけで伝えるスクリーンショットは、スクリーンリーダーを使う読み手を排除し、画像が読み込まれなかった人を置き去りにします。代替テキストはその両方に対応します。WCAG 2.1 達成基準 1.1.1においても、情報を伝える非テキストコンテンツには代替テキストが求められています。

代替テキストは、ピクセルではなく意味のある内容と操作を説明するように書きます。「スクリーンショット」ではスクリーンリーダーの利用者に何も伝わりません。「管理コンソールのセキュリティタブ。MFAリセットボタンがハイライトされている」と書けば、目の見える読み手が見ているものが伝わります。画像に関するW3C WAIのガイダンスでは、見た目ではなく画像の目的を伝える機能的な代替テキストの書き方が説明されています。

注釈付きスクリーンショットでは、注釈の意図も説明しましょう。特定のコントロールがハイライトされていることを記述するのです。そのハイライトは、目の見える読み手が受け取っている情報であり、スクリーンリーダーの利用者はそれを取りこぼしてしまうからです。アクセシブルなドキュメントは、単なるコンプライアンス要件ではありません。分かりやすい文章と同じ思いやりであり、より多くの読み手がガイドをたどれるようにするものです。

スクリーンショットドキュメントの整理と管理

キャプチャと注釈があれば良いスクリーンショットは手に入ります。整理は、それを見つけ、更新し、数か月後に一から撮り直さずに再利用できるようにするためのものです。フォルダーやインライン画像として散在するスクリーンショットは維持が難しく、維持されない画像こそ古びていきます。

ファイル名とフォルダー構成

「Screenshot 2024-06-14 at 3.42.11 PM.png」という名前の画像は追跡できません。何が写っているのか、どのガイドのものか、最新かどうかを誰も判断できないため、更新されることのないまま静かに朽ちていきます。

意味を含む命名規則を採用し、それをフォルダー構成にも反映させましょう。

追跡可能性を保つ命名規則

• 製品領域を先頭に：機能名やモジュール名から始めます（例：billing-settings-invoice-download-01.png）。関連する画像がまとまって並びます。
• 連番：ガイド内でスクリーンショットに番号を付け、ファイル一覧で順序が分かるようにします。
• リリースまたは日付のタグ：バージョンやキャプチャ日を末尾に付け、古い素材が一目で分かるようにします。
• フォルダー構造を対応させる：ドキュメントの構成に合わせて、製品領域とガイドごとに画像をまとめます。ある機能を更新するオーナーが、影響を受けるすべての画像を1か所で見つけられます。

命名規則は形式主義ではありません。それが再キャプチャの規律を成り立たせます。見つけられない画像は更新できないからです。同じ理屈は、素材を見つけやすく保つ、よく構成された社内ナレッジベースにも当てはまります。

バージョン管理と再利用可能な素材

同じログイン画面、同じナビゲーションバー、同じ設定パネルが、多くのガイドに登場します。その共通要素が変わったとき、すべてのガイドを探し回って1枚ずつ直したくはないはずです。

共通のスクリーンショットは、単一の出所を持つ再利用可能な素材として扱いましょう。正となる画像を1度だけ保存し、必要な場所すべてから参照し、UIが変わったら1か所で更新します。そうすればリニューアルは、宝探しではなく、伝播する1回の編集になります。

各素材にバージョン履歴を残し、いつ、どのリリースに対して更新されたのかを確認できるようにしておけば、陳腐化チェックは当てずっぽうから調べ物へと変わります。この層全体を自動的に最新に保つより踏み込んだ方法については、AIによるプロセスドキュメントが白紙からのSOP作成に取って代わる仕組みと、元の情報が変わったときに成果物を再生成する方法をご覧ください。

よくある質問