Question

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

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.