Resource review #2: official Koha documentation

Koha Development Team. (n.d.). Documentation. Retreived from http://koha.org/documentation.

This is what I love about the Internet: within a day or so of me writing a blog post that was longer on frustration than research, someone who knows better (in this case, one of the documentation developers for Koha) drops by and gently points out my misrepresentation. Basically, “I’ve just spent several hours looking for information on a very specific problem that I, who am totally not qualified to be a system administrator, can actually understand” is not the same thing as “the documentation sucks.” So, as a sort of mea culpa, I present a resource review of the official Koha documentation.

As far as I know, our Koha install was never really configured for anything (largely because we aren’t really using it for anything except our own amusement), so I sat down and started to work through the Koha 3.0 manual start to finish. (Naturally I got bored partway through, so I didn’t get the whole thing, but I did look at at least part of each section.) There’s a lot of example data already installed on our system, but I didn’t like it for my demos, so I figured I might as well input some of my own while I figured out what was going on.

One thing I liked about the manual is that it’s fairly redundant — a lot of what it covers is explained in slightly less detail in the program itself, particularly in the settings region. This is good in documentation, it means you don’t have to read the manual cover to cover and you can be reasonably assured that it does what it says it’s going to do. It even points out the places where you really, really have to work through something in exactly this order if you expect it to work at all, which is convenient. There’s also a BUG notification for settings which still have some kinks to be worked out; I wished the bug notice linked to a more detailed description of what the problem was, but it’s good to know when there’s something that’s not quite fully functional.

When I gave up on setting up administration and OPAC settings, I moved into the patron setup and cataloging areas. (There’s a setting that basically allows you to bypass acquisitions, which is handy for those of us who aren’t actually acquiring anything.) This was where I started to be properly impressed by the manual, since I have that Technology Geek disease where I won’t read the manual unless I’ve already spent half an hour incapable of figuring it out on my own, but usually it doesn’t take me half an hour to figure it out, so usually I don’t need the manual at all. Still the case here, but when I did check the manual, it provided me with some shortcuts I wouldn’t have figured out too quickly myself and I had no problems finding the sections immediately relevant to what I was doing.

There’s a slight over-reliance on default settings in the manual, I think; because some of our system wasn’t using defaults, there were places where the manual assumed things that I simply wasn’t seeing. I had no problem figuring it out, but there are people who would. Overall, though, I will cheerfully retract my statement that the Koha documentation sucks. The installation documentation is a little thin for those of us with less Linux and system administration experience, certainly, but the manual for day-to-day use is very nice indeed.

In addition to the manual, there’s quite a lot of other documentation, which I haven’t had a chance to look at while playing with the software, but I like the look of it. There are how-tos, step-by-step instructions for common tasks (including how to contribute one of your own); detailed tutorials; and a long list of Frequently Asked Questions. To be honest, I’m not sure what the difference is between how-tos and tutorials, and neither of those sections have very much content at the moment, although of course they’ll expand as more people contribute. The FAQs cover common problems, many relating to issues having to do with how the system settings are applied, which are probably handy for administrators who have permissions to change settings but might be frustrating for people who don’t. Overall, it looks like the actual manual is probably the best resource for staff working with the system on a day-to-day basis, and the other documentation will be most helpful for the sysadmins and others with more complete control over the Koha system.