在错误消息中包括指向相关文档的链接？

我们创建了一个供外部开发人员使用的商业库和代码示例。我们有（封闭的，可供注册用户使用）文档，其中广泛解释了如何使用该库。

许多开发人员是首次使用，因此会遇到很多基本错误。

在错误日志中包含指向文档的链接是否合适？可能的不利之处是什么？我可以预见一些，但似乎有可能克服以下问题

• 文档URL已过期
• 最新文档中未反映的特定于版本的错误
• 还有其他问题，我们通过将开发人员发送给无关的文档来浪费开发人员的时间

在我的意思示例下面，添加粗体字是个好主意吗？

[错误]无法在独立项目上执行目标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了解更多信息和可能的故障排除

根据这些错误消息准则以及我的经验，人们喜欢通过不阅读文档或帮助来节省时间。搜寻错误也可能不在他们范围内，因此当他们有理由点击它时，请包括一个链接。

最后，您可能已经知道了尼尔森的《计算机文档第一定律》：人们没有读过它。对于网站而言，这一发现甚至更为强大，因为在该网站上，用户真正回避了对其任务而言并非必不可少的任何阅读。单击帮助？决不。

用户只有在遇到麻烦时才阅读系统文档（这是第二定律）。当他们想从错误中恢复时，他们特别专心。鉴于此，您可以将错误消息用作教育资源，以向用户传递少量知识。当然，错误消息应该简短而切题，所有Web内容也应如此。但是，错误消息仍然可以教会用户一些有关系统如何工作的信息，并为他们提供更好地使用它所需的信息。为此，Web的基础技术使另一条准则成为可能：

超文本链接可用于将简明的错误消息连接到带有其他背景材料或问题说明的页面。（不过，不要过度这样做。）

是的，但绝对是：

• 链接腐烂将是一个问题，理想情况下，可以从已知目标文档动态生成链接，但可以通过某种形式的配置获取前缀。如果服务器发生更改，则可以通过更新此config元素使旧代码有效。您也可以仅通过更改此前缀配置来使文档在本地可用。
• 版本控制：本着同样的精神，如果可以的话，请一定要在链接中包含版本控制功能，以便链接始终指向正确的文档版本。
• 使文档可编辑类似于Wiki类型的文档站点，您可以在其中动态纠正错误，理想情况下还允许用户在页面上直接发表评论。这将使您的用户更轻松地参与并找到他们所需要的东西，并且您将获得黄金信息以使您的文档保持良好的工作状态，但要确保您定期对其进行监视，并且大多数人都积极参与。
• 生成的模板使您的构建系统直接从代码中的注释生成文档的基本模板。尽管要保持简单，但这将确保每个链接始终指向有效的文档。如果您确实使用Wiki，请确保可以轻松地推送这些模板，并确保可以以与编写代码相同的方式升级文档站点（拥有一个不同于prod网站的dev网站，并且将代码推广到prod网站自动在产品网站中执行插入操作）。

如果您使用Java或.NET开发，则该文档可以包含在jar文件或DLL文件中，并且通过更改前缀，您的代码可以改为在本地获取。

如果您确实选择了wiki方法，我会热烈推荐DokuWiki，因为它很简单，并且它基于平面文本文件，这对于从构建系统进行自动注入非常友好。就是说，我对您的环境或客户不太了解，因此无法真正知道这是否适合YMMV。

我创建的一些最成功的工具采用了类似的方法，其中错误消息针对的是最有可能执行任务的实际用户。这意味着我必须进行大量的异常捕获和包装，以确保错误处于适当的抽象级别。我还确保每个错误消息都将包含最可能的错误源，并指出潜在的解决方案“您是否忘记设置xxxx配置值？”，“确保xxx和yyy通过给它们指定不同的名称不会冲突”等。从发生错误的上下文中将生成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协议中。

• 在具有Internet访问权限（或至少直接访问您的域）的环境中，应用程序故障排除并不总是发生的。

• 您提到您的文档位于“身份验证”墙的后面。只在网站上创建帐户只是为了理解错误消息是不愉快的（这就是为什么SO不需要人们登录的原因）。

解决这个问题有一种非常成功的方法。确保与消息组合的异常足够独特，以至于将其粘贴到网络搜索中就可以轻松找到有关此问题的所有相关帖子。

这就是我非常讨厌空指针异常的秘密原因。当然，我讨厌我们甚至必须检查null，但是最让我困扰的是，当我遇到一个时，我唯一需要搜索的真正唯一的标识符是易失的行号。

是的，我希望能够搜索这些。哦，可以肯定，我知道发生了这种情况，因为某些东西留为空然后被使用了。尽管并非总是显而易见，但为什么总是将某些内容留为空。

因此可以肯定，请考虑所有其他这些文档解决方案。但是您可以做的最懒惰的事情对我最大的好处就是给我我可以谷歌搜索的东西。

漂亮吗？