What is Good Online Documentation?

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

• The ability to submit comments is useful, as that can capture documentation written from a different perspective, or ideas you had not thought of originally.
• If you've the time to allow for checking the changes to wiki-style of documentation, that can reap similar dividends also.
• good search facility
• plenty of #bookmark anchor points in long pages, which allows sections to be easily referenced in sites like this
• using a flexible format like DocBook allow the manual to be rendered in a variety of ways, like HTML, PDF, CHM etc.

Answer 2

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.

Answer 3

I think PHP has the best online documentation for a language.

If there's a function that I don't know the use for, I would go to php.net/function-name.

For example, if I am looking for the function debug_backtrace, I would visit php.net/debug_backtrace. If I mispelled the function name or it doesn't exist, the site would try its best to find the correct function and redirect you there. Failing that, it will show you a search on PHP's function that is the closest to the function you are looking for.

Answer 4

Divide the information, some people that might want to try your product may very well want to only see tutorials or examples, pretty short examples I mean.

On the other hand, somebody that already bought your product wants to make out most of it so create a full API specification with indexes and search capabilities, link the information between pages, add some samples for the API and dont just add what the parameters receive and what the method/function returns etc. Of course that in the case that you sell something for programmers.

Give real world examples!! Dont just add reference information but code examples or real work environment examples that can be useful for someone who will apply your software to be productive and complete a task and not just to learn.

Thats what I look for on documentation, if it has those then I'll buy it ;)

Answer 5

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.

Answer 6

Django's documentation is pretty amazing (http://docs.djangoproject.com/), its quite comprehensive and easy to read and makes it quick to find what you need.

• Concise text (not much reading needed, thus less time reading docs)
• Good examples
• Quick find what you're looking for (without needing a search engine but as in a great index page)

Answer 7

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 8

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 9

Personal pet hate: projects which run doxygen over their headers and think the documentation is done. You absolutely need introductory material... tutorials, working (preferably standalone) code samples, an overview to point you at the most important classes in the reference documentation. Qt is one of the best examples of this done well IMHO.

Also, be sure to provide a decent search facility (even if only a redirect to a site-specific google search). This is one reason for me preferring MS .chm file docs to web-hosted online manuals sometimes.

Answer 10

Lots of minimal code samples. One per task. Identify the top 5 tasks; Make it a no-brainer to copy/paste their implementation from your docs and compile it. Yes, I'll come back and read the actual explanations. I want to see some meat first.

This makes a lot of difference when evaluating libraries. I still don't know what Adobe Adam&Eve is really about.

Answer 11

A lot of companies don't seem to realize how important doc is.

Writing documentation is a big part of my job. It's the job nobody wants, but it's at least as important as any other on the development team. I realized this more and more as I have worked with various languages and tools and experienced the pain of poor or non-existent doc and the joys of good doc.

The most important things:

1. Be clear and concise
2. A good example is worth a thousand words
3. Useful examples (not the same as #2 )
4. Add examples of stuff a typical user/most user would want to/need to do with whatever you're documenting.
5. Have I mentioned examples?

Specifics: I hate the fact that the java API docs have virtually no examples. Look up practically any class or method, and nada, not even a one liner. Not that a one liner is sufficient in most cases, but they couldn't even be bothered with that.

Answer 12

Online documentation (at least the canonical standard version of it) needs to be short and concise. But then the canonical version of all documentation needs to be short and concise, so for me online documentation just needs to duplicate the canon.

I'm particularly unhappy with the assumption behind the statement in the question about a “1500-something pages tome like” xpectation for good printed versions. To me, that's not a good example of any kind of documentation short of an encyclopedia.

And it needs to be downloadable, because that's where I like my documentation to be - on my laptop, readily available wherever I am.

Notice that so far there have been few proposed consensus examples of good documentation. Consider whether the complexity of the features listed in the answers isn't working against the feasibility of doing it that way in the first place. All that stuff is great in some context, but when that's supposed to be the primary source it's all too overwhelming (and impossible to keep current and internally consistent.

Yes, I'm old enough to prefer unix man pages. Start with those, and I'll take (or not) the rest of it when and if I need or want it.

Answer 13

In my opinion, you should think in simple about that. You can also install any wiki software or try to rent from some hosting company and create your own documentation without any limitation.

Free for example : screwturn

Answer 14

Good documentation should be skimmable. It has to be written from a point of view that 90% of your users will not be willing to read more than 10% of the material. There's always a disconnect between the author who is focused on writing something good and the reader who just wants to get things down.

Use any trick in the book to make the most critical information highly visible. Especially warnings or instructions.