[Fwd: Re: [Koha] Koha Documentation Project]

[Joshua Ferraro]

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