Alex Rivera | Logout

What is Good Online Documentation?

Asked 2009-01-25T10:28:38.333
17

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
documentation
Edit
Report

1 Answer

2

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.

answered 2009-01-25T17:49:21.273

Your Answer