悪いアドバイス：技術文書の書き方 パート3および最後

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

パート3（最終）



テクニカルライターのAndrei Starovoitovのマニュアルの結論。これは、ユーザーのドキュメントをより簡単に理解しやすくするのに役立ちます。







今回はさらに詳しく検討します。

• 概念的なトピック（概念ページ）;
• 参照トピック（参照ページ）;
• 問題の解決方法を説明するトピック（トラブルシューティングページ）。
• スクリーンショットを使用する場所と方法。
• また、英語でドキュメントを作成する人にいくつかのヒントを提供します。

前の部分：文書化とローカリゼーションへのアプローチ。 ドキュメント作成のヒントパート1とパート2 。



概念トピック（概念ページ）



このようなトピックは、ユーザーに追加の技術情報を提供し、それによってタスクトピックを過負荷にしないために必要です。



正確に追加情報を含める必要がありますが、問題を解決する方法ではないことに注意してください。



概念的なトピックは、次の目的で使用するのに適しています。

• これまたはそのプロセスがどのように機能するかを伝えるため。
• このバージョンの製品に追加された新機能を説明してください。
• ユーザーが意思決定に役立つ追加情報を提供します。
• ユーザーがアプリケーションでできることを教えてください。

たとえば、トピック「仮想マシンについて」では、それが何であるか、どのように機能するかについて説明します。 ただし、このトピックでは、仮想マシンの作成方法に関する指示はありません。これについては、タスクトピックで説明する必要があります。



したがって、経験豊富なユーザーは、タスクトピックを読んでいる間、「なぜあなたは私にそれを書いているのか、私はすでに知っています...」と文句を言いません。 そして、知らない人は概念的なトピックへのリンクを読んで読むでしょう。



通常、概念的なトピックの見出しは次で始まります。

• 「About（something）」（「About Virtual Machines」）;
• 「...とは」（「仮想マシンとは」）;
• 「（何か）の仕組み」（「仮想マシンの仕組み」）;
• 「仮想マシンの基本を理解する」など

以下は、英語のドキュメントの概念的なトピックの例です。







参照トピック（参照ページ） ：



このようなトピックには、ユーザーが必要に応じて参照できるさまざまな参照情報が記載されています。



そのようなトピックの良い例は次のとおりです。

• ガイドの最後にある「用語集」。
• メニューで使用できる要素とその機能、プログラムを操作するときに使用できるクイックキーボードショートカット、タスクバーで使用できるアイコンなどを説明するトピック

GUIアイコンを説明するトピックの例を次に示します。







問題の解決方法を説明するトピック（ページのトラブルシューティング）





このようなトピックは、ユーザーが障害を克服したり、問題を解決したりするのに役立ちます。 トラブルシューティングのトピックには、次のシナリオがあります。

• ユーザーに問題があり、解決したいと考えています。 たとえば、「仮想マシンでUSBデバイスが機能しません」。
• ユーザーが何かを実行しようとして失敗しました。 たとえば、「Parallels Desktopをアクティブにできない」（「Parallels Desktopをアクティブにできない」）。
• ユーザーが変更したい条件または条件があります。 たとえば、「Windowsは遅い」（「Windowsは遅いようです」）。

トラブルシューティングとは何ですか ：



ユーザーが何かをしたいが方法がわからない場合は、トラブルシューティングではなく、タスクトピックで説明する必要があります。



トラブルシューティングとは、ユーザーが（タスクトピックの指示に従って）何かを実行しようとしたが、何らかの問題があり、ユーザーがそれを解決する方法を知らないことを意味します。



たとえば、ゲストオペレーティングシステムで外部ドライブを使用する方法を説明するトピックは、タスクトピックです。



考えられる問題を説明するトピック-「ハードディスクの接続に問題があります」-は、トラブルシューティングのトピックです。 その内容は、ユーザーが指示に従ったが、何らかの理由で成功しなかったことを意味します。



タスクトピックを作成し、手順の一部のステップでわずかな問題が発生する場合は、同じステップまたはトピックで説明することができます。 小さな問題については、別のトラブルシューティングトピックを作成する必要はありません。



たとえば、キーボードショートカットの変更方法を説明するトピックの最後に、「一部のキーの組み合わせは編集または削除できません」を追加できます。



トラブルシューティングのトピック



通常、トラブルシューティングのトピックは、タスクのトピックに似た構造を持っています。



それらは以下で構成されます：

• タイトル（「タイトル」）
• 導入部（「導入部」）
• 序文、その後に番号付きのステップまたは必要な情報（「ステップ見出し」）が始まる
• 問題を解決するために必要な情報（「解決へのステップ」）
• 最後の部分（「アウトロ」）

タイトル（ページタイトル）



トラブルシューティングトピックのヘッダーがユーザーの一人称問題を表していると便利です。 例：

• 「Parallels Desktopをアクティブにできない」（「Parallels Desktopをアクティブにできない」）
• 「Windowsが遅い」（「Windowsが遅いようです」）
• 「「仮想マシンが検出されませんでした」というメッセージが表示されます」

英語でドキュメントを作成する場合は、タイトルにタイトルスタイルの大文字を使用する必要があります（大文字については、記事の最後にある詳細を参照してください）。



右：USBデバイスが機能していません



間違った：USBデバイスが機能していません



はじめに（イントロ）



見出しの直後に、ユーザーが最初に知る必要がある情報を提供します。



例：

• 問題の最も可能性の高い原因を説明してください。 多くの理由がある場合は、可能な限りすべてを説明してください。
• 問題を解決するために何をする必要があるかを一般的な用語で説明できる場合があります。 それは一般的なことです-詳細な指示は解決へのステップで与えられるべきです。

導入フレーズ（ステップ見出し）



問題を解決するために必要な一連の手順の前に、紹介フレーズを書きます。 最後にコロンを置くことを忘れないでください。



問題の解決策が一連の連続したアクションである場合：



このような場合、導入フレーズはタスクトピックと同じ原則（ヒントの2番目の部分を参照）に従って実行する必要があります。つまり、タスクの定式化と同じ言葉を使用します。



たとえば、ユーザーが仮想マシン構成を開けない理由を説明するトラブルシューティングトピックを作成します（メニュー項目はグレー表示され、非アクティブになっています）。



タイトル：「仮想マシンの設定を開けません」



はじめに：「仮想マシンの設定を開けない場合（メニュー項目がグレー表示されている場合）、最も可能性の高い理由は、仮想マシンがオフになっていないことです。」



さらに、導入フレーズ：「仮想マシンの設定を開くには：」（実行されるタスクの定式化と同じ言葉がこのフレーズで使用されます）



そしてステップ-1）マシンの電源が切れていることを確認します。 動作する場合は、あちこちをクリックしてください。 2）次にこれを行います。



問題にいくつかの解決策がある場合：



そのような場合、導入フレーズには次の単語を含める必要があります。



-「これらのソリューションを試してください」、

-「次を試してください」、

-「それを確認してください」など



英語版のドキュメントの例を次に示します。



ページタイトル：Parallels Desktopをアクティブにできない

タスクカバー：チェックする項目のリスト

手順の見出し：Parallels Desktopのアクティベーションに問題がある場合は、次のことを確認してください...



ページタイトル：Windowsが遅いようです

タスクカバー：試すことのリスト

ステップの見出し：Windowsのパフォーマンスが遅いと思われる場合は、次を試してください...



ページタイトル：「No Macs connected」というメッセージ

タスクカバー：確認または試すべきいくつかの事項

ステップの見出し：MacのリストにMacが表示されない場合



問題を解決するために必要な情報（解決へのステップ）



このセクションには、ユーザーが知っておく必要のあるすべての情報が含まれています。



いくつかの解決策がある場合：

そのような場合は、箇条書きを使用して各方法を説明します（これについては、ヒントの後半で説明します）。 いずれかの方法が複雑で、別のトピックで既に詳細に説明している場合は、リンクを張ってください。



必要なことがすでに別のトピックのどこかに記載されている場合：

このトピックへのリンクを提供してください。



特定の指示がない場合、問題を解決するために何ができるか：

ユーザーが問題の原因を突き止めるのに役立つ追加情報を提供します。



結論（アウトロ）



結論として、タスクに関連する追加情報または問題の可能な解決策を提供できます。 outroの使用については、 パート2のヒントを参照してください 。



グラフィックスの使用（スクリーンショット、チャート、図など）



スクリーンショットと図は、ユーザーがトピックに書かれていることをよりよく理解するのに役立ちます。



グラフィックを使用する場合：



各ステップの下で、スクリーンショットを挿入する必要はありません。ユーザーはどこを見るべきか分からず、画面とスクリーンショットを常に比較します。



スクリーンショットは、指示に書かれている内容を理解するのに非常に役立つ場合に挿入する必要があります。



例：

• グアに名前のないボタンやアイコンを表示する必要がある場合、またはすぐに目を離さない場合、または画面上に類似したものがいくつかある場合。
• タスクのコンテキスト、または最終的にどのように、そしてどのように見えるかについての明確な視覚的説明を提供する必要がある場合。
• スクリーンショットを使用すると、長すぎて複雑な説明が必要な言葉をすばやく理解または説明できる場合。

スケジュールの場所と方法：



以下は、ページ上のグラフィックを配置する場所と方法に関する推奨事項です。



1）スクリーンショットに概念情報またはタスクの結果が反映されている場合は、イントロの前後に挿入できます。



以下は、英語版ドキュメントの例です。Windowsのウィンドウモードを説明するトピックを示しています。 このようなスイッチを導入後、命令自体の前に挿入した後、このモードに切り替える方法を示すスクリーンショット：







2）スクリーンショットが指示の特定のステップに言及している場合、このステップの後または中に挿入します。







ボタン、アイコン、またはその他のインターフェイス要素のスクリーンショットを挿入する必要がある場合は、この要素の名前の後に挿入する必要があります。







明白なことを説明するためにグラフィックを使用しないでください。



特に、スクリーンショットを使用して以下を説明しないでください。

• メニュー
• 名前のあるアイコン、ボタン、タブ
• 言葉で簡単かつ簡単に説明できる他のすべて。

英語でドキュメントを書く人のための追加のヒント：





1） タイトルを大文字にする方法：



大文字化大文字化には、文のスタイル、タイトルのスタイル、すべて大文字の3つのスタイルがあります。

• 文スタイルの大文字化：この行は、文スタイルの大文字化の例を提供します。
• タイトルスタイルの大文字：この行は、タイトルスタイルの大文字の例を示しています。
• すべての上限：この行は、すべての上限の例を示します。

強調のためにすべてのキャップを使用しないでください。



大文字化（文型）：文型の大文字化を使用する場合、最初の単語の最初の文字、および固有名詞と適切な形容詞の最初の文字を大文字にします。

大文字（タイトルスタイル）：書籍のタイトル、パートのタイトル、章のタイトル、およびセクションタイトル（テキストヘッド）にタイトルスタイルの大文字を使用します。



タイトルスタイルの大文字化を使用するときは、これらの規則に従ってください。 以下を除くすべての単語を大文字にします。

• 記事（a、an、the）、記事が最初の単語であるか、コロンに続く場合を除く
• 接続詞の調整（および、しかし、または、また、ため、まだ、など）
• 不定詞（プリンターの接続方法）の単語
• 品詞に関係なく、単語として
• iPhoneやiPadなど、常に小文字で始まる単語。
• 単語が動詞句の一部である場合を除き、4文字以下の前置詞（at、by、for、from、in、in、of、off、on、onto、out、over、to、up、with、with）。 例：
  
  
  
  ComputerLogを起動します
  
  ServerGetへ
  
  Parallels Desktopで開始

大文字にする：



•品詞に関係なく、最初と最後の単語：

Linuxユーザーの場合



Parallels Toolsの対象



•ハイフネーションされた複合語の2番目の単語：



正しい例：高レベルイベント、32ビットアドレス指定

間違った例：高レベルイベント、32ビットアドレス指定

例外：ビルトイン、プラグイン



•単語は、If、Is、It、Than、That、およびThis



2）「クリック」という言葉の使用方法：



クリッククリックを使用して、画面上のオブジェクトにポインターを置き、マウスボタンを短く押して放す動作を説明します。 クリックを使用しないでください。 ほとんどのユーザーはクリックが何であるかを知っているので、チュートリアルなどの初心者向けに設計されたドキュメントでのみクリックを定義する必要があります。

正しい例：Mac OS XでUSBデバイスを使用する場合は、[Mac]をクリックします。



間違った例：Mac OS XでUSBデバイスを使用する場合は、Macをポイントしてクリックします。

[使用しない]をクリックします。 クリックを使用します。



3）電子メールまたは電子メール？



メールを使用します。 電子メールを使用しないでください。



4）場合またはどうか？



ifを使用して条件を表現します。 代替案を表現するかどうかを使用します。

正しい：Parallels Toolsがインストールされているかどうかを確認します。

間違った例：Parallels Toolsがインストールされているかどうかを確認してください。

正しい例：Mac OS XでUSBデバイスを使用する場合は、[Mac]をクリックします。



5）製品名の使用方法：



製品のパッケージの大文字のスタイルに従ってください。 テキストのセクション（章など）内で最初に現れる完全な製品名を使用します。 その後、該当する場合は、製品名の短縮バージョンを使用してください。



例：Mac用Parallels Desktop 14：テキストのセクション内で最初に出現する場合、Mac用Parallels Desktop 14を使用します。



それ以降は、Parallels Desktopを使用します。



おわりに



マニュアルのこれら3つのパートでは、ドキュメントをより簡単に理解しやすくするためのヒントをまとめ、要約し、構成しようとしました。



このように書く必要があると主張することはありません-文書化やテクニックには多くのアプローチがあります。 設定を見て、自分に合った設定を使用してください。



ご清聴ありがとうございました！