I missed the Koha IRC meeting due to a really unfortunate miscalculation of 1900 GMT, so I didn't get a chance to chime in on the documentation discussion...
The original manual covered Sysadmins (mainly install, when parameters were much simpler) and staff, and developers (we had a handy chunk of why/how-stuff-is-done info -- some architectural info for presentation/explanation wouldn't hurt either -- never occured to me until recently how hard it was to explain some of the webserver/perl/db potential issues etc until I looked over some of the more typical questions). Here's the current index of the sysadmin guide that I've been working on: (I'm hoping for feedback ... so if you see something you don't like or you don't see something that should be included let me know)
Koha Systems Administrator Guide Introduction Further Reading and Resources Part I: Installation and Migration Introduction hardware software 1: Installing Koha on Debian (jferraro) 2: Installing Koha on Redhat AS (shedges) 3: Installing Koha on Fedora (jferraro) 4: Migrating to Koha (shedges) 5: Customizing Koha's Template System (oleonard) Part II: Maintenance and Troubleshooting 6: Updating Koha setting up a testing environment(jferraro) setting up CVS symlinks(jferraro) tracking arch (mjr) 7: Backups (jferraro) backing up and restoring the database role of replication as backup backing up and restoring the filesystem 8: Optimization (jferraro) optimizing MySQL load balancing with replication 9: Troubleshooting (jferraro) Koha's error reporting database corruption worst-case scenario: utilizing the statistics table Part III: Participating in the Koha Community 10: Communicating with the developers(jferraro) mailing lists IRC Wiki 11: Reporting Bugs (jferraro) 12: Submitting Code (jferraro) 13: Koha Translating (??) Part IV: Introduction to Libraries for Sysadmins 14: haven't given this much thought but we need a section on MARC. Appendix: Installing the Z3950 Server (jferraro) Cleaning up the issues data (shedges) Renewals (shedges) Reserves (shedges) Handling Overdue Items (shedges) MJ suggested part IV, "introduction to libraries for sysadmins" which would be a great addition but we need someone to write it ... So the initial draft of this document is slated to be released on Monday or Tuesday of next week (in time for OLC annual) but not all the above chapters will be finished by then :-).
Also needed, and always a problem, is work re the FAQ and troubleshooting info -- come to think of it, some newer hardware recommendations wouldn't be amiss (CMSD I think gave us their original specs). Thoughts? I've slid a hardware section into the intro of Part I ... great idea!
I'm thinking MARC and associated questions will need special handling. Possibly a "Cataloging In Brief" for the MARC-uncomfy... also, some wise words on tags wouldn't kill us. That'd fit nicely into the "introduction to libraries for sysadmins" part ... anyone want to write it?
Ditto something on translating. If someone writes it that'd be a great addition too (ch 13 in the above scheme).
In the past (formal) docs have been in DocBook SGML/XML.... advantage here is that it permits easy multi-format output, and is relatively easy to translate the raw XML for other languages (we successfully handed the file over to people with them returning translations of stuff between tags). And gives a nice, clean look and feel. Opinions? I've never used DocBook but from what I've heard it's a good medium ... I'll check it out this weekend if I have time. I've been thinking that it might be a good idea to use a Wiki for at least the initial editing of the document (so that any of us can make changes/additions to the content) and then when we're all satisfied we can move the text to more universal formats (maybe through Docbook) ... how does that sound?
Flames, comments, suggestions: all welcome. Thanks, Joshua