ソフトウェアの手順書を明確に書く方法

明確なソフトウェアの手順書があれば、読者は手順書の内容を意識せずに作業を完了できます。余分な語、曖昧なラベル、複数の操作をまとめた手順は、読者の手を止めて読み直させます。

この記事では、特に重要な執筆ルールを例とともに説明します。Mac 上の Temposhot でガイドを作成する場合の適用方法も示します。

完了時の結果を一つ定義する

最初に結果を書きます。読者が画面を見て確認できる文を一つ作ります。例: 「請求書が顧客に送信され、ステータスが Sent になっている」。この文がガイドのタイトルになり、最後の手順になります。

結果を一つにまとめられない場合、手順書は複数の作業を含んでいます。作業ごとに分割します。「請求書を送信する」を検索した読者は、「顧客を作成する」を読み飛ばしたくありません。

スクリーンショットを撮る前に結果を書きます。撮影後に結果を書くと、書き手が偶然行ったすべてのクリックが記述されやすくなります。先に結果を書けば、どのクリックをガイドに含めるかが決まります。画面間の移動だけを目的とするクリック、たとえば正しいページに行くためにメニューを開く操作は、遷移先の名前を一つのラベルで示す形に置き換えられることが多いです。

一つの作業に役割が二つある場合は、結果が一つずつのガイドを二つ書きます。請求書を承認する人と送信する人では、開始地点も確認項目も異なります。一つにまとめると、読者は自分の役割に関係のない部分を読み飛ばすことになります。

曖昧な結果と確認可能な結果

結果は、読者が画面を見て「はい」か「いいえ」で答えられるとき、確認可能です。下の比較は、同じ作業を二通りに書いたものです。

確認可能な版は、ガイドの長さも決めます。画面上の可視ステータスで終わるガイドには、自然な最後の手順があります。書き手は、最初の段落を繰り返すだけの締めの段落を追加する必要がありません。

各手順を操作で始める

読者は動詞を探しながら読みます。手順の先頭に動詞を置きます。

弱い	明確
設定メニューを開く必要があります。	設定を開きます。
次に、保存をクリックする必要があります。	保存を選択します。
右上の角に共有ボタンがあります。	右上隅の共有を選択します。
通知がオフになっていることを確認する必要があります。	通知をオフにします。

短い動詞リストを用意し、一貫して使います。Open（開く）、Select（選択）、Choose（選ぶ）、Enter（入力）、Turn on（オンにする）、Turn off（オフにする）、Drag（ドラッグ）の七つです。「クリック」はマウスを使う読者には通じますが、キーボードやタッチ操作の読者には合いません。そのため、多くのスタイルガイドは「選択」を推奨します。

すべての手順で、動作を現在形で書きます。「保存を選択します。」と「設定を開きます。」は、今行う操作を示します。「保存を選択する必要があります。」は、読者が操作の前に取り除かなければならない一層を加えます。手順の末尾の結果の文も、画面に何が表示されるかを示します。例: 「バナーに Changes saved と表示されます。」

操作の種類ごとに動詞を一つ割り当てる

動詞リストは、動詞が一種類の操作だけに対応するときに機能します。「選ぶ」を見た読者は一覧かメニューを想定し、「選択」を見た読者はボタンかリンクを想定します。下のチェックリストは、動詞ごとに一つのルールを示します。

動詞リストのどれにも一致しない操作は、位置とラベルを書きます。ピッカーを開く操作には「Choose」を使い、処理を開始する操作には「Select」を使います。リストは短く保ちます。動詞が増えるほど、書き手が覚えるルールも増えるためです。

正確なインターフェースのラベルを使う

ラベルは、大文字小文字と句読点を含めて、画面に表示されたとおりにコピーします。ボタンに Add member と表示されていれば、「Add a user」とは書きません。読者は画面上の文字と照合します。

ラベルは太字にして、文の中で目立たせます。ラベルが見つけにくい場合や、同じ語が二か所に出る場合にだけ、場所を示します。例: 「ファイルメニューではなく、ツールバーのExportを選択します。」

同じラベルが二か所にある場合

同じラベルが二か所にあると、手順がラベルだけを指定した場合に、読者は誤った方を選びます。ダイアログは、ツールバーのボタンと同じ語を表示することがよくあります。そのため「Exportを選択します。」だけの手順は、どちらの操作とも読めます。対策は、手順が指す場所を書き、次に表示される結果を書くことです。例: 「ツールバーのExportを選択します。書き出しダイアログが開きます。」二つ目の文は、読者が正しい操作を選んだことを確認させ、次の手順に進ませます。

メニューは二つ目の問題を生みます。Settings という名前のメニュー項目が、アプリメニューとウィンドウのツールバーの両方にあることがあります。パスは、読者に必要な場合だけ書きます。メニューを最初に使う手順で、一度だけ書きます。

読者の検索に合わせたラベルのルール

ラベルが見つけられない読者は、画面上で正確な文字列を検索することがよくあります。言い換えたラベルは、誤った場所に導くか、どこにも導きません。下の表は、ルールの使用例を示します。

ラベルがアプリのバージョンによって変わる場合は、注記が必要です。ページの説明に、たとえば「バージョン 4 では、ボタンの表示は Invite です」と書きます。この注記により、読者が質問する前に疑問を解消できます。

一つの手順に一つの判断を含める

一つの手順には、一つの操作または一つの選択だけを含めます。「設定を開き、Billing を選択して、プランを変更する」は三つの手順です。長い一文では、読者が画面に戻ったときに現在位置を見失います。

例外は、同じ小さな領域で必ず一緒に行う二つの操作です。例: 「コードを入力し、Verifyを選択します。」ただし、二つ目の操作に条件がある場合は分けます。

判断を伴う手順も同じ注意が必要です。読者が選択肢から選ぶ場合は、手順の中で選択肢を列挙するか、選択を決める設定名を示します。「形式を選ぶ」とだけ書くと、読者は選択肢を推測することになります。「FormatでPDFまたはPNGを選びます。印刷する場合はPDFを選びます。」と書けば、読み直さずに適用できるルールになります。

複合手順を分割する

複合手順には、判断の箇所が隠れていることがよくあります。下の例は、プランを変更する一つの手順を、読者が確認すべき操作ごとに分割したものです。

元の文には動詞が六つと、確認が一つありました。上の四つの手順はそれぞれ一つの操作だけを含み、最後の手順にはチェックポイントが含まれます。次の節で扱います。

重要な操作の後にチェックポイントを置く

何かを変更する操作の後には、読者が見るべき結果を書きます。例: 「緑のバナーに Changes saved と表示されます。」チェックポイントは進捗を確認させ、読者が五つ先の手順に進む前に誤りを見つけられるようにします。

保存、送信、インポート、権限の確認、読み込みに時間がかかる操作の後にチェックポイントを置きます。

エラー時の案内

チェックポイントは成功時の表示を示します。エラー時の案内は、失敗時の表示と次の操作を示します。失敗しうるチェックポイントごとに、案内を一つ書きます。案内には、表示されるメッセージ、取るべき操作、戻るべき手順を書きます。

アップロードの手順を例にします。成功時のチェックポイントは「ファイル名が一覧に表示されます」です。エラー時の案内は「一覧に Upload failed と表示される場合は、Try again を選択します。二回目も失敗する場合は、ファイルサイズの上限についてトラブルシューティングのページを確認します」です。読者はメッセージを確認し、取るべき操作を把握し、どこで作業を止めるかを判断できます。

案内は短く保ちます。分岐が三つある案内は、別のトラブルシューティングガイドに分け、手順からリンクします。一つの案内を説明するのに画面を二つ以上使う場合は、通常、二つの作業に分かれています。

長いガイドでチェックポイントを置く場所

チェックポイントがないガイドでは、読者が複数の変更を行った後に失敗が見つかり、それらを元に戻す必要が生じます。下の数値は、12 手順の例のガイドを示します。チェックポイントは、読者の次の操作が結果に依存する位置に置いています。

「Done」とだけ書かれたチェックポイントより、画面に表示される結果を書いたチェックポイントの方が役立ちます。「Done」は画面上の何も確認しません。「行に Imported with 240 records と表示されます」は、読者が自分の画面と比べられる数値を示します。

画面で観察できる条件から分岐を書く

分岐は、読者が迷いやすい箇所です。分岐は、読者が知っていなければならないことではなく、画面で確認できることに基づかせます。

• 弱い: 「レガシープランを使用している場合は、...」
• 明確: 「ページに Upgrade to continue と表示される場合は、手順 7 に進みます。」

分岐は短く保ちます。分岐が二つを超える手順を含む場合は、独自のガイドに移し、リンクします。

読者の履歴に依存する分岐は避けます。「2025 年より前に登録した場合」は、画面に表示されない情報を読者に思い出させます。画面に表示される結果に置き換えます。例: 「アカウントページに Legacy バッジが表示される場合は、手順 7 に進みます。」画面上の条件に基づく分岐は、初めての読者、再訪する読者、別の人のためにガイドを確認するサポート担当者のいずれにも機能します。

画面から始まる分岐

下のフローは、読者が画面で確認できる分岐を示します。読者は、どのプランを契約しているかを知る必要がありません。

分岐は、読者を既知の地点に戻します。手順 9 は書き出しができない読者のためにガイドを終えるので、他の読者は読み飛ばす必要がありません。

スクリーンショットで位置と状態を示す

文章は何をするかを示し、スクリーンショットは場所と見た目を示します。手順ごとに一枚を使い、必要な領域に切り抜き、対象に一つのマークを付けます。スクリーンショットは状態も確認させます。読者は自分の画面と比べ、正しく進んでいるかを判断できます。

Temposhot は、クリックからこの組み合わせを作成します。Action Capture（Command+3）を開き、Configureの下にあるParse clicked elementsを有効にして、Start Action Captureを選択します。受理されたクリックごとに、クリック直前の画面が Click "[[element-name]]" という下書きタイトルとともに保存されます。Finish captureの後、Document がエディタで開きます。

各スクリーンショットは、手順が指すウィンドウまたはコントロールに切り抜きます。画面全体には多くのコントロールがあり、読者は手順が指すものを探す必要があります。書き出しの前に、切り抜きにアカウント名や無関係の通知などの個人情報が含まれないことを確認します。また、印刷または表示される大きさで画像を確認します。

下書きタイトルは、上記のルールに従って書き直します。例: Click "Save" を「Saveを選択して変更を保存します」に変えます。チェックポイントと条件はPage descriptionに書きます。PDF の書き出しでは、説明を各スクリーンショットの前か後に表示できます（Pro のカスタマイズ）。エディタのガイドでは、タイトル、説明、ツールを扱っています。

操作手順ガイド向けの設定

下の設定は、一つのウィンドウを使う読者向けに、クリックごとに一ページで対象が見えるページを作ります。

クリックを伴わずに変化する画面（処理後に更新されるステータスなど）には、手動のショートカットを使います。そのステップでは Show cursor in shortcut captures を有効にし、読者が読むべきフィールドをポインタで示します。

ガイド全体でキャプチャ対象は統一します。ガイドの途中で Active Window から Specific Window に切り替えると、ページの枠組みが一致しなくなります。

手順ページを書くためのエディタのキー

ほとんどの編集は、エディタで一ページずつ行います。下のキーは、タイトル、説明、マークを書くときに最もよく使う操作を示します。

余分な語と暗黙の前提を取り除く

読者の作業を変えない語は削除します。

• 「Simply」「just」「easily」（「簡単に」「ただ」「すぐに」）: 意味を加えず、操作につまずいた読者の負担を増やします。
• 「You will now want to」「Go ahead and」: 代わりに動詞から書き始めます。
• 「As mentioned above」（「上で述べたように」）: 事実を繰り返すか、その箇所にリンクします。

次に、前提を確認します。読者はアプリの場所、使用するアカウント、用語の意味を知っていますか。不足している点ごとに一行を追加します。通常は前提条件に書きます。

削除の効果を測る

余分な語は追加しやすく、見落としやすいものです。編集の前後で語数を数えると、一回の見直しでどれだけ削られたかがわかります。

削減の効果は、ページを短くするだけではありません。削除された語句はそれぞれ、読者が立ち止まって重要かどうかを判断する箇所でした。編集後の手順は、初めて読んだときから操作の指示として読めます。

説明せずに手順をテストする

手順書を、その作業をしたことがない人に渡します。その人が手順に従う様子を観察し、質問には答えません。一時停止や質問のそれぞれが、より明確な操作、ラベル、チェックポイントが必要な手順を示します。

読者に近いテスターを選びます。製品を作った人はラベルと流れを知っているため、その人が問題なく完了しても証明になりにくいです。サポートチームの人や、対象の役割に新しく就いた人は、作成者がもう見えなくなった不足点を見つけます。テスターにはガイドと、使用するアカウントだけを渡し、それ以上は渡しません。

問題を修正し、可能であれば別の人で再テストします。二回連続で迷わず完了すれば、手順が機能している良い兆候です。スクリーンショットチュートリアルのチェックリストには、公開前の残りの確認項目があります。

メモを取りながらセッションを行う

一時停止ごとに時刻と手順番号を書き留め、説明はセッションの後に行います。下のタイムラインは、9 手順のガイドでのセッションと、一つの有用な発見を示します。

メモは、どの手順にラベルが必要で、どの手順にチェックポイントが必要かを示します。一回のセッションは傾向を示すもので、割合を示すものではありません。そのため、ガイドを再び変更する前に二回目のセッションを行います。

操作手順ガイドに付随するファイル

ガイドには、ページ以外にも複数のファイルがあります。元の Document は Documents ライブラリに残し、書き出した PDF とメモはアプリの外の一つのフォルダに入れます。フォルダにバージョン番号とテストのメモを、読者に渡すファイルと一緒に保存すると、次の編集を同じ記録から始められます。

よくある質問

手順では「click」と「select」のどちらを使うべきですか？

「Select」（選択）は、マウス、キーボード、タッチのいずれの操作にも使えます。「click」は、読者がマウスを使い、スタイルガイドが「click」を求める場合にだけ使います。どちらを選んでも、全体で一貫して使います。

一つの手順はどのくらいの長さにすべきですか？

操作を示す一文に、必要に応じて結果か条件を示す一文を加えます。より長い説明は、注記または別ページに書きます。

手順には番号を付ける必要がありますか？

順序が重要な場合は必要です。番号があると、読者は現在位置を保てます。サポート担当者も「手順 4」と指して説明できます。Temposhot の PDF 書き出しでは、ステップ番号を追加できます（Pro）。

警告はどこに書きますか？

警告が対象とする手順の前に書きます。削除操作の後に書かれた警告は、読者にとって遅すぎます。

操作手順ガイドには何枚のスクリーンショットが必要ですか？

画面が変わる手順、または対象が見つけにくい手順ごとに一枚です。既に表示されているフィールドに文字を入力するだけの手順には不要です。初稿の後に、手順数とスクリーンショットの数を照らし合わせ、同じ画面を繰り返すものは削除します。

公開後にインターフェースが変わった場合はどうしますか？

変更されたラベルや位置を示すすべての手順を見つけ、スクリーンショットとタイトルを同時に更新します。古いラベルに新しいスクリーンショットを付けると、古いスクリーンショットよりも読者を混乱させます。ページの説明またはガイドのフッターにアプリのバージョンを記録し、読者がどのバージョンのガイドかを判断できるようにします。

キーボードだけで操作する読者のために、どのように書きますか？

手順がキーの操作やフォーカス先に依存する場合は、キーやフォーカス先を書きます。例: 「Exportボタンにフォーカスが移るまで Tab を押します」。「クリック」という語や画面上の位置には頼りません。キーボードの読者には、コントロールの位置が同じように見えないためです。公開前に、キーボードだけで一回操作して確認します。

チェックポイントはいくつあれば十分ですか？

保存、送信、インポート、アクセス権の変更を行う操作ごとに一つ、そして数秒以上かかる手順ごとに一つです。チェックポイントが多すぎると読者の作業が遅くなるため、常に一緒に起こる二つの操作のチェックポイントはまとめます。

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

Action Capture は、クリックごとに一枚のスクリーンショットと一つの下書きタイトルを作成します。これらは、この記事の執筆ルールに沿って使えます。Temposhot をダウンロードすると、録画の上で次のガイドを書けます。