悪いアドバイス：技術文書の書き方 パート2

ユーザー向けの技術文書を適切に作成するためのヒント。
パート2

テクニカルライターのAndrei Starovoitovのマニュアルの続き。ユーザーマニュアルをより簡単に、より理解しやすくします。

ここで記事の冒頭を読むことができますが、この記事の前半で製品の文書化とローカライズのプロセスを説明しました。

このパートでは、主にユーザーのドキュメント（特にユーザーズガイド）を構成するトピック 、つまり特定の問題の解決方法を説明するタスクトピックを詳細に分析します。



トピックで説明するタスクの数-1つ以上？

タスクトピックでは、1つのタスク-「Windowsアプリケーションの起動」（「Windowsアプリケーションの起動」）といくつかの関連タスクの両方を説明できます。 たとえば、トピック「パフォーマンスの最適化」は、次のセクションで構成できます。「ディスクスペースを自動的に保存する」（「ディスクスペースを自動的に節約する」）および「MacBookのパフォーマンスを向上させるか、バッテリーを節約する」（「最適化するより長いバッテリー寿命またはより高いパフォーマンスのためのMacBook ''）。

1つのトピック-1つのタスクという原則に基づいてタスクトピックを作成する必要があります。 確かに、例外があります-アクションが反対の2つのタスクがある場合、1つのトピックで説明する必要があります。 たとえば、仮想マシンをフルスクリーンモードに切り替える方法と、後で終了する方法を説明する必要がある場合は、同じトピック内でこれを行う必要があります。
いくつかの関連タスクを説明する必要がある場合、説明が長くない限り、1つのトピックでこれを行うこともできます。

タスクトピックのセクション

タスクトピックの構成：

• 見出し
• 導入部 （英語の「intro」）
• フレーズ。ユーザーが何をする必要があるかを正確に説明します （英語の「ステップ見出し」）
• 番号付きまたは掲示の手順（英語の「番号付きまたは箇条書きの手順」）
• 最後の部分 （英語の「アウトロ」）

タスクトピックに上記のすべてのセクションが含まれていない場合があります。たとえば、IntroやOutroを挿入する必要はありません。 次に、トピックの各セクションについて詳しく説明します。

見出し

ユーザーがトピックに書かれている内容をすぐに理解できるように、このような見出しを作成する必要があります。

見出しは大容量にしますが、長すぎないようにします。 一部のブラウザまたはApple Help Viewerでは、長いヘッダーが完全に表示されない場合があります。

見出しを書くときは、命令型を使用します（「これを行う」）

たとえば、「Bonjourを使用したプリンターのセットアップ」。

問題の解決方法を説明していないトピックの名前には、命令を使用しないでください。

トピック名にわかりやすい言葉を使用し、インターフェイス要素に集中しないでください。

ユーザーは機能、用語、インターフェース要素などを理解したくない-特定の問題を解決する必要があります。 したがって、トピックの名前には、ユーザー自身が使用する単語を使用してみてください。 たとえば、「Windowsアプリケーションを使用するようにMacをセットアップする」というトピックを呼び出すと、「仮想マシンについて」のトピックよりもユーザーにとって理解しやすくなります。

ユーザーがおそらく行うように、目標を策定してみてください。 たとえば、「リモートセッションを開始する」の代わりに、「Windowsのリモート制御を開始する」というトピックに名前を付けます。

技術的に複雑な用語やインターフェース名を使用する必要がある場合、これはヘッダーではなくトピックの紹介で行うのが最適です。

英語でドキュメントを作成する場合、タイトルの単語は大文字で始める必要があります

右 ：Windowsアプリケーションを使用するようにMacをセットアップする

間違った ：Windowsアプリケーションを使用するようにMacをセットアップする

（見出しの大文字化については、マニュアルの次の部分で詳しく説明します）。

イントロ（イントロ）

見出しの直後にある導入部分では、ユーザーがタスクの完了を開始する前に知っておくべきことを書く必要があります。

プロローグには以下が含まれます。

• 追加の一般情報：ユーザーができること。
• 動機 ：ユーザーが1つまたは別のアクションを実行する必要がある理由。 既製の仮想マシンをダウンロードして使用する必要がある理由を説明する紹介部分の例を次に示します。

既製の仮想マシンを使用する

必要な構成で新しい仮想マシンを作成する時間がない場合は、構成済みの構成で完成した仮想マシンをダウンロードできます。

• ユーザーがアクションを実行している間に発生する可能性のある、ハードウェア、ソフトウェアの損傷、またはデータの損失に関する警告。
• 健康、機器、またはデータの損失につながることはありませんが、タスクの実行中に発生する可能性のある潜在的な問題または困難に関する重要な情報 。
• 説明：この用語またはその用語の意味、または機能の動作方法。

たとえば、Parallels DesktopユーザーがmacOSとWindowsを同時に操作したい場合、単一のオペレーティングシステムであるかのように、導入部分で「コヒーレンスモード」について説明して、トピックでさらに使用されます。

• 追加条件に関する情報 ：たとえば、Bonjourを介してプリンターを接続する方法を説明するトピックでは、BonjourをサポートしているWindowsのバージョンがイントロから通知される場合があります。
• 現在のタスクに必要な条件 ：トピックで説明されているタスクの実行を開始する前に、ユーザーが何か他のことを実行または確認する必要がある場合、これは導入部で言及する必要があります。 また、ユーザーがすばやく見つけて読むことができるように、説明されているトピックへのリンクを提供するとよいでしょう。

必要のない場所にプロローグを挿入しないでください。

導入部分は追加の有用な情報を提供しますが、タイトル自体からすべてが明らかな場合もあります。 そのような場合、紹介テキストを作成する必要はありません（それがあったとしても）。

例：

[スタート]メニューからMacアプリを起動する

Windowsの[スタート]メニューを開き、次のいずれかを実行します。

• [すべてのプログラム]> [Parallels Shared Applications]をクリックし、目的のアプリケーションを選択します。
• 検索フィールドにアプリケーションの名前を入力し、提案されたオプションから目的のアプリケーションを選択します。

プロローグを長くしすぎないでください

導入は長すぎてユーザーを悩ます。 このような場合、ユーザーは多くの場合それをスキップして、特定の手順のリストに直接進みます。

導入部分が大きすぎる場合は、メイン部分に言及し、別の概念または参照ページへのリンクを提供する必要があります。ここでは、すべてがすでに詳細に説明されています。

場合によっては、導入部分の長いテキストを視覚的に読みやすくするために、箇条書きを使用できます。 例：



導入部でタスクを完了する方法を教えないでください

プロローグはこれのためではありません。 何をする必要があるのか​​、どこで、どのように-導入部の後で、後で説明する必要があります。

ただし、まれに、タスクを完了するために必要なものをユーザーに伝える必要がある場合があります。 以下の例では、導入部分は、トピックで説明されているタスクを完了するために必要なものをユーザーに伝えます。



導入部でタスクの結果を説明しないでください。

これは最終パート（ Outro ）で行う必要があります。

指示の前のフレーズ（ステップ見出し）

イントロの後に、「導入」フレーズ（英語-「ステップ見出し」）を挿入する必要があります。これは、特定の結果を得るために何をする必要があるかをユーザーに指示します。

たとえば、Introでは次のように記述しています。「 インストールディスクとアクティベーションキーがある場合、それらを使用してWindowsを仮想マシンにインストールできます。 」

Introがステップ見出しになった後：「 Windowsをインストールするには： 」

そして、ステップ自体：

1）ここをクリックしてください。
2）これを選択します。
3）など...

注：トピックにイントロがない場合、ステップ見出しはオプションです。

トピックが連続したステップを説明している場合、ステップの見出しは「 何かをする：」（「To X：」）のようになります。
例：「全画面モードに切り替えるには：」（「Windowsを起動するには：」）または「 全画面モードに切り替えるには：」

最後にコロンを置くことを忘れないでください

見出しでユーザーフレンドリな単語を使用し、指示で複雑な技術用語またはインターフェイス要素の名前を使用する必要がある場合は、次の操作を実行できます：導入部で用語の意味を説明し、ステップ見出しで既に積極的に使用しています。

例：

1）ユーザーに対してヘッダーをより明確にします：

「全画面を表示するようにWindowsを設定する」

2）次に、イントロで「フルスクリーンモード」という用語を紹介します。

3）この後、ステップの見出しで、ユーザーが理解できないことを恐れることなく、すでにこの用語を使用できます。

「フルスクリーンに入るには：」（「フルスクリーンに入るには：」）

トピックで説明されているステップが一連のアクションではなく、目標を達成するためのいくつかの方法である場合、ステップの見出しは次のように実行する必要があります： 「ここに何かを行ういくつかの方法：」 （「ここにXを行う方法があります」）または「 これを行うには、次のいずれかを実行します：” （“ Xを行うには、次のいずれかを実行します：））。

たとえば、「Windowsをシャットダウンする方法は次のとおりです。 」または「 プリンターを接続するには、次のいずれかを実行します。 」（「プリンターを接続するには、次のいずれかを実行します。 」）。

ステップ見出しを作成するときは、タスクトピックで説明されているタスクを反映する単語を使用する必要があります。 英語の例を次に示します。

ページタイトル ：インストールディスクからWindowsをインストールします。
タスクカバー ：インストールディスクを使用してWindowsをインストールします。
ステップの見出し ：Windowsをインストールします。

ページタイトル ：Coherence設定を調整します。
タスクカバー ：CoherenceモードでのWindowsの表示と動作のカスタマイズ。
ステップの見出し： Coherenceモードをカスタマイズします。

ページタイトル ：全画面を表示するようにWindowsを設定する
タスクカバー ：フルスクリーンモードを開始します。
ステップの見出し ：全画面モードに入るには、次のいずれかを実行します。

番号付きステップ

特定のタスクの実行方法を説明するすべてのトピックには、何をすべきかの指示が含まれています。 テキスト内のこれらのアクションは、通常、番号が付けられているか（一連の連続したステップの場合）、箇条書きで強調表示されています（自由裁量でリストのいずれかを選択するよう提案されている場合）。

必要な手順のリストをできるだけ短くしてください。

アクションを実行する最も簡単で最速の方法を選択して説明します。 代替方法は、最終パート（Outro）または別のタスクトピックで説明できます。 1つのボタンをクリックするだけですべて同じことができる場合は、ユーザーに4つの手順で指示を読むように強制しないでください。

最も簡単な方法がツールバーからアクションを実行する場合、このオプションを説明してください。 ツールバーを好みに合わせてカスタマイズでき、疑問がある場合は、突然、ユーザーのツールバー構成がトピックで説明されているものとは異なるため、デフォルト設定で行われているすべてを説明してください。 実践が示すように、ほとんどの一般ユーザーは「工場」設定をめったに変更しません。

1つのトピックでアクションを実行する方法をいくつか説明する必要がある場合 ：

書籍の多くのタスクトピックで、さまざまな方法（メニューやツールバーなど）で実行できる特定のアクションが繰り返される場合、1つの方法を選択し、各タスクトピックで順番に言及します。

シンプルで短い代替方法があり、それについて確かに話したい場合は、同じステップでそれを行うことができます。

例：「仮想マシン構成を開くには、[アクション]> [構成]を選択するか、右上隅の[構成]アイコンをクリックします。）

順番に実行するステップに番号を付けます。

説明を膨らませず、別のステップ（「OK」をクリックするなど）で非常に短い指示を強調しないために、以下に示すように、2つの関連アクションと関連アクションを1ステップで結合できます。



箇条書きを使用して一貫性のないアクションを強調する

ユーザーには、目標を達成する方法を選択するいくつかの方法が提示される場合があります。 そのような場合、提案されたオプションは弾丸を放出します。

例：


リストにグラフィック要素の名前が含まれている場合は、明確にするためにそれらを太字で強調表示します

ユーザーが実行するアクションがグラフィカルインターフェイスの多くの要素（メニュー項目、ドウなど）をリストする場合、各オプションを新しい行で開始し、要素の名前を太字で強調表示します。 太字でマークされた要素の後に、コロンを入れて、説明をプレーンテキストで説明します。

この例に示すように：


トピック内のテキストがさまざまなインターフェイス要素を何度も参照している場合、これらの要素を説明する個別のヘルプトピックを作成する価値があります。

これは、ガイド内の多くのトピックが同じ要素を参照している場合に特に役立ちます。 この場合、トピックの最初に、言及された要素が説明されている参照トピックへのリンクを提供する必要があります。

この要素がテキストの後半で再度言及されている場合は、リンクを提供する必要がなくなりました-最初に1つだけです。 トピックに多くのリンクがある場合、これは何が書かれているかについての認識と理解を複雑にする可能性があります。

最終パート（Outro）

Outroは、番号付きのステップの後に来る最終情報です。 最後の部分を短くするようにしてください-各段落は最大3文で構成されている3つ以下の段落を使用してください。

Outroを使用して、これらのアクションの結果または結果を説明します。

結果または結果の例は次のとおりです。

•ファイルがインストールされた場所に関する情報。

•ユーザーからの追加のアクションを要求するメッセージが表示されます。

•説明されたアクションが完了した後にユーザーが切り替える必要がある設定。

たとえば、Parallels AccessをWi-Fiでのみ動作させる方法に関するトピックの最後の部分は次のように述べています。「 Parallels AccessをWi-Fiでのみ動作するように構成し、ワイヤレスネットワークが現在検出されていない場合、メッセージが表示されます-3G経由で接続しますか？ 「。

トピックの最後の部分では、タスクを完了する別の方法を説明できます。

別の方法を1つの文で説明できる場合は、トピックの最後の部分でこれを行うことができます。

Outroは、現在のタスクに関する詳細情報を提供できます。

そのような情報は、説明されたタスクを完了した後に他に何ができるかをユーザーに知らせることができます。

次の例のトピックでは、macOS Finderで仮想マシンからファイルを見つける方法について説明します。 また、トピックの最後の部分では、ファイルが見つかった後、ユーザーがファイルで他にできることを説明します。



Outroは、一部のユーザーのみが必要とする追加情報を記述することができます。

たとえば、Windows仮想マシンをmacOSに統合することに関するトピックの最後の部分では、 「MacBook Pro 2016以降を使用している場合は、タッチバーを使用して一部のWindowsアプリケーションを操作できます」と書くことができます。


長いタスクを短い段階に分割する

基本的に、タスクトピックは短く、1ページに収まります。 ただし、ステージ、ステージ、および手順に分割できる複雑で非常に長いタスクを説明する場合、論理的に情報を分離し、個別のトピックで各ステージを説明する価値があるため、説明はよりシンプルで読みやすく、理解しやすくなります。

以下は、Parallels Desktopユーザーガイドの例です。 スクリーンショットは、仮想マシンにWindowsをインストールするさまざまな方法を説明する章を示しています。 そして、その方法の1つ-リモートコンピューターからデータをインポートする方法-は、いくつかのトピックに分かれています。



継続するには...

（次の部分では、概念と参照のトピック、および問題の解決に役立つトピックについて詳しく説明します）