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

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 2

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 3

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 4

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.

Answer 5

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 6

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.