エンドユーザーのドキュメントの例の参考資料とアドバイス

Question

私たちの社内ソフトウェアは多くのユーザーに使用されており、トレーニング部門はエンドユーザーのドキュメント形式のヒントを求めてきました。

トレーニング部門がインスピレーションを得るために使用するソフトウェアエンドユーザードキュメントの良い例や、良いアドバイスがあるサイトをどこで見つけられるか知っていますか？

これはこの質問に似ていますが、技術者以外のユーザーが使用するエンドユーザードキュメントを探しています。

funkymushroom · Accepted Answer

まず、社内ユーザーにソフトウェアについてインタビューを行い、知りたい情報の種類を調べます。

私がソフトウェアについて書いたドキュメントの多くは、1人または多くの読者を想定しています。トレーニング部門は、トピックのスケルトン（TOCなど）の恩恵を受ける可能性があります。したがって、どのトピックが関連し、何が彼らのトレーニングの目的に無関係であるかについて話し合うことができます。

トピックのいくつかをカバーすることができます：

対象読者
技術要件
インストールする方法（該当する場合）
プロセス（ソフトウェアが実行するビジネス機能は何か）
機能セット（ソフトウェアにはどのような機能がありますか？）
- タスクベースのアプローチを使用できます。 ユーザーの追加またはドキュメントの追加
- あなたはオブジェクトベースのアプローチを持つことができます。ユーザー、ロール
- メニューベースのアプローチを使用できます。ファイルメニュー、表示メニュー
最後に、おそらく今後の機能とFAQセクションは、製品の成長する知識リポジトリとして機能する可能性があります。

ソフトウェアの開発に関する知識、ソフトウェアの機能に関する知識、および（できれば）エンドユーザーへのインタビューに基づいて、エンドユーザーがソフトウェアをどのように使用するかを予測してください。

最も重要なのは、読みたいドキュメントを作成し、楽しいサンプル名を使用してデモンストレーションを行い、注釈付きのスクリーンショットをたくさん使用することです。

お役に立てれば

Nicol&#225;s · Answer

私はいくつかの「エンドユーザーガイド」を読み、1つ作成しましたが、その効果を向上させる要素はたくさんあると思います。

コマンドを発行したり、アクションを実行したりする方法を画像で示します（スクリーンショットなど）。
何かをする必要性と、それを成し遂げる方法に焦点を当てます。たとえば、そのアクションがどのように最適化されるかについての技術的な説明は避けてください。
モジュールを説明するフロー図を配置すると、ソフトウェアが分割され、あまり役に立たないというコメントを受け取りました。
トラブルシューティングセクションが役立つように、ユーザーに起こりうる問題を予測するようにしてください。また、他のプロジェクトに目覚めた同僚でさえ、開発に関与していないユーザーでプログラムをテストする必要があります。
退屈な説明は避けてください。それ以上の情報は付録またはそのようなものに入れることができます。

これがお役に立てば幸いです。

MikeRand · Answer

あなたはそれが訓練のために使われると言っています。

あなたがトレーニングドキュメントをJoelのMercurialチュートリアルの1/2ほどかっこいいとしたら、私はそれを読むでしょう。しかし、上記の3つの点をコピーできたとしても、a）執筆への情熱とb）それを引き出すための信じられないほどの深い知識を持つ人が必要です。うまくいくことを願っています。

Jim Rush · Answer

Piper Merriam · Answer

これがあなたのニーズに合うかどうかはわかりませんが、技術ドキュメントに使用されているシステムがあります sphinx オンラインドキュメントの作成を容易にするためのシステムです。このようなものをあなたが興味を持っているものに使用できますか？

私はちょうど ReadTheDocs にも遭遇しましたが、これは同じことのほとんどを行いますが、ホストされたソリューションです。