Online documentation pains
Posted at 20:00 on 11 August 2006
When I'm learning new programming languages, concepts and things, I like to have the documentation available for download as a self-contained unit that I can refer to on my computer, rather than having to connect to the Internet to browse through it all online.
There are various reasons for this. The first is speed: since many APIs are overwhelmingly humungous these days, a quick, easy to use search facility and straightforward overviews and walkthroughs are a must. A .chm file is the best option -- you can search it quickly and easily, and it usually doesn't take more than a few seconds to find what you're looking for. Individual HTML pages are not quite so good though, since searching is less straightforward. And accessing something on your hard disk is much faster than surfing the web, due to network latency and other similar factors.
Secondly, I prefer to spend the bulk of my time offline to help eliminate distractions. I'm not saying you should work offline exclusively: I have found a lot of help from online resources such as the ASP.NET forums, experts' blogs, tutorials and the like. However, I do like to be disconnected from the Internet when I'm trying to work my way through some tricky problems. It helps to reduce distractions such as those Wikipedia loops that it's so easy to get into -- you know the kind of thing I mean, where you end up clicking on one interesting looking link after another for a while and suddenly realise that you've spent two hours reading a whole lot of total drivel and completely forgotten what you went online for in the first place.
Furthermore, at present at least, we still only have dial-up connectivity to the Internet at home rather than broadband, so going online is slow and cumbersome, though hopefully this will all change after we move house at the end of this month.
A lot of programming languages and platforms do quite well in this respect. The .net framework is a good example: the SDK documentation comes with examples, quickstarts, howtos and API specifications that you can install on your computer to refer to as and when you need it. PHP and Python are also pretty good, with comprehensive, searchable, easy to follow documentation available for download in CHM format.
Java is a bit more awkward. You can download the J2SE and the J2EE documentation, but they are a bit more fragmented, and contain a lot of links back to the web -- in particular, from J2EE stuff to J2SE stuff, which is a little bit annoying. I've also found Ruby on Rails pretty frustrating. It would be great to have one download that covers both Rails and the Ruby core API, rather than having to go online all over the place, but there isn't one. You can get a number of CHM files, but they seem to be strewn all over the place and don't cover everything. This is a real shame, because I would love to be able to get my teeth into Rails in my spare time, and it seems that you can't do that quite so effectively offline.
Still, at least the documentation is comprehensible and reasonably structured, which is a lot more than can be said for Perl. I really, really hate the Perl documentation. Look at the index, for starters -- a list of cryptic, obfuscated and sometimes downright misleading names such as perlboot, perltoot, perllol, perlre, perlrun, perlpod. I can just about make sense of it, but it takes twice as long to find what you're looking for as anywhere else. To a beginner, it is probably the most confusing, incomprehensible and intimidating mess you are ever likely to encounter.