What is Good Online Documentation? [closed]

Question

Closed. This question is opinion-based. It is not currently accepting answers.

---

Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.

Closed 2 years ago.

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

Answer 1

I agree with lots of other posters here, two things that are not really content but that are very important to me:

• it has to be FAST - both normal browsing and searching
• it has be be linkable, I want to be able to send someone a link to a specific part of the documentation

As a negative example: http://livedocs.adobe.com always feels slow and lots of the time it's not linkable :-(

PS: and providing a downloadable version for offline use is always nice.

Answer 2

What I really don't like is MSDN docs format. I do prefer JAVA Sun documentation style, Flex 3 Livedocs (http://livedocs.adobe.com/flex/3/langref/) and PHP too.

Answer 3

Good documentation should explain "why", not just "what". Why would I want to use this feature? What scenarios is it good for?

That, and it must have good search facilities.