ユーザーマニュアルガイド：本当に使われるドキュメントの書き方

失敗は、誰かが行き詰まったまさにその瞬間に起こります。アプリを開いたり製品を箱から出したりしてマニュアルに手を伸ばすと、やりたかった1つのタスクの代わりに、すべてのメニューの案内が並んでいます。だから彼らはマニュアルを閉じ、フォーラムを検索するか、サポートに連絡します。後で彼らがドキュメントは役に立たなかったと言うとき、それは正しいのです。

解決策はシンプルです。機能をドキュメント化するのをやめ、タスクをドキュメント化し始めることです。ユーザーマニュアルは、製品ができるすべてを説明すべきではありません。1人がそれを必要とする瞬間に、1つのタスクを完了できるように助けるべきです。

このガイドは、私たちの7ステップのSOPフレームワークのエンドユーザー向けの姉妹編です。そのガイドは社内プロセスをドキュメント化する方法を説明しています。こちらは顧客とエンドユーザー向けのドキュメントに焦点を当てています。

ユーザーマニュアルとは何ですか？

ユーザーマニュアルは、製品のセットアップ、使用、または何か問題が起きたときのトラブルシューティングといった特定のタスクを完了できるように誰かを助けるエンドユーザー向けのドキュメントです。その対象は、何かを成し遂げようとしているチーム外の人であり、成功の尺度は網羅性ではなくタスクの完了です。

取扱説明書、ユーザーガイド、製品マニュアル、オーナーズマニュアル、ユーザードキュメントなど、いくつかの名前で呼ばれます。名前は変わっても、役割は変わりません。専門家でない人が助けを求めずに成果にたどり着けるようにすることです。

1つの境界を明確に保ちましょう。それがマニュアルに何を含めるべきかを決めるからです。ユーザーマニュアルは、外部の読者が製品を使うのを助けます。標準作業手順書は、自分のチームが社内プロセスをどう実行するかを説明します。両者は異なる読者に向けているため、異なる書き方をします。一方は初めてのユーザーであり、もう一方は確立されたプロセスに従う同僚です。社内の作業をドキュメント化しているなら、SOPを使ってください。顧客向けに製品をドキュメント化しているなら、あなたは正しい場所にいます。

ユーザーマニュアルの計画の立て方

私が読んだ使えないマニュアルはどれも、誰のためのものか、何を達成すべきかを誰かが決める前に書かれていました。計画は、執筆を可能にする安価な部分です。5つの決定がそれを担います。

「ユーザー」ではなく、読者を名指しする。「ユーザー」とは、誰でもない人の平均です。実際にそのタスクを行うことが許されている最も経験の浅い人を選びましょう。新しい顧客や初日のオペレーターです。そして、その人に向けて書きます。あなたの語彙ではなく、その人の語彙が読解レベルを決めます。あなたのチームが1日に50回言う言葉は、見知らぬ人が調べなければならない言葉かもしれません。

機能ではなく、仕事を列挙する。白紙のページを開き、読者がやりに来るタスクを書き出します。アカウントを接続する、フィルターを交換する、レポートをエクスポートする、パスワードを復旧する。これらがあなたのマニュアルのセクションになります。機能リストは製品がどう作られているかを中心にマニュアルを構成し、仕事リストは誰かがなぜそれを開いたかを中心に構成します。

必要とされる瞬間を見つける。読者がこれに手を伸ばすとき、どこにいるかを問いましょう。片手が空いた状態で機械の前に立っている？サインアップの途中で、少しイライラしながらスマートフォンを見ている？そのコンテキストが、長さ、フォーマット、そしてページがどこで見つけやすくあるべきかを決めます。ドキュメントは静かな部屋ではなく、負荷のかかった状況で読まれます。

スコープを決め、それを守る。スコープを決め、それを守ります。このマニュアルが何をカバーし、何を他所に案内するかを決めます。すべてを説明しようとするマニュアルは、読者が必要とする1つのことを隠してしまいます。あるタスクが実際には別のプロセスである場合は、それを教え直すのではなくリンクします。繰り返し行われる社内手順のためには、私たちの7ステップのSOPフレームワークがまさにそのためにあります。

一文を書く前に背骨を選ぶ。設定メニューの並び方ではなく、読者が進む順番でセクションを並べます。クイックスタート、次によくあるタスク、それからまれなものとトラブルシューティング。この構造は計画上の決定です。散文を書き始める前に、一度、意図的に決めましょう。

ユーザードキュメントの書き方

読者とタスクがわかれば、残りはいくつかのシンプルなルールに落ち着きます。それらはすべて同じ目的に役立ちます。読者が間違ったアクションを取るのを防ぐことです。

インターフェースではなく、タスクから始める。成果から始めましょう。設定画面の説明ではなく、「パスワードをリセットするには」です。読者は目標を持ってやって来ました。そこで彼らを迎え、それからボタンへと導きます。

見知らぬ人の読解レベルに合わせて書く。プレーンな言語は、内容を幼稚にすることではありません。忙しく、あなたの製品に不慣れな読者を尊重することです。短い文、一般的な言葉、1文につき1つの考えを使います。タスクの完了に役立たないものはすべて削ります。彼らはあなたの機能を称賛しに来たのではありません。それを使いに来たのです。

1ステップにつき1つのアクション、実行できる動詞で。1ステップにつき1つのアクションです。番号付きのステップに「そして」が含まれているなら、おそらく2つのアクションを組み合わせてしまっています。分割しましょう。各ステップを動詞で始め、重要な場合は成功がどう見えるかを述べます。「エクスポートをクリックします。ファイルがダウンロードフォルダにダウンロードされます。」確認する、保証する、確実にするといった曖昧な動詞は避けましょう。代わりに、読者に何をすべきかを伝えます。文レベルの指示の書き方の詳細については、わかりやすい作業指示の書き方のガイドをご覧ください。

1つのものを1つの言い方で呼ぶ。ステップ2で「ダッシュボード」なら、ステップ6で「ホーム画面」ではありません。同義語は良い文章のように感じられますが、2つの異なる機能のように読まれます。一貫した用語は、スタイルの好みではなく、ユーザビリティの機能です。

「完了」がどう見えるかを述べる。すべてのタスクは、読者が確認できる何かで終わるべきです。緑のチェックマーク、確認メール、または点灯し続けるステータスライトです。それがなければ、2人が同じ手順に従っても、成功したかどうかで意見が食い違うことがあります。

ユーザーマニュアルの構成とフォーマット

マニュアルは1ページ目から読まれるものではありません。あるページを開かれるものです。構成とフォーマットが、読者が諦める前に必要なものを見つけられるかどうかを決めます。

読者が予測できる背骨をマニュアルに与えましょう：

• まずクイックスタート。ほとんどの読者が完了しに来たタスクを一番上に置きます。探し回らなければならないなら、彼らは他所を見に行きます。
• 次にタスクのセクション。1つの仕事につき1セクション、仕事に合わせて命名し（「ユーザー管理」ではなく「チームメンバーを追加する」）、よくあるものからまれなものへと並べます。
• 最後にリファレンスとトラブルシューティング。設定の用語集、エッジケース、トラブルシューティングは後方に置き、それらを必要とする読者が、他の全員を遅らせることなく探せるようにします。

そして、プレッシャーの中でスキャンできるように各ページをフォーマットします：

• 順序のあるステップには番号を、それ以外にはすべて箇条書きを。番号は順序を約束します。順序が重要なときだけ使いましょう。
• アクションを先に、警告はステップの前に置く。アクションの後に来る警告は、遅すぎます。
• 見出しと余白でまとまりを作る。詰め込まれたページは流し読みされ、そこでステップが見落とされます。説明的な見出しは、読者が必要なところへ飛ぶのを助けます。
• 見つけやすくする。目次、検索、相互リンクは、どんな1文よりも重要です。最もよく書かれたステップも、読者が見つけられなければ役に立ちません。

すべてのページを、読者が最初に見るページであるかのように書きましょう。そのうちの1つは、実際にそうなのです。

ユーザーマニュアルへのスクリーンショットとビジュアルの追加

文章にすると伝わらないものがあります。ほとんど同じ3つのボタンのうちどれをクリックすべきか、正しいときに画面がどう見えるべきか、あるいはある部分が別の部分に対してどこに位置するか。読者が段落からその絵を再構築しなければならなくなった瞬間、そのステップは脆くなります。まさにそこでビジュアルが役割を果たします。

2つのルールがビジュアルを有用に保ち、3つ目のルールがそれらを最新に保ちます。

注釈を付けるか、やめておくか。加工していないスクリーンショットは「この画面のどこか」と言っているだけです。矢印、ハイライト、そして1行のキャプションは「ここ、これ、なぜなら」と言います。注釈のない画像はドキュメントではありません。読者が解釈しなければならない絵です。

判断ポイントに絞ってトリミングする。デスクトップ全体ではなく、そのステップが対象とする画面の部分を見せます。見せるものが多いほど、読者は探さなければなりません。

古くなったビジュアルは何もないより悪い。再設計されたUIの古いスクリーンショットは、画像の権威をもって間違ったアクションを教えます。マニュアルが腐る静かな理由は、手作業でビジュアルを更新するのが高くつくため、それが行われないからです。私たちはドキュメント作業全体でトレードオフを測定しました。手作業で手順を書き直して図解し直すには90〜120分かかるのに対し、撮り直すには8〜15分です。

更新が安価なとき、マニュアルは正確なままです。高くつくとき、スクリーンショットはゆっくりと嘘になっていきます。それが、ワークフローを書き起こす代わりに実際に行ってキャプチャすることの論拠です。

課題が空間的なとき、静止画は正しいツールです。課題が動き、たとえばドラッグや凍結できない一連の流れであるとき、静止画ではそれを捉えられず、そこで短い録画が引き継ぎます。凍結した1コマで伝えられるすべてについては、凍結したままにしましょう。瞬時に読み込まれ、印刷でき、読者は自分の位置を保てます。

ユーザーマニュアルの例とテンプレート

違いを見る最も簡単な方法は、2つの良い例を見ることです。どちらの例も同じ構造に従っています。ほとんどの良いユーザーマニュアルもそうです。

SaaS製品ガイド

「最初の連携を接続する」を例にとりましょう。機能優先のバージョンは、連携プラットフォームとそのアーキテクチャに関する段落で始まります。タスク優先のバージョンは、成果とステップから始まります。設定 → 連携に移動し、ツールを選択し、接続をクリックし、権限を承認し、ステータスバッジが接続済みと表示されることを確認します。

権限画面に注釈付きのスクリーンショットを1枚追加します。そこが読者がたいてい迷うところだからです。読者が最もぶつかりやすいエラーのために、短いトラブルシューティングの注記を含めます。プラットフォームの設計思想については何も書きません。

ハードウェアマニュアル

「コーヒーマシンを除石灰する」を例にとりましょう。読者はカウンターの前に立っているので、このセクションは手元に必要なもの（除石灰液、水、空のカラフェ）から始まり、続いて目に見えるチェックポイント付きの番号付きステップが並びます。

たとえば、「除石灰中はランプが黄色に点滅し、サイクルが終了すると緑色に点灯し続けます。」正しい給水タンクを示すトリミングされた写真を追加します。タンクが2つあるとき「タンク」は曖昧だからです。警告（「サイクルを中断しないでください」）は、それが守るステップの後ろではなく、上に置きます。

どちらの例も同じパターンに従っています。ほとんどの良いタスクセクションもそうです：

• タイトル：読者の言葉で、タスクに合わせて命名する。
• 目的：いつ、なぜそれを行うのかを説明する1行。
• 前提条件：ステップ1の前に必要なもの。
• 番号付きステップ：完了基準付きで、1ステップにつき1つのアクション。
• ビジュアル：言葉が脆くなるところだけ。注釈を付け、トリミングする。
• トラブルシューティング：実際に起こる2〜3の失敗モード。
• 関連タスク：次にどこへ行くか。

テンプレートは、その下で製品が変化しても生き残る場合にのみ役立ちます。各ステップを、次のリリースで動くかもしれないボタンのラベルではなく、それが達成することと近くの安定した目印に結びつけましょう。それがインターフェースの変更に耐えるように作られたテンプレートの背後にあるアプローチです。構造を一度作れば、新しいセクションはどれも4分の3が書けた状態から始まります。

FAQ