スクリーンショットを使ったソフトウェアのドキュメントセットの計画方法

スクリーンショット付きのドキュメントセットは作り始めるのが簡単ですが、維持するのは難しいです。各画像はある日時点の画面のコピーで、画面は変わり続けます。撮影前に計画を立てると、最初の画面刷新の後もセットを維持できるかどうかが決まります。

この記事では、ドキュメントセットの構成、スクリーンショットのルール、Mac で Temposhot を使った作成方法を説明します。各セクションの例として、5つのプロダクト領域を持つ小規模な請求書作成 Web アプリと、サポートも担当するテクニカルライター1名のケースを使います。

読者が知りたい質問を集める

ページを決める前に、実際の質問を集めます。情報源は、サポートチケット、営業の通話、オンボーディングのセッション、社内のチャットスレッド、現在のドキュメントで使われている検索語です。

各質問は読者の言葉で書きます。

• 「チームメンバーを招待するには？」
• 「エクスポートしたファイルが空白なのはなぜ？」
• 「Sync status とはどういう意味？」
• 「監査ログはどのプランに含まれる？」

重複する質問はまとめます。できあがったリストがセットの範囲になります。リストに含まれない内容は後回しにします。

例: チケットから質問リストを作る

請求書作成チームは、直近90日間のサポートチケット240件を書き出しました。件名と顧客の最初のメッセージだけを読むと、作業に約2時間かかりました。重複をまとめた後、異なる質問は52件残りました。

10回以上尋ねられた質問は9件ありました。この9件でチケットの約半数を占めたため、作業の優先順位を決める基準にしました。残りの43件は、請求書、顧客、支払い、設定、請求の5つの領域ごとにバックログに分類しました。

読者が使う言葉を記録する

各質問には、インターフェースのラベルと一致しない場合でも、読者の言葉を残します。「カードを削除する」と書く顧客は、「支払い方法」で検索しません。ページのタイトルはプロダクトのラベルを使い、最初の文で読者の言葉を繰り返すと、検索で両方が見つかります。

質問の文脈も記録します。プラン、役割、デバイスが異なると、同じ質問でも別のページが必要になります。アカウントオーナーからの「請求書を返金するには」と閲覧者からの同じ質問は、別のページに対応します。前者はタスクガイド、後者は権限が不足している場合のトラブルシューティングです。

ドキュメントで解決できない質問を取り除く

一部のチケットは、バグや未実装の機能に関するものです。バグを説明するページは、修正後も残る回避策になります。この例では、重複をまとめる段階で52件に含める前に6件のバグ報告を除外し、ドキュメントのバックログではなくプロダクトチームに渡しました。

ラベルが分かりにくいことが原因の質問もあります。「Sync」の意味を10人の読者が尋ねている場合、リファレンスページは役立ちますが、ラベルを分かりやすくする方がより効果的です。このような質問もプロダクトチームに送ります。ラベルを変更しない場合にのみ、ページを作成します。

質問ごとにページ種別を1つ割り当てる

質問によって必要なページの形式は異なります。形式を混ぜると、ページが長くなり、読みにくくなります。

ページ種別	回答する内容	スクリーンショット
タスクガイド	「Xをするには」	ステップごとに1枚
リファレンス	「Xとは何か」	画面ごとに注釈付きの概要を1枚
トラブルシューティング	「Xが失敗する理由」	エラーの状態と解決方法
コンセプト	「Xはどのように動作するか」	図。スクリーンショットは0枚または少数

リストのすべての質問に種別を付けます。プロダクトに関する質問の多くは、タスクガイドになります。

執筆前にスクリーンショットの数を数える

ページ種別から、ページごとの画像の枚数を予測できます。その枚数にページ数を掛けると、画面刷新のたびに更新が必要な画像の数になります。撮影ツールを開く前に、この数を把握しておく価値があります。

この例では、52件の質問のうち31件がタスクガイドになり、平均7ステップでした。12件はトラブルシューティングページになり、各2枚の画像を持ちました。6件はリファレンスページになり、各1枚の注釈付き概要を持ちました。3件はスクリーンショットのないコンセプトページになりました。

247枚の画像が、このセットの実際の保守の負担です。ある1つのプロダクト領域の画面を刷新し、その約5分の1に影響する場合、約50枚の差し替えが必要になり、作業は1日から2日かかります。この数を把握しておくと、後述のスクリーンショットのポリシーを説明しやすくなります。

複数の種別を含む質問を分割する

1つの質問に2つの種別が含まれる場合があります。「エクスポートが空白になる理由と解決方法」は、タスクガイドへのリンクを含むトラブルシューティングページです。エラーと原因をトラブルシューティングページに書き、完全な手順はタスクガイドにリンクします。

スクリーンショットのポリシーを定める

スクリーンショットの見た目を一度決めて、文書にします。見た目が統一されたセットは、整備されているように見え、更新も速くなります。

• ウィンドウサイズ: すべての撮影で同じサイズにします。Action Capture の Specific Window ターゲットを使うと、1回の実行中は同じウィンドウを維持します。
• テーマと言語: ライトまたはダーク、インターフェースの言語は1つにします。
• データ: サンプルアカウントと仮の名前のみを使います。
• 切り抜き: デスクトップ全体ではなく、ウィンドウまたはパネルを切り抜きます。Framing の Focus on action を Balanced または Close に設定します。
• マーク: 1枚の画像につきクリックマーカーまたは矢印を1つ、アクセントカラーは1色にします。
• 形式: インターフェースのテキストには PNG を使います。サイトでファイルサイズを小さくする必要がある場合は WebP を使います。

スクリーンショットが不要な場面も決めておきます。たとえば、1つの入力欄だけの設定、ラベルが本文に書かれている手順、リリースごとに変わる画面です。

ポリシーを撮影設定に反映する

書面のポリシーは、撮影設定と一致して初めて役立ちます。Action Capture を一度設定すると、値は Mac に保存され、以降のすべての実行で使われます。この例のチームは、31件のタスクガイドすべてに次の設定を使いました。

Specific Window を設定すると、1回の実行中に1つのブラウザウィンドウが撮影対象になり、すべてのステップの横幅が同じになります。Include toolbar in captures をオフにしないと、ドキュメントの画像にフローティングツールバーが写り込みます。別のウィンドウを使うタスク（パスワードマネージャーなど）でない限り、Capture outside clicks はオフのままにします。

ページ種別ごとにフレーミングのレベルを設定する

フレーミングは元の画像を変更しないため、ポリシーでレベルを指定しつつ例外も認められます。タスクガイドでは、既定で Balanced（レベル3）を使いました。読者がコントロールを見つけられるだけのページ範囲を残せるためです。長い設定リストの中のトグルなどの小さなコントロールには Close（レベル4）を使いました。

リファレンスの概要では、フレーミングを使いませんでした。ウィンドウ全体を番号付きのラベルとともに表示します。目的は、すべての領域に名前を付けることだからです。Step Numbers は Pro の機能のため、無料プランでは、手動で配置した Text ラベルで同じ結果を得ます。

撮影しない場合を決める

画像は1枚ごとに将来の更新対象になるため、ポリシーには撮影しないケースも記載します。この例のチームは、ラベル付きの入力欄に値を入力するだけのステップでは画像を省きました。3秒で消える確認のトーストも省き、メッセージの内容は本文で説明しました。

5項目のいずれにも当てはまらない場合は、ステップをテキストのみで書きます。この例では、このルールにより、撮影を始める前に、予定していたタスクガイドの画像217枚のうち38枚を削減しました。

撮影ごとに同じサンプルアカウントを用意する

アカウントが異なるスクリーンショットでは、名前、合計金額、日付が異なり、読者はそれに気づきます。この例のチームは、3社の顧客、12件の請求書、2つの支払い方法を含むサンプルのワークスペースを1つ作成し、すべて仮の名前にしました。すべてのガイドはこのワークスペースから始めるため、どのページにも同じ顧客名が表示されます。

実行前に毎回サンプルデータをリセットします。あるガイドが請求書を1件削除した後に記録したガイドでは、請求書が12件ではなく11件と表示され、次の更新で一致しなくなります。ポリシー文書の冒頭に、リセットの手順を書いておき、別の作成者も同じ手順を繰り返せるようにします。

ブラウザウィンドウは、実行の前に1つのサイズに設定し、そのまま維持します。Temposhot は現在のサイズでウィンドウを撮影し、ウィンドウのサイズは変更しません。「ブラウザウィンドウの幅は 1440 ポイント、ズームは 100 パーセント」のような記載をポリシーに入れると、日が異なる撮影でも同じ縮尺を保てます。

差し替えを前提に画像を命名して保存する

すべての画像は、いずれ差し替えが必要になります。1つの画面のすべての画像をすばやく見つけられるように、ファイルに名前を付けます。

area-task-step.png のようなパターン（例: billing-change-plan-03.png）を使うと、領域とタスクで並べ替えられます。ガイドごとに1つのフォルダを作成し、編集後に再書き出しできるように、各ガイドの Temposhot Document を保存します。

Temposhot の画像の書き出しでは、ファイル名にページのタイトルが使われます。書き出しの前にタイトルを設定するか、後でドキュメントのリポジトリでファイル名を変更します。ZIP パッケージには、レンダリングされた PNG ページと一緒に document.json が含まれます。ドキュメントシステムへのインポートをスクリプトで行う場合に役立ちます。

例のセットのフォルダ構成

プロダクト領域ごとに1つのフォルダを作り、その中にガイドごとのフォルダを置きます。書き出した画像は、それを使うページの隣に配置します。こうすると、ガイドを変更するプルリクエストで、どの画像が変わったかも分かります。

ページタイトルとファイル名を一致させる

Temposhot はページのタイトルから画像のファイル名を付けるため、Click "Change plan" のようなタイトルは、並べ替えしにくいファイル名になります。方法は2つあります。1つ目は、ページのタイトルを読者向けの最終的な文に書き直し、スクリプトでリポジトリのファイル名を変更する方法です。2つ目は、ZIP パッケージを書き出し、document.json のページ順を使ってファイル名を付ける方法です。

チームがどちらを選ぶ場合でも、ファイル名のステップ番号は、ページのステップ番号と一致させます。ステップ4を削除した場合は、後続のファイルの番号を同じコミットで振り直します。

元の Document を保存する

書き出した画像はすべて、それを撮影した Mac 上の Document から作られます。Document は、その Mac の Documents ライブラリ（Command+4）にあり、Temposhot は同期しません。各 Document には、ガイドのフォルダと同じ名前（例: billing-change-plan）を付けます。こうすると、ライブラリを検索して、どの画像の元データかを見つけられます。

広範なツアーより先にタスクガイドを作成する

タスクガイドは最も多い質問に答え、内容を検証しやすいものです。最初に作成します。

1. Action Capture を開く

   Command+3 を押し、Start Action Capture を選択して、Specific Window を選びます。

2. タスクを実行する

   タスクを一度クリックして進めます。承認されたクリックごとに、そのクリックの直前のウィンドウが保存されます。タイトルの下書きは Parse clicked elements から付けられます。

3. 完了して編集する

   Finish capture を選択します。エディターでタイトルを書き直し、ページのフレーミングを調整し、マークを追加します。

4. ページを書き出す

   More export formats を開き、ドキュメントサイト用に PNG または WebP のページを選びます。

プロダクトのツアーや概要ページは、タスクガイドで重要な画面が分かった後に作成します。詳細は Action Capture ガイド と ドキュメントの書き出しガイド で説明しています。

チケット件数の多い順に最初のバッチを作る

この例のチームは、最初の1週間で、最も多く尋ねられた9件の質問のガイドを撮影しました。1件のガイドにかかった時間は約25分でした。内訳は、サンプルアカウントのリセットに5分、録画に5分、タイトル、フレーミング、マークの編集に15分です。9件のガイドは合計で約4時間かかりました。

下書きのタイトルを手順の文に書き直す

Parse clicked elements は、Click "Change plan" のように、コントロールの名前からページのタイトルを付けます。読める名前がないコントロールのクリックには Click here が付けられます。どちらも下書きです。読者向けのタイトルは動詞から始め、コントロールの名前を太字で示し、結果が明確でない場合は結果も加えます。

下書きのタイトル	書き直したタイトル
Click "Billing"	サイドバーの Billing を開く
Click here	Team のプランカードを選択する
Click "Confirm"	Confirm を選択して、次回の更新時にプランを切り替える

書き直したタイトルは、書き出し時に画像のファイル名にもなります。明確なタイトルにすると、読者とリポジトリの両方に役立ちます。

無料プランの上限とステップ数を照合する

無料プランでは、Action Capture の実行は5ステップで一時停止しますが、それまでに撮影したステップは保存されたままです。この例のような7ステップのガイドには、Temposhot Pro が必要です。または、1つの Document に2回の実行を追加します。2回目の実行を追加するには、Pages パネルの Capture new images… を使います。開いている Document に新しいフレームが追加されます。

キーボードショートカットでページを編集する

ガイド1件あたりの25分のうち、大半は編集に使われます。次のエディターのキーは、ドキュメントのページでよく行う編集を対象にしています。

注釈は元データを変更しません。このリリースで追加した矩形は、対応する画面が一致している限り、次の画面刷新の後も、ステップを撮り直さずに移動または削除できます。

ドキュメントセットを相互にリンクする

読者が必要なページに直接たどり着くことは、ほとんどありません。ページ同士をリンクして、概念からタスクへ、エラーから解決方法へ移動できるようにします。

• 各タスクガイドは、前提条件と次に続く可能性が高いタスクにリンクします。
• 各トラブルシューティングページは、そのエラーを解決するタスクガイドにリンクします。
• 各リファレンスページは、その画面を使うタスクにリンクします。

プロダクト領域ごとに短いインデックスページを作り、目的別にタスクを一覧にすると、検索ではなく閲覧で探す読者に役立ちます。

1つの質問から作るリンクの流れ

この例の「エクスポートが空白になる理由」という質問からは、4ページの流れが作られました。どのページから入っても、残りの3ページに1クリックで移動できます。

孤立したページを避ける

公開後に、すべてのページを一覧にして、受信リンクの数を数えます。受信リンクのないページは、検索でしか到達できません。この例では、52ページのうち4ページに受信リンクがなかったため、それぞれを領域のインデックスページに追加しました。

担当者とレビューのきっかけを決める

各ページに担当者を割り当てます。通常は、その機能を担当するチームです。スクリーンショットが一致するプロダクトのバージョンも記録します。

レビューのきっかけは、カレンダーのリマインダーだけよりも効果的です。

• リリースで、セットに含まれる画面が変わる。
• ラベルやメニュー項目の名前が変わる。
• サポートから、手順が現在の画面と一致しないという報告がある。
• 四半期など、一定の期間が経過する。ほかのきっかけがない場合も含む。

更新の手順は、スクリーンショットのドキュメントを最新に保つ方法 で説明しています。

リリース後に画像を差し替える

リリースで画面が変わると、ファイル名から影響を受ける画像を簡単に見つけられます。リポジトリで領域のプレフィックスを検索し、対応する Document を開き、変更されたステップのみを撮り直します。

撮影した新しいページは、選択したページの後ろに挿入できます。変更されたステップの前のページを選択してから撮影すると、新しいページは正しい位置に追加されます。

プロダクト領域ごとに担当を分ける

1人の作成者が、リリースのたびに52ページすべてをレビューすることはできません。この例のチームは、各領域を担当エンジニアに割り当て、作成者は編集者としました。担当者はリリースのチケットで変更された画面を示し、作成者が画像を差し替えます。

各ページにプロダクトのバージョンを記録する

ページのメタデータか最後の行に、プロダクトのバージョンを追加します（例: 「スクリーンショットはバージョン 4.2 に対応」）。サポートから不一致の報告があった場合、バージョンから、担当者はページがどの程度古いかを判断できます。2リリース以上古いページは、レビューキューの先頭に入れます。

よくある質問

ソフトウェアのドキュメントのページにはスクリーンショットが何枚必要ですか？

タスクガイドではステップごとに1枚、それ以外のページでは可能な限り少なくします。各画像は将来の更新対象になるため、読者の手間を減らす場合にのみ追加します。

ドキュメントのスクリーンショットは画面全体を表示するべきですか？

ほとんどの場合、表示する必要はありません。ウィンドウまたはパネルを切り抜きます。画面全体の画像には無関係のアプリが写り込み、インターフェースのテキストが小さくなります。

ビジュアルドキュメントとは何ですか？

テキストと併せて、スクリーンショット、図、動画を使うドキュメントです。用語集の ビジュアルドキュメント を参照してください。

ドキュメントサイトではどの画像形式を使うべきですか？

PNG のページはインターフェースのテキストを鮮明に保ちます。WebP のページはファイルサイズが小さくなりますが、Mac に WebP エンコーダーがある場合にのみ More export formats に表示されます。アップロード前に、Image Compressor で PNG ファイルをさらに小さくできます。

画面刷新の後、スクリーンショットの更新にはどのくらい時間がかかりますか？

変更された画面を示す画像の枚数によります。この例では、1つの領域の刷新で、247枚のうち約50枚に影響しました。保存済みの Document から変更されたステップのみを撮り直すと1日から2日かかりました。同じガイドを最初から作り直す場合は、約1週間かかっていました。

複数の作成者が1つの Temposhot Document を共有できますか？

できません。Document は作成した Mac に保存されます。書き出したファイルはドキュメントのリポジトリで共有し、各ガイドの元の Document は担当者の Mac に保管します。

クリック操作を分かりやすい手順ガイドにする

Action Capture は、一定のウィンドウサイズと下書きのタイトルで、各タスクガイドを1回の操作で記録します。Temposhot をダウンロード して、リストで最も多く尋ねられている質問から始めてください。