エラーメッセージに関連ドキュメントへのリンクを含めますか？

外部の開発者が使用している商用ライブラリとコード例を作成します。ライブラリの使用方法を広範囲に説明する（登録済みユーザーは利用できますが、閉鎖された）ドキュメントがあります。

開発者の多くは初めてのユーザーなので、多くの初歩的なエラーが発生します。

エラーログにドキュメントへのリンクを含めることは適切ですか？考えられる欠点は何ですか？いくつかは予想できますが、以下を克服することは可能と思われます

• ドキュメントのURLが古い
• 最新のドキュメントに反映されていないバージョン固有のエラー
• 他に何か問題があり、無関係なドキュメントに送信することで開発者の時間を無駄にしています

意味の例の下に、太字のテキストを追加するのは良い考えですか？

[エラー]プロジェクトstandalone-pomで目標org.apache.maven.plugins：maven-archetype-plugin：1.2.3：generate（default-cli）を実行できませんでした：目的のアーキタイプが存在しません（com.example.library。 archetypes：library-archetype-blank：1.2.3.0）->詳細および考えられるトラブルシューティングについては、http：//example.com/docs/setting-up-an-archetypeを参照してください

これらのエラーメッセージガイドラインと私の経験によれば、人々はドキュメントやヘルプを読まないことで時間を節約したいと思っています。エラーをグーグルすることもそれらを超えている可能性があるので、クリックする理由がある場合はリンクを含めてください。

最後に、おそらくNielsenのコンピュータドキュメンテーションの第一法則をすでにご存じでしょう。人々はそれを読んでいません。この発見は、ユーザーが自分の仕事に不可欠ではない読書を本当に避けているWebサイトにとってはさらに強力です。ヘルプをクリックしますか？決して。

ユーザーは、問題が発生したときにのみシステムのドキュメントを読みます（これが第二法則です）。エラーから回復する場合は特に注意が必要です。この場合、エラーメッセージを教育リソースとして使用して、ユーザーに少量の知識を与えることができます。もちろん、すべてのWebコンテンツと同様に、エラーメッセージは簡潔かつ要点を絞ったものでなければなりません。ただし、エラーメッセージは、システムがどのように機能するかについてユーザーに少し教え、ユーザーがシステムをよりよく使用するために必要な情報を提供します。そのために、Webの基盤となるテクノロジーにより、別のガイドラインが可能になります。

ハイパーテキストリンクを使用して、簡潔なエラーメッセージを、追加の背景資料または問題の説明を含むページに接続できます。（ただし、無理しないでください。）

はい、間違いなくBUT：

• リンクの腐敗が問題になります。理想的には、既知のターゲットドキュメントから動的にリンクを生成しますが、なんらかの構成からプレフィックスを取得します。サーバーが変更された場合は、この構成要素を更新することにより、古いコードを有効に保つことができます。このプレフィックス設定を変更するだけで、ローカルでドキュメントを利用できるようにすることもできます。
• バージョニング：同じ精神で、リンクに常にバージョニングを含めることができる場合は、リンクが常に正しいバージョンのドキュメントを指すようにします。
• ドキュメントを編集可能にするWikiタイプのサイトのように、ドキュメントの間違いを動的に修正できます。理想的には、ユーザーがページに直接コメントすることもできます。これにより、ユーザーが参加して必要なものを見つけやすくなり、ドキュメントを良好な状態に保つための重要な情報が得られますが、定期的に監視し、ほとんどすべての人が積極的に参加するようにしてください。
• 生成されたテンプレートは、ビルドシステムに、コードの注釈からドキュメントの基本的なテンプレートを直接生成させます。ただし、シンプルにしてください。ただし、これにより、すべてのリンクが常に有効なドキュメントを指すようになります。wikiを使用する場合は、これらのテンプレートを簡単にプッシュできることを確認し、コードと同じ方法でドキュメントサイトを宣伝できることを確認してください（prodサイトとは異なる開発サイトを用意し、prodにコードを宣伝します） prodサイトで挿入を自動的に実行します）。

Javaまたは.NETで開発する場合、ドキュメントはjarファイルまたはDLLファイルに含めることができ、接頭辞を変更することで、コードがローカルでフェッチすることができます。

wikiのアプローチを選択する場合は、DokuWikiをシンプルにすること、およびビルドシステムからの自動インジェクションに非常に使いやすいフラットテキストファイルに基づいていることから、DokuWikiを強くお勧めします。そうは言っても、私はあなたの環境や顧客について、これがYMMVに適しているかどうかを本当に知るほど十分には知りません。

私が作成した最も成功したツールのいくつかは、エラーメッセージがタスクを実行する可能性が最も高い実際のユーザーを対象とする同様のアプローチを取っていました。つまり、エラーが適切なレベルの抽象化であることを確認するために、例外のキャッチとラッピングをたくさん行う必要がありました。また、各エラーメッセージに最も可能性の高いエラーのソースが含まれ、潜在的な解決策が示されていることを確認しました。 XXXおよびwhatnotは​​、エラーが発生したコンテキストから生成されます。

このアプローチはやや単純でしたが、より制限されていました。ただし、リンクが腐敗する可能性がないため、ドキュメントが常に存在するという利点があります。

あなたのアプローチは次の進化です。はるかに複雑ですが、はるかに多くの潜在的な利益があります。それは費用がかかりますが、正しく行われると簡単に元が取れます。

オンラインではなく、ライブラリにバンドルされているオフラインのドキュメントを指すようにしてください。

（com.example.library.archetypes：library-archetype-blank：1.2.3.0）->詳細および考えられるトラブルシューティングについては、/ usr / share / myprog-3.8.1 / docs / setting-up-an-archetypeを参照してください

（明らかに、Windowsライブラリの場合、パスは異なります）。

ここでの利点は次のとおりです。

• このようにして、ドキュメントは常にライブラリと同期しています。人々は古いライブラリのバージョンを開発し、トラブルシューティングします。また、会社名が変更されたり、製品名が変更されたり、更新時に誰かがボールを落としたりすることがありますexample.com。

• ウェブは急速に変化しています。あなたが与えるリンクはですhttpが、数年後にはその主要なブラウザがサポートするだけになるでしょうhttps。または、gopherプロトコルに戻ることもできます。

• アプリケーションのトラブルシューティングは、インターネットアクセス（または少なくともドメインへの直接アクセス）が行われている環境では必ずしも発生しません。

• あなたのドキュメントは「認証」の壁の背後にあると述べています。エラーメッセージを理解するためだけにWebサイトでアカウントを作成するのは楽しいことではありません（これが、SOがログインする必要がない理由です）。

この問題に取り組むための本当に成功した方法があります。メッセージと組み合わせた例外が十分に一意であることを確認して、それらをWeb検索に貼り付けて、この問題に正確に関連するすべての投稿を簡単に見つけることができるようにします。

これが、私がnullポインタ例外を非常に嫌う秘密の理由です。確かに私はnullをチェックする必要さえあるのが嫌いですが、最も気になるのは、1つに出会ったときに検索する必要がある唯一の本当に一意の識別子が揮発性の行番号だけであることです。

はい、これらを検索できるようにしたいと思います。確かに、何かがnullのままにされてから使用されたために発生したことは知っています。何かがnullのままにされた理由は何ですか。

確かに、これらすべての他のドキュメントソリューションを検討してください。しかし、あなたができる最も怠惰なことは、私にとって最も良いことです。

プリティープリーズ？