Documentation Hell
With leaving UH in January, one big thing that I have to get done is writing better documentation for systems that we’ve implemented. The process is exceptionally tedious but kind of interesting because it makes me realize:
- All the systems I’ve implemented here
- All the stuff I’ve learned in the last 4 years
- Which library OSS has good documentation and which is lacking
Another thing I’m looking at is how systems we’ve implemented are put together. Sometimes the systems are designed to nicely separated local customizations from core code, sometimes not (LibStats, LibraryFind). Sometimes this is half implemented (cough, Archon).
The irony is that some of the stuff I’m documenting is stuff I was going to have to write about for the Resource Discovery Tools portion of the book. So lucky for me the work is going to serve double-duty!
Seriously though, documentation is one place where OSS and techies often fall down. It is much more fun to build stuff then write about what you’ve built. So you really, really have to get your techies in the habit of writing stuff down. Otherwise, well, there comes a time when the coding stops and the writing starts until its put together. If I had to do it again, I’d schedule once a week documentation writing time for all my staff. Definitely going to suggest that to my boss and the interim department head.
The greatest irony of all is that in my new job, I’m having to learn things from my boss, who ironically doesn’t have documentation. So you can guess what my first major assignment is? Yeah, documentation. Guess its good that most of the time I like writing about how to do stuff. Still, the process of putting it all together can wear one down. So, I’m taking breaks and eating cupcakes as a reward for completing sections.
I hear things about Open Source having bad, or non-existent, documentation an awful lot. It makes me cringe every time. This is not something that is Open Source specific: Software has bad or non-existent documentation. Open Source has nothing to do with it… except with Open Source you can look at the code if you need to figure out something you can’t. That isn’t an option with closed, proprietary software. I admit some Open Source programs have bad or almost non-existent documentation. However, I have seen worse, and less, documentation on numerous proprietary applications that organizations I’ve worked for have paid signification acquisition, support, and licensing fees for.
Ed,
I agree. Proprietary software can have bad or non-existent documentation too. However, my experience has been that not having documentation for a particular open source application has been more painful to deal with. Maybe that is because with proprietary software you can call the vendor.
Being able to look at the code is great for figuring stuff out, if you know what you’re looking at. But not everyone has enough technical background to glean anything useful from this. So I’m not sure for those folks if open source software is really better than proprietary software.
That being said I will say the documentation I’ve been happiest with because I think it hits the entire spectrum of users is WordPress’s. I wish that more projects had the community, ability and wherewithall to create this kind of documentation. It would make life much easier for implementers and maintainers.
This is been my greatest fear if I ever leave my current position. I document, but I always fear the next person might not grasp it.
Oi. Welcome to last few months at the UH Libraries. It’s a strangely satisfying feeling knowing you have so much information/documentation to pass one, but it isn’t necessarily the most entertaining project. Cupcakes sound like an excellent reward.
We are currently trying to determine what is the best thing to document in Google Docs, Ning, a local wiki? Karen – do you have a preference or something you have found to be the best?
We’re using PMWiki at UH and I like that a great deal because it doesn’t require a database to run and is very very easier to use. GoogleDocs is cool too but a pain if you’re organization doesn’t have Google Apps because you have to have everyone get a Google Account.