I use a lot of free and open source libraries, and the main problem I find with them is documentation. Strangely, it's rarely that there's a lack of documentation, but more commonly that the documentation provided is inadequate.

The typical incarnation of this is where someone has processed their entire source code with Doxygen or something like that, in the almost completely misfounded belief that an unordered list of function names and objects is enough information to get started. It is much like giving someone 100 identical keys when they ask how to unlock a certain door. Why make them dig through the whole lot? Anyone with a decent IDE (or a reasonable command of their toolchain) can look up function names and parameters in seconds anyway. Providing an HTML interface to it all seems largely pointless unless you're going to add value with diagrams and so on.

Today I came across something less common - the opposite extreme, where the authors have gone to lengths to ensure that you have an easy and well-worded tutorial, yet have seemingly forgotten to provide any sort of useful reference that doesn't involve reading a long block of prose. My culprit for today is the Lua documentation. The reference manual is okay, but feels disorganised. To find something within, you have to look at the table of contents, pick a likely-looking topic, and hope for the best. I wanted to put one table inside another using the C API, and had to chase around several sections before discovering that what I needed was elsewhere on the web. Lua also has a lot of very helpful functions in the auxiliary library, which aren't documented properly anyway. This is somewhat ridiculous as they make life so much easier, but I digress. There is not even an index where you can look up function names to see exactly what they do. So whereas other documentation drowns you in detail and leaves out the big picture, the Lua docs give you their big picture but don't tell you the details of how to draw your own picture.

So, what do I think documentation needs? It's quite simple:

1) Tutorial/Overview. I want to be told what the software does, and ideally be given some short sample code illustrating exactly how it does it. Talk me through it line by line, so I get a feel for the interface, and can see how I might modify it to suit my needs.

2) Hierarchical description. Give me a table of contents where the functions and classes are described, arranged according to sensible groupings of functionality. This allows me to translate a task in my head to a relevant section of the documentation. No function or class should be omitted, least of all convenience functions. No function should be described without an example. Even if that example is just an uncompilable snippet, it's still better to see it in context. All functions and classes in a section should be summarised together at the start of that section with a one-line description for each. You should be able to drill down from the top level (seeing which module you want) to the sub-section (seeing which function you want) to the individual function (seeing which parameters you need). Feel free to generate this automatically from the code providing there is a clear and obvious hierarchy. Most automatic doc-generators do not do this at all. (Or perhaps I should say that nobody is using them in such a way.)

3) Index. After a while I will vaguely know about the existence of functions or objects but will not know precisely what they do. I may have a rough idea that they might be useful to me, or I might just be interested in finding out for future reference. But if I don't know what they do, I cannot look them up in the table of contents. So an alphabetical index is vital. Don't make me wade through your tutorial again to find the one place where you used that function.