Equinox Blog

Next week I’m going to close out the FUDBuster series — for now, anyway — with the FUDdiest FUD we’ve heard about Evergreen (you can’t place holds, anyone can edit a cataloging record, it’s only for very large installations, etc.). I want to move on to a new series based on Evergreen’s functionalities.

But today’s FUDBuster is a little different: not all FUD is FUD.

This isn’t going to turn into a weepy expiation of everything wrong with Evergreen or OSS. If you know of a perfect software program or design model, please do tell.

Evergreen has its strengths and its growing edges, just like anything else. This blog tends to focus on its strengths — some related to the nature of OSS, some due to its architecture, some due to the people involved in its development — and who can blame us? Creating and growing a product such as Evergreen is quite an achievement for all concerned — GPLS, PINES, the original developers, and everyone else who has since become involved.

I even like alphabetical order

But sometimes stereotypes do often hit uncomfortably close to home. (For example, I own many pairs of sensible shoes, and I also have cats. Livin’ the Library Life!) One stereotype that’s true more often than I’d like to admit is that OSS is poorly documented.

Last week I waged major battle with a piece of OSS (not library-related). The documentation was…and this is charitable…sparse and haphazard. I really wanted to work with this product for a variety of reasons — I could even buy commercial support for it at a very decent price — but the lack of documentation was one of several nails in this product’s coffin, at least for now.

Sometimes documentation is more important than other times. I confess I didn’t look at the Evergreen public catalog documentation until I decided to research all the capabilities of bookbags. I didn’t need to. I’ve been able to search, browse, find, and hold items without asking how to do this, and not, I believe, due to my magical librarian skills, but because the Evergreen catalog is easy to use.

But we do need more documentation for some of our services — reporting comes to mind — and moving forward, we know we also need to ensure we always incorporate documentation into the development process. Plus documentation should also help surface functions that might not be obvious; I intuited more about bookbags that was actually documented — such as the ability to subscribe by RSS — but not everyone might recognize that orange RSS icon. I’ll be writing about holds soon, to illuminate some of their hidden power.

In the end, documentation doesn’t write itself any more than laundry washes itself, and though it’s unsexy and a bit of a slog to produce (also not unlike laundry), it needs to be done.

Prepare Ye the Way

Fortunately, we’re able to address documentation this summer and fall through a grant from the Mellon Foundation that’s specifically targeted at documentation in Evergreen. We’re not putting documentation on our “round tuit” list to be gotten to eventually; we’re not waiting for it to grow on trees, or to float by our river on a lilypad. We’re getting ‘er done, we are, with real resources dedicated to this effort — and then, as is required by all good documentation, we’ll shampoo, rinse, and repeat indefinitely, and integrate documentation into the development process. It won’t happen any other way.

I will say that it’s easier to add documentation to good software than to add good software to documentation. But — not without some lessons-learned — we recognize the two go hand in hand!

– Karen, Equinox Community Librarian

Bookmark to:

This entry was posted on Tuesday, August 12th, 2008 at 5:29 am and is filed under FUDbusters. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.