ヘルプファイルの作り方

多くのコンピューター・ユーザーには無視されがちですが、ヘルプ・ファイルは、関連するソフトウェア・アプリケーションの使用方法に関する重要な情報を提供します。ヘルプ」をクリックすることで、ユーザーはプログラムの機能の概要、見ている画面の説明、指定されたタスクを実行するためにプログラムを使用する方法に関する説明、またはプログラムに関するよくある質問とその回答のリストを読むことができます。ヘルプファイルを書くには、ソフトウェア・アプリケーションを扱う能力と、ユーザーが理解できるように説明する能力の両方が必要です。

1

文書化するソフトウェアのコピーを入手してください。可能であれば、プログラムの仕様書のコピーも入手してください。場合によっては、プログラマーが、開発期間が短いとか、特定の機能をコーディングできないなどの理由で、仕様書から逸脱することもあります。

2

ヘルプ作成ツールを入手する。リッチテキスト形式（.rtf）のファイルを使用して、手作業でヘルプファイルを作成することも可能ですが、ほとんどのヘルプファイル作成者は、RoboHelp、Help and Manual、Doc-To-Help、MadCap Flare、HelpLogixなどのソフトウェアアプリケーションを使用してヘルプファイルを作成します。ほとんどのヘルプ作成ツールは、テキストエディタを含むか、Microsoft Wordのようなワープロソフトと連動し、ヘルプ作成者がヘルプファイルを書きながら、ヘルプファイルがどのように見えるかを確認できるユーザーインターフェイスを提供します。一部のヘルプ作成ツールには、ヘルプファイルに含めるスクリーンショットを作成するためのグラフィックエディターも含まれています。

• ヘルプファイルのフォーマットはいくつかあります：最も一般的なのはHTMLヘルプで、Windowsで動作するアプリケーションで使われています。(最も一般的なのはHTMLヘルプで、ウィンドウズで動作するアプリケーションで使われています（古いフォーマットであるWinHelpはもうサポートされていません）。アップルやユニックスにもそれぞれ独自のフォーマットがありますし、サン・マイクロシステムズにもJavaHelpがあります。複数のオペレーティングシステムで動作するように設計されたソフトウェアアプリケーションは、ユーザーのウェブブラウザで動作するクロスプラットフォームヘルプシステムを使うことができます。どのヘルプ作成ツールを使用するにしても、ヘルプファイルを作成しようとするヘルプフォーマットをサポートしている必要があります。

3

ヘルププロジェクトファイルを作成します。ヘルプ作成ツールは、指定されたファイル名とその他の情報に基づいて、ヘルププロジェクトファイルを作成します。メインプロジェクトファイルには、コンテンツファイル、インデックスファイル、1つ以上のイメージファイル、その他のファイルに関する情報が含まれています。

• コンテンツファイルには、ドキュメント化するソフトウェアアプリケーションの動作を説明するヘルプファイルのテキストが含まれます。テキストは通常、特定の画面、機能、手順をカバーするトピックに分かれています。
• インデックスファイルは、ヘルプファイルのトピックのリストです。ユーザーが閲覧するトピックを選択するための目次や、ヘルプファイル内の検索可能な索引を作成するために使用されます。
• イメージファイルは、ヘルプファイルのテキストが何を参照しているかをユーザーが理解する能力を高めるために、ヘルプファイル内に表示されるプログラム画面またはそれらの画面の一部のグラフィックファイルです。

4

ヘルプウィンドウのサイズを調整する。ユーザーのウェブブラウザに表示されるようにヘルプファイルを書いているのでなければ、ヘルプファイルは独自のウィンドウに表示されます。ヘルプ作成ツールは、エンドユーザーがアプリケーション自体の邪魔にならずにヘルプファイルを読むことができるサイズに、ウィンドウの水平方向と垂直方向の寸法を調整することができます。メインヘルプウィンドウは、左側に目次、右側に選択したトピックが表示される3ペイン形式になっていることがよくあります。

• ヘルプファイルには、メインウィンドウの他に、特定の機能を詳しく説明するセカンダリウィンドウや、機能の簡単な説明をする自動サイズのポップアップウィンドウを表示することができます。ヘルプファイルには、ハイライトされたテキストやボタンがクリックされたときにのみ表示される埋め込みテキストを含めることもできます。

5

ヘルプトピックを作成します。これを行うには、仕様書またはプログラム自体をレビューして、プログラムの画面と機能を文書化するトピックを作成する必要があります。各トピックを作成すると、ヘルプ作成ツールがそのトピックをヘルプファイルの目次と索引に追加します。

• 目次は作成しながら作成することもできますが、目次をどのように整理するかについて、ある程度計画を立てておくと便利です。目次は、プログラムの画面、機能、使用方法、またはそれらの組み合わせを中心に整理することができます。
• トピックを書きながら、ヘルプファイル内でユーザーが素早くアクセスしたいと思うような他の情報も考慮してください。ヘルプファイルのテキストに、その情報を持つトピックに接続するジャンプ（ハイパーリンク）を作成することができます。

6

必要に応じてスクリーンショットを含める。多くのプログラム機能は、テキストとグラフィックを組み合わせて説明するのが最適です。スクリーンショットは、ヘルプ作成ツールに付属しているアプリケーションでも、Microsoft Paint、Paint Shop Pro、SnagItなどの別のアプリケーションでも作成できます。

• テキストとスクリーンショットは、ユーザーが過度にスクロールしなくてもスクリーンショットとその補足テキストを確認できるように、トピックに一緒にレイアウトする必要があります。多くの場合、画面全体ではなくプログラム画面の一部を表示したり、スクリーンショットをオリジナルよりも小さいサイズで表示したりすることができます。スクリーンショットアプリケーションは、ぼやけたり細部を失ったりすることなくスクリーンショットのサイズを変更できるものでなければなりません。
• テスト版と最終版の間でユーザー・インターフェイスの変更が予想される場合は、最終版のプログラムが完成するまでスクリーンショットの作成は控えた方がよいでしょう。

7

必要であれば、マップファイルを作成します。いくつかのプログラムには、ユーザーがクリックしてヘルプファイルのトピックを表示するための「ヘルプ」ボタンが含まれており、その画面がどのように動作するかを具体的に説明しています。このようにトピックを表示することは、文脈依存ヘルプと呼ばれ、プログラマーが「ヘルプ」ボタンをヘルプファイル内の特定のトピックにリンクするためのマップファイルを作成する必要があります。ヘルプ作成ツールで作成することもできますし、プログラマーがコーディングしてヘルプファイルに含めることもできます。

8

ヘルプファイルをコンパイルします。コンパイルすると、プログラムに含まれる実際のヘルプファイルが作成されます。ほとんどのヘルプフォーマットでは、ヘルプファイルを作成したときに作成されたすべてのコンポーネントファイルが組み込まれますが、一部のコンパイルされていないヘルプフォーマットでは、個々のヘルプトピックファイルをプログラムに含める必要があります。

9

ヘルプファイルをテストします。ヘルプファイルをコンパイルしたら、すべてのハイパーリンクが目的のトピックに接続され、すべてのグラフィックが正しく表示されることを確認するために、テストする必要があります。また、ヘルプファイルの内容が正確で、ユーザーにとって適切で、一貫性のある形式であることもテストする必要があります。ヘルプファイルを自分でレビューし、アプリケーションをテストする人たちにもレビューしてもらうとよいでしょう。

• 大規模なヘルプファイルのプロジェクトでは、コンパイルとテストは継続的なプロセスです。最終版を作成する前に、ヘルプファイルをコンパイルし、何度もチェックすることをお勧めします。

10

ヘルプファイルを開発者に渡し、プログラムに同梱してもらいます。プロジェクトの性質やヘルプファイルの形式にもよりますが、文脈依存のトピックがある場合はマップファイルなど、いくつかのファイルを開発者に提供する必要があるかもしれません。

この記事は、CC BY-NC-SAの下で公開されている " How to Make a Help File " を改変して作成しました。特に断りのない限り、CC BY-NC-SAの下で利用可能です。