什么是好的在线文档？ [英] What is Good Online Documentation?
问题描述
Disclamer：
虽然这个问题有自私的起源（我正在撰写文档，并且自然希望它是最好的），我相信其他人可以利用答案。另外，虽然文档不是编程，但我仍然认为这是适合的问题，因为你需要编写东西，如果你编程的东西。
详细说明：
此问题适用于在线文档，因为我认为 tome in 1500-somet pages 以及网页/网站的动态。
假设有一个新的令人兴奋的服务器叫WhizBangDaemon，你几乎没有任何意见，你已经决定在业余时间尝试学习。应该有什么样的部分，文档有用和有趣，并让您阅读它？
请随时提供良好的现有示例的链接，以及为什么你喜欢他们的解释。
这个问题的另一种方法是：什么样的showstoppers使您对阅读一组文档失去兴趣？ em>
答案：
答案之间的重复主题：
- 快速浏览
- 简介文字/教程/例子
- 不仅仅是API文档
- 零件（可能与第一点有关）
- 简明扼要
- 搜索工具
- #anchors进行链接
- 可下载可用的
许多成功的开源项目表明，看起来像。
有些方面是：
- 最新。如果文档是
不是最新的，那么它可以成为
a show stop。 - 许多在线文档以$ b $开头b一些简短的教程。他们从软件中显示一些
的关键方面，并保持
，用户感觉更有兴趣挖掘
。 - HowTos或常见问题常常非常有用。
许多用户选择不阅读
文档，只是尝试一下。
在某些时候，用户很可能一次又一次地要求
相同的问题。 Be
知道用户可能会要求什么以及
他们已经要求的内容。 - 对于感兴趣的用户，请提供
一些详细信息一个核心文档。 - 还要考虑考虑文档的
受众。作为一个
的文档作者，我认为这是
非常有用，以清楚地说明
哪些受众的文档是
，以及他们的
应该有哪些知识。这迫使我
具体和简洁。这样
我可能最终将不同的
部分中的
文档分开，这使得文档
非常结构化。
如果您已经有一个1500页的东西文档，您可以围绕一些教程，HowTos和常见问题解答，并且可以调用文档。当软件发展时，您可以将核心文档重构更易于阅读。
最困难的部分是保持文档最新。写下文档以备将来的变化。
What does it take for online documentation to be helpful and interesting to read?
Disclamer: While this question has selfish origins (I'm writing documentation, and, naturally, want it to be the best one out there), I'm sure other people can take avantage of the answers. Additionally, while documentation isn't programming, I still think it's suitable to ask this here, as you need to document stuff if you program stuff.
Elaboration: This question is specific for online documentation, because I think there is a great difference between a tome in 1500-something pages and the dynamics of a webpage/website.
Assuming there's a new and exciting server called WhizBangDaemon which you know pretty much nothing about, and you have decided to try and learn it on your spare time. What kind of sections should there be, for the documentation to be helpful and interesting enough and to keep you reading it?
Please feel free to provide links to good existing examples, and explanations to why you like them.
Another approach to this question is: What kind of showstoppers make you lose interest in reading a set of documentation?
Answers:
Recapping some recurring themes between answers:
- fast browsing
- introductionary text / tutorials / examples
- not just API documentation
- divided into many small parts (could be related to the first point)
- concise and to the point
- search facilities
- #anchors for linking
- downloadable format available
Many successful open source projects demonstrate how good online documentation can look like.
Some aspects are:
- Up to date. If the documentation is not up to date anymore, it may become a show stopper.
- Many online documentations begin with some short tutorial. They show some key aspects from the software and keep the user aware and interested to dig deeper.
- Often HowTos or FAQs are very useful. Many users choose not to read documentations and just try it out. At some point the users are very likely to ask the same question over and over again. Be aware what the users may ask for and what they already have asked for.
- For the interested users, provide some in detailed information in a core documentation.
- Also consider to think about the audience of the documentation. As an author of documentation, I think it’s very useful to clearly state for which audience the documentation is for and what kind of knowledge they should already have. This forces me to be specific and concise. This way I may end up separating the documentation in different distinct parts, which makes the documentation very structured.
If you already have a "1500-something pages tome like" documentation, you can wrap around some tutorials, HowTos and FAQs and that would spice up the documentation. When the software evolves, you can refactor the core documentation to a more readability.
The most hard part is to keep the documentation up to date. Write the documentation with future changes in mind.
这篇关于什么是好的在线文档？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
