什么是好的在线文档？

Question

阅读在线文档有用和有趣的内容是什么？

Disclamer: 虽然这个问题有自私的起源(我在写文档,并且,自然希望它是在那里最好的一个),我相信其他人可以采取的答案爱维稳特.另外,虽然文档不是编程,但我仍然认为在这里问这个问题是合适的,因为如果编程的话你需要记录内容.

详细说明: 这个问题是针对在线文档的,因为我认为在1500页的页面和网页/网站的动态之间有很大的不同.

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

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

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

回答:

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

Answer 1

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

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

Answer 2

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

一些方面是:

最新.如果文档不再是最新的,它可能会成为一个显示阻止.
许多在线文档都以一些简短的教程开头.它们展示了软件的一些关键方面,让用户意识到并有兴趣深入挖掘.
HowTos或常见问题解答通常非常有用.许多用户选择不阅读文档,只是尝试一下.在某些时候,用户很可能一遍又一遍地问同一个问题.请注意用户可能要求的内容以及他们已经要求的内容.
对于感兴趣的用户,请在核心文档中提供一些详细信息.
还要考虑考虑文档的受众.作为文档的作者,我认为明确说明文档所针对的受众以及他们应该具有哪些知识是非常有用的.这迫使我具体而简洁.这样我最终可能会将文档分成不同的不同部分,这使得文档非常有条理.

如果您已经有一个"1500-pages pages tome like"文档,那么您可以包含一些教程,HowTos和常见问题解答,这会使文档更有趣.当软件发展时,您可以重构核心文档以提高可读性.

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

Answer 3

我同意这里有很多其他的海报,有两件事并不真实,但对我来说非常重要:

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

PS:并提供可下载的版本供离线使用总是很好.

Answer 4

好的文档应该解释"为什么",而不仅仅是"什么".我为什么要使用此功能？它有什么好处？

那,它必须有良好的搜索设施.

Answer 5

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

此外,请务必提供一个像样的搜索工具(即使只是重定向到特定于网站的谷歌搜索).这是我有时喜欢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是多么重要.

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

最重要的事情:

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