什么是好的在线文档？

Question

在线文档阅读有用和有趣需要什么？

Disclamer： 虽然这个问题有自私的起源（我正在编写文档，当然，希望它是 最好的文档），我相信其他人可以优先考虑答案。另外，虽然文档不是编程，但我仍然认为在这里提出这个问题是合适的，因为如果你编写东西，你需要记录内容。

精化： 这个问题是针对在线文档的，因为我认为tome in 1500-something pages与网页/网站的动态之间存在很大差异。

假设有一个名为WhizBangDaemon的令人兴奋的新服务器，您几乎一无所知，并决定在业余时间尝试学习它。应该有哪些部分，文档要有用和有趣，并让你阅读它？

请随时提供有关现有良好示例的链接，并解释您喜欢它们的原因。

这个问题的另一种解决方法是：什么样的showstoppers让你对阅读一套文档失去兴趣？

数目：

在答案之间重新定位一些反复出现的主题：

• 快速浏览
• 介绍性文字/教程/示例
• 不仅仅是API文档
• 分为许多小部分（可能与第一点有关）
• 简明扼要
• 搜索设施
• #anchors for linked
• 可下载的格式

Answer 1

大量最小代码示例。每个任务一个。确定前5个任务;从文档复制/粘贴它们的实现并编译它是一个明智的选择。是的，我会回来看看实际的解释。我想先看一些肉。

这在评估库时会产生很大的不同。我仍然不知道Adobe Adam＆amp; Eve真正的意义。

Answer 2

许多成功的开源项目都展示了良好的在线文档的外观。

有些方面是：

• 最新。如果文档是 不再是最新的，可能成为 一个节目塞子。
• 许多在线文档都以 一些简短的教程。他们展示了一些 从软件的关键方面和保持 用户意识到并有兴趣挖掘 更深。
• 通常，HowTos或常见问题解答非常有用。 许多用户选择不阅读 文件，然后尝试一下。 在某些时候，用户很可能会问 同样的问题一遍又一遍。是 了解用户可能要求的内容和 他们已经要求的东西。
• 对于感兴趣的用户，请提供 一些核心文档中的详细信息。
• 还要考虑考虑一下 观众的文件。作为一个 文档的作者，我认为是 非常有用，明确说明 哪些受众是文档 因为他们有什么样的知识 应该已经有了。这迫使我 要具体而简洁。这条路 我可能最终分开了 不同的文档 零件，这使得文档 非常有条理。

如果您已经拥有“1500-pages pages tome like”文档，那么您可以包装围绕一些教程，HowTos和常见问题解答，这会使文档更有趣。当软件发展时，您可以重构核心文档，以提高可读性。

最困难的部分是使文档保持最新。编写文档时考虑到未来的变化。

Answer 3

我同意这里有很多其他海报，这两件事并不是真正的内容，但对我来说非常重要：

• 必须 FAST - 正常浏览和搜索
• 它是可链接的，我希望能够向某人发送指向文档特定部分的链接

作为一个反面的例子：http://livedocs.adobe.com总是感觉很慢并且很多时候它不可链接： - （

PS：提供可下载的版本供离线使用总是很好。

Answer 4

良好的文档应该解释“为什么”，而不仅仅是“什么”。我为什么要使用此功能？哪些情况有利？

那，它必须有良好的搜索设施。

Answer 5

个人宠物讨厌：在标题上运行doxygen并认为文档已完成的项目。您绝对需要介绍性材料...教程，工作（最好是独立的）代码示例，概述指向参考文档中最重要的类。 Qt是恕我直言的最好例子之一。

此外，请务必提供合适的搜索工具（即使只是重定向到特定于网站的Google搜索）。这是我有时喜欢MS .chm文件文档到网络托管在线手册的原因之一。

Answer 6

我认为PHP拥有最好的语言在线文档。

如果有一个我不知道使用的功能，我会去php.net/function-name。

例如，如果我正在寻找函数debug_backtrace，我会访问php.net/debug_backtrace。如果我拼错了函数名称或它不存在，该站点将尽力找到正确的函数并将其重定向到那里。如果做不到这一点，它会向您显示最接近您正在寻找的功能的PHP函数。

Answer 7

Django的文档相当惊人（http://docs.djangoproject.com/），它非常全面且易于阅读，可以快速找到所需内容。

• 简明文本（不需要太多阅读，因此阅读文档的时间减少）
• 好例子
• 快速查找您要查找的内容（无需搜索引擎，但需要在精彩的索引页中）

Answer 8

我真正不喜欢的是MSDN docs格式。我更喜欢JAVA Sun文档样式，Flex 3 Livedocs（http://livedocs.adobe.com/flex/3/langref/）和PHP。

Answer 9

很多公司似乎都没有意识到doc是多么重要。

撰写文档是我工作的重要部分。这是没人想要的工作，但它至少与开发团队中的任何其他人一样重要。我越来越意识到这一点，因为我使用过各种语言和工具，经历了可怜的或不存在的文档的痛苦以及良好文档的乐趣。

最重要的事情：

1. 清晰简洁
2. 好的示例值得千言万语
3. 有用的示例（与＃2不同）
4. 添加示例典型用户/大多数用户希望/需要处理的任何内容。
5. 我是否提到示例？

具体细节： 我讨厌java API文档几乎没有例子。几乎可以查找任何类别或方法，以及nada，甚至不是一个班轮。在大多数情况下，并不是说一个衬垫就足够了，但是他们甚至不能为此烦恼。

Answer 10

• 提交评论的能力很有用，因为它可以捕获从不同角度编写的文档，或者您最初没有想到的想法。
• 如果你有时间允许检查wiki风格的文档更改，那也可以获得类似的红利。
• 良好的搜索工具
• 长页面中有大量#bookmark锚点，可以在像这样的网站中轻松引用各个部分
• 使用DocBook这样的灵活格式，允许以各种方式呈现手册，如HTML，PDF，CHM等。

Answer 11

好的文档应该是可以浏览的。必须从一个角度编写，即90％的用户不愿意阅读超过10％的材料。 专注于写好事的作者与想要把事情搞砸的读者之间总是存在脱节。

使用本书中的任何技巧可以使最重要的信息高度可见。特别是警告或说明。

Answer 12

划分信息，一些可能想要尝试你的产品的人可能只想看教程或例子，我的意思很简短。

另一方面，已经购买了您的产品的人想要了解其中的大部分内容，因此需要创建具有索引和搜索功能的完整API规范，在页面之间链接信息，为API添加一些示例，而不是仅添加内容参数接收以及方法/函数返回的内容等。当然，如果您为程序员出售东西。

给出现实世界的例子!!不要只是添加参考信息，而是添加代码示例或实际工作环境示例，这些示例对于将应用您的软件以提高工作效率并完成任务而不仅仅是学习的人来说非常有用。

这就是我在文档上寻找的东西，如果它有那些，那么我会买它;）

Answer 13

真正的代码示例，以及最小的。

Hello-world风格的示例很棒，但我们需要知道生产代码中应该考虑的所有注意事项，即安全隐患，线程不安全等等。

Answer 14

在线文档（至少是它的规范标准版本）需要简洁明了。但是，所有文档的规范版本都需要简洁明了，所以对我来说，在线文档只需要复制正典。

我对这个问题的陈述背后的假设特别不满意，这个假设是关于“1500页的东西，像是对于良好的印刷版本的期望”。对我来说，这不是一本关于百科全书的任何文件的好例子。

它需要可下载，因为我喜欢我的文档 - 在我的笔记本电脑上，随时随地都可以使用。

请注意，到目前为止，很少提出良好文档的共识示例。考虑答案中列出的功能的复杂性是否与首先采用这种方式的可行性相悖。所有这些东西在某些情况下都很棒，但是当它被认为是主要来源时，它太过于压倒性（并且不可能保持当前和内部的一致。

是的，我已经老了，不喜欢unix手册页。从那些开始，当我需要或想要的时候，我会接受（或不接受）其余部分。

Answer 15

在我看来，你应该简单地思考一下。您也可以安装任何wiki软件或尝试从某个托管公司租用并创建您自己的文档，没有任何限制。

免费例如：screwturn