关闭。这个问题是 opinion-based 。它目前不接受答案。
想改进这个问题？更新问题，以便 editing this post 可以用事实和引用来回答它。
4年前关闭。
Improve this question
在线文档需要什么才能使阅读变得有用且有趣？
免责声明:
虽然这个问题有自私的根源(我正在编写文档，并且自然希望它是最好的)，但我相信其他人可以利用这些答案。此外，虽然文档不是编程，但我仍然认为在这里提出这个问题是合适的，因为如果您编写内容，则需要记录内容。
详细说明:
这个问题是针对在线文档的，因为我认为 tome in 1500-something pages 和网页/网站的动态之间存在很大差异。
假设有一个令人兴奋的新服务器 WhizBangDaemon，您对此几乎一无所知，并且您决定在业余时间尝试学习它。应该有什么样的部分，以使文档足够有用和有趣，并让您继续阅读？
请随时提供指向良好现有示例的链接，并解释您喜欢它们的原因。
解决这个问题的另一种方法是:什么样的阻碍因素会让你对阅读一组文档失去兴趣？
答案:
回顾一下答案之间反复出现的一些主题:
最佳答案
许多公司似乎没有意识到文档的重要性。
编写文档是我工作的重要组成部分。这是没有人想要的工作，但它至少与开发团队中的任何其他人一样重要。当我使用各种语言和工具工作时，我越来越意识到这一点，并经历了糟糕或不存在的文档的痛苦和好文档的乐趣。
最重要的事情:
规范:
我讨厌 java API 文档几乎没有示例这一事实。几乎可以查找任何类(class)或方法，以及 nada，甚至不是一个类轮。在大多数情况下，并不是说一个类轮就足够了，但他们甚至都不会为此烦恼。
关于documentation - 什么是好的在线文档？，我们在Stack Overflow上找到一个类似的问题： https://stackoverflow.com/questions/477502/