ユーザー向けの技術文書を適切に作成するためのヒント。
パート1
前の記事で、 製品の文書化とローカライズのプロセスがどのように行われるかを概説しました。
今回は、テクニカルライターのAndrei Starovoitovのマニュアルです。これは、ユーザーがドキュメントをより簡単に理解しやすくするのに役立ちます（説明されている手法は、製品をドキュメント化するためにApple、Microsoft、およびその他の企業で使用されています）。
ご存知のように、優れたドキュメントは贅沢品ではなく、会社の売上を増やす手段です。 何らかのプログラムを開始するか、すでに開発している場合、それを使用して世界市場に参入するには、ユーザーマニュアル（別名ユーザーガイド）または少なくとも製品の使用を開始する方法を顧客に伝える文書（いわゆる）が必要です。はじめに）。
どの言語でドキュメントを書くか-ロシア語で翻訳してから、すぐに英語で-あなたが決めます。 Parallelsでは、2番目のアプローチを選択しました。 多くの場合、英語の説明を作成する方がはるかに簡単です。これは、ロシア語のほとんどすべての（および「すべて」の）コンピューター用語が借用されているためです。
さらに本文では、ロシア語と英語の両方の例に焦点を当てます。
それでは、ドキュメントを書くときに何を探すべきですか？
ドキュメント内のトピックの種類
トピックを書くとき、最初にどのようなトピックになるかを決定する必要があります:)
これから何をどのように書くかに依存します。
トピックには主に4つのタイプがあります 。
• 特定のタスクまたはいくつかの関連タスクを解決する方法を説明するトピック （英語では、このタイプのトピックはタスクページと呼ばれます） 。
たとえば、「Parallels Desktopのインストール」または「Windowsのシャットダウンまたは一時停止」。 これらの各トピックでは、特定の目標を達成するためにユーザーが実行する必要がある1つ以上の一連の手順について説明します。 ユーザーマニュアルは、主にそのようなトピックで構成されています。
通常、ユーザーは、特に大量のテキストがある場合、読むことを好みません。 したがって、このようなトピックはできるだけ短くするようにしてください。 理想的には、情報が次の形式で表示される場合：「何かをすることができます、ここをクリックしてここでクリックしてください」（タスクトピックについては、記事の次の部分で詳しく説明します）。
開発者が、ユーザーが知っておく必要のある追加情報があり、多くの情報があると考えている場合は、概念トピックでこれを説明することをお勧めします（以下を参照）。
• 概念的なトピック （英語- 概念ページ ）。 これらのトピックには、問題の解決方法に関する指示はありません。 それらには、物事の理解を深めるのに役立つ情報が含まれています。 たとえば、概念的なトピックは次の目的で使用されます。
-ユーザーにプロセスがどのように機能するかを正確に説明します。
-アプリケーション設定で何ができるかを伝えます。
-製品の新しいバージョンに追加された機能を説明します。
-ユーザーが問題をよりよく理解または解決するのに役立つ追加情報を提供します。
タスクトピックが過負荷にならないように、概念トピックで正確に追加情報（多くの場合）を提供する必要があることに注意してください。
• 参照トピック （英語- 参照ページ ）-特定の用語の意味、機能の動作などを確認するためにユーザーが定期的に参照できる情報が含まれています。 このようなトピックの良い例は、ガイドの最後にある辞書（用語集）です。 参照トピックは、さまざまなインターフェイス要素の目的を説明するのに特に役立ちます。
• 問題の解決方法を説明するトピック （英語- トラブルシューティングページ ）。
例：「Parallels Desktopをアクティブにできない」または「インターネットに接続できません。」 これらのトピックでは、問題を解決するために何をする必要があるかについて説明します。 また、故障の原因を理解するのに役立つ情報が含まれている場合があります。
すべての種類のドキュメントの基本的な手順
ガイドを作成する場合：
1） ユーザーに集中する
•機能またはインターフェイス要素に基づいて製品の説明を構造化する代わりに、ユーザーが解決しようとする可能性が最も高いタスクに集中するようにします。
たとえば、仮想マシンのデータを保護する方法に関するトピックは、2つの方法で呼び出すことができます。
a）「セキュリティ設定」。データを保護するためにできることを詳細に説明します。
b）特定のタスクを説明するいくつかのトピックを作成します。
-「ウイルス対策ソフトウェアでデータを保護する」
-「仮想マシンのバックアップ」（「仮想マシンのバックアップ」）
ドキュメントの現在の傾向によれば、この場合、ユーザーは何かを行うかどうかを推測する必要がなく、正確に何をする必要があるかについて明確な指示を受け取るため、2番目のアプローチが望ましいです。
•ユーザーのタスクと技術的リテラシーのレベルに焦点を当てます。
たとえば、平均的なユーザー向けのドキュメントでは、「仮想マシンの作成」と書く代わりに、「Windowsまたはその他のOSのインストール」と書く必要があります。仮想マシン」は誰にも知られていません。 または、別の例-クイックキーボードショートカットの作成方法を説明するトピックでは、「キーボード設定」ではなく「キーボードショートカットの構成」を呼び出すことをお勧めします。
ポイントですが、Habrの読者の大多数にとっては、「ショートカットを構成する」ことはより明確になりますが、現時点では公式用語でそのような用語がどれだけ適切かは疑問です:)
•これが明確でない場合は、ユーザーが特定のタスクを完了する必要がある理由を説明してください。
例：
•説明するとき、ユーザーがスピーチで毎日使用する単語を使用するようにします。 技術的に複雑な用語を単純な単語に置き換えることができる場合は、常に単純な単語を使用するようにしてください。
たとえば、「transparent」ではなく「transparent」です。 英語の例を挙げる場合は、「utilize」の代わりに「use」を使用します。
2） 不要な言葉を使わずに、必要なすべての情報を提供してください
「サモス島の大使が助けを求めてスパルタに来ました。 彼らは長く美しいスピーチをしました。 スパルタンは言った：「終わりに耳を傾けていた、私たちは始まりを忘れて、始まりを忘れて、終わりを理解しなかった。」 サモセットは機知に富んでいた。 翌日、彼らは空の袋を持って会議に来て、4つの言葉だけを言いました：「袋があり、小麦粉はありません。」 スパルタ人は彼らをscりました-2つの言葉で十分でした：「小麦粉はありません」、しかし、彼らはそのような速い機知に満足して、助けると約束しました。
機能の説明が長すぎると、誰も読むことができません。 しかし、それは完全に「質素な」方法でもあります。書かれている内容が少なすぎると疑問や疑問が生じると、ユーザーはサポートチームを引き始めます。 一般に、バランスを維持することが重要です。
ユーザーが必要なすべての情報を見つけやすくすると同時に、できるだけ簡単に各セクションを説明するために：
- トピックで説明されている問題を解決するために必要な最も重要な情報に焦点を当てます。 タスクに一部の詳細が必要でない場合は、説明しないでください。
- クリックごとに文書化する必要はありません。 インターフェースのすべてが明確な場合は、ユーザーが自分で理解できるようにします。 たとえば、プログラムをインストールする各手順を文書化する代わりに、「プログラムをインストールするには、画面の指示に従ってください」と書くことをお勧めします。 手順の最終段階で[OK]をクリックする必要がある場合、これも説明する価値はありません。
- すべての情報を1つのトピックで提供する代わりに、他のトピックへのリンク、外部リソースへのリンクを使用して追加情報を読むことができる場所をユーザーに示すか、「関連情報」セクションを最後に挿入します。画面の説明に関連するトピック。
- 長いタスクを複数のステージまたはサブタスクに分割でき、それぞれが個別のタスクである場合、トピックを適切なセクションに分割するか、各ステージを説明するトピックで構成されるガイドのセクションを作成します。 この場合、関連トピックへのリンクを挿入することを忘れないでください。
- タスク（たとえば、仮想マシンの起動）をいくつかの方法で実行できる場合、それらすべてを説明する必要はありません。 最速かつ最も簡単な方法について言及するだけで十分です。 それでもユーザーが他の方法を知っていると便利だと思う場合は、最後に（英語-Outro）トピックで説明してください。
3） ページで同じ情報を繰り返さないでください
他のトピックで既に説明されている各トピックの情報を繰り返す代わりに、そのようなトピックでより詳細な説明を見つけることができるか、単にハイパーリンクを付けることをお勧めします。
4） ユーザーの注意を正しく引き付ける
説明でユーザーの注意を引く必要がある場合は、「注意！」（英語-警告！）、「重要：」（英語-重要:)、「注意：」（英語-注： ）
これらの言葉のそれぞれは、それ自身のレベルの「重要性」を暗示しています。
ユーザーを無駄にしないために、各用語を正しく使用してください。
- 「注意！」 （英語の警告）を使用して、回避しないとデータの損失、コンポーネントの損傷、またはその他の損傷を引き起こす可能性のある危険な状況を示します。
- 「重要：」 （英語-重要:)を使用して、重大で潜在的に問題のある状況を示しますが、物理的損傷、損傷、またはデータ損失につながることはありません。
- 「注：」 （ 注：英語）を使用して、このトピックに関連する追加情報を提供してください。 このような挿入はユーザーを現在のタスクから切り離しますが、便利な場合があります。
例：
仮想マシン構成を開くには、「アクション」>「構成」をクリックします。
注：仮想マシンはオフにする必要があります。
「メモ：」というメモは控えめに使用してください。頻繁に挿入すると、テキストが詰まり、注意を払わなくなります。
可能であれば、トピックの冒頭に「注意！」、「重要：」、および「注：」を挿入して、ユーザーが手順の実行を開始する前にこれについて知るようにします。 ただし、情報が特定のステップのみを参照している場合は、このステップの後に挿入します。
例：
続行するには...
（記事の次の部分では、特定の問題を解決する方法を説明するトピックをさらに詳しく説明します）