什么是好的在线文档？ [关闭]答案

【问题标题】：What is Good Online Documentation? [closed]什么是好的在线文档？ [关闭]
【发布时间】：2010-10-03 09:54:28
【问题描述】：

在线文档需要什么才能变得有用且有趣？

免责声明： 虽然这个问题有自私的根源（我正在编写文档，并且自然希望它成为最好的），但我相信其他人可以利用这些答案。此外，虽然文档不是编程，但我仍然认为在这里提出这个问题是合适的，因为如果您编写内容，则需要记录内容。

阐述： 这个问题是针对在线文档的，因为我认为tome in 1500-something pages和网页/网站的动态有很大的不同。

假设有一个令人兴奋的新服务器 WhizBangDaemon，您对此几乎一无所知，并且您决定在业余时间尝试学习它。应该有哪些类型的部分，以使文档足够有用和有趣并让您继续阅读？

请随时提供指向现有优秀示例的链接，并说明您喜欢它们的原因。

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

答案：

回顾一下答案之间反复出现的一些主题：

快速浏览
介绍性文字/教程/示例
不仅仅是 API 文档
分成很多小部分（可能与第一点有关）
简明扼要
搜索设施
#anchors 用于链接
提供可下载格式

【问题讨论】：

FWIW，如果您有兴趣，有一个 51 区技术交流提案正处于承诺阶段。

标签： documentation

【解决方案1】：

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

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

【讨论】：

Qt 的文档确实非常棒！

【解决方案2】：

好的文档应该是可略读的。它必须从 90% 的用户不愿意阅读超过 10% 的材料的角度来编写。专注于写好东西的作者和只想把事情记下来的读者之间总是存在脱节。

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

【讨论】：

【解决方案3】：

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

免费例如：screwturn

【讨论】：

【解决方案4】：

很多公司似乎没有意识到文档的重要性。

编写文档是我工作的重要组成部分。这是没有人想要的工作，但它至少与开发团队中的任何其他人一样重要。当我使用各种语言和工具工作时，我越来越意识到这一点，并经历了糟糕或不存在的文档的痛苦和好的文档的乐趣。

最重要的事情：

简洁明了
一个好的例子值一千字
有用的示例（与#2不同）
添加示例典型用户/大多数用户希望/需要对您记录的任何内容进行的操作。
我是否提到了示例？

细节：我讨厌 java API 文档几乎没有示例的事实。几乎可以查找任何课程或方法，以及 nada，甚至不是一个班轮。在大多数情况下，并不是说一个班轮就足够了，但他们甚至都不会为此烦恼。

【讨论】：

我完全同意！ JavaDoc 仅用作参考那些已经知道它是如何工作的人的参考——“这个方法承诺做什么，究竟是什么？”。这有时也太模棱两可了（如果确实存在的话），一组适当的前置条件和后置条件会有所帮助。
是的......我正坐在一大堆未记录的遗留代码上，如何使用它的示例比试图逆转更有价值（并提供更多的努力回报）设计“适当的”每个功能的文档。

【解决方案5】：

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

我特别不满意问题中陈述背后的假设，即“1500 多页的书本之类的”期望良好的印刷版本。对我来说，这不是百科全书以外的任何类型文档的一个很好的例子。

而且它必须是可下载的，因为这是我喜欢我的文档的地方 - 在我的笔记本电脑上，无论我身在何处都可以随时使用。

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

是的，我已经足够大，可以更喜欢 unix 手册页了。从这些开始，我会在需要或想要的时候接受（或不接受）其余部分。

【讨论】：

它实际上（也许也是）对这本书荒谬大小的微妙参考。我有那本书的早期版本（JRE1.3），但我从来没有超过 70 页。

【解决方案6】：

真实代码示例，以及极简。

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

【讨论】：

【解决方案7】：

大量最小代码示例。每个任务一个。确定前 5 项任务；从您的文档中复制/粘贴它们的实现并编译它是一件轻而易举的事。是的，我会回来阅读实际的解释。我想先看看肉。

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

【讨论】：

+1。最少的代码示例应该很容易上手。
如果你没有有易于使用的最小代码示例，我通常会更快地找到一个不同的、有据可查的库来使用，而不是找出你的.

【解决方案8】：

许多成功的开源项目展示了优秀的在线文档的外观。

一些方面是：

最新。如果文档是不再是最新的，它可能变成一个表演终结者。
许多在线文档都以一些简短的教程。他们展示了一些软件的关键方面并保持用户意识到并有兴趣挖掘更深。
HowTos 或 FAQs 通常非常有用。许多用户选择不阅读文档，然后尝试一下。在某些时候，用户很可能会问一遍又一遍地问同样的问题。是了解用户可能会要求什么以及他们已经要求的。
对于感兴趣的用户，提供 核心文档中的一些详细信息。
还要考虑考虑文档的受众。作为一个文档的作者，我认为是明确说明非常有用文档的受众群体他们有什么样的知识应该已经有了。这迫使我要具体和简洁。这边走我最终可能会分开不同不同的文档部分，它使文档非常有条理。

如果您已经拥有“1500 多页的大部头”文档，您可以包装一些教程、HowTos 和常见问题解答，这会为文档增添趣味。随着软件的发展，您可以重构核心文档以提高可读性。

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

【讨论】：

Developer Experience of documentation 很重要！想一想： - [指标] 测量完成“快速入门”所需的时间 - 提供代码游乐场（如 Stripe 所做的那样）、沙箱或直接将工具部署到 DigitalOcean 的按钮，例如 - 提供 clear structure （教程、操作指南、解释和您的参考文档）- 提供典型“Hello World”示例的真实示例

【解决方案9】：

我真正不喜欢的是 MSDN 文档格式。我也更喜欢 JAVA Sun 文档风格、Flex 3 Livedocs (http://livedocs.adobe.com/flex/3/langref/) 和 PHP。

【讨论】：

【解决方案10】：

我同意这里的许多其他海报，两件事并不真正满足，但对我来说非常重要：

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

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

PS：提供一个可供离线使用的可下载版本总是不错的。

【讨论】：

+1 供离线使用。它也应该是可打印的。（在纸上阅读比在电脑屏幕上容易得多。）

【解决方案11】：

Django 的文档非常棒 (http://docs.djangoproject.com/)，它非常全面且易于阅读，可以快速找到您需要的内容。

简洁的文字（不需要太多阅读，因此阅读文档的时间更少）
好例子
快速找到您要查找的内容（无需搜索引擎，但就像在出色的索引页面中一样）

【讨论】：

【解决方案12】：

划分信息，一些可能想尝试您的产品的人可能只想看教程或示例，我的意思是非常简短的示例。

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

给出真实世界的例子！！不要只添加参考信息，而是添加代码示例或实际工作环境示例，这些示例可能对那些将应用您的软件以提高生产力和完成任务的人有用，而不仅仅是为了学习。

这就是我在文档中寻找的东西，如果有，我会买它；）

【讨论】：

【解决方案13】：

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

如果有一个我不知道用途的函数，我会去 php.net/function-name。

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

【讨论】：

php.net 同上。用户在每个页面上提交的 cmets 也很有用。
好点。 “可预测的 URL”使查找内容变得容易。
是的，我非常喜欢 PHP 文档。我曾多次看到它被用作示例文档系统。

【解决方案14】：

好的文档应该解释“为什么”，而不仅仅是“什么”。我为什么要使用这个功能？适合什么场景？

那个，而且它必须有很好的搜索工具。

【讨论】：

【解决方案15】：

提交 cmets 的功能很有用，因为它可以捕获从不同角度编写的文档或您最初没有想到的想法。
如果您有时间检查对 wiki 样式文档的更改，也可以获得类似的好处。
良好的搜索工具
长页面中有大量的#bookmark 锚点，可以在此类网站中轻松引用部分内容
使用灵活的格式（如DocBook）允许以多种方式呈现手册，如 HTML、PDF、CHM 等。

【讨论】：