Hi I changed the subject header and focussing here on your last point "solid foundation in Linux commands" needed with present documentation and "documentation easy enough for a person with average technical skills to follow" as desideratum:
your observation is echoed in what came out of the eIFL FOSS ILS implementation project (both Koha and Evergreen) that recently published it's case studies [1] [actual cases - including learning points ! - available at the very end of this longish page] : ".. From June 2008 to the present, each of the pilot sites has committed considerable effort to investigating their chosen FOSS ILS. In some cases this entailed significant challenges in terms of key skills (e.g. needing to learn Linux systems administration first before proceeding) or environmental factors (e.g. a number of sites experienced periods of severe infrastructure breakdown over the course of their piloting efforts). Learning to fully engage with FOSS development and support communities was equally challenging. And some technical challenges were (or have been so far) insurmountable. .." With this observation on prerequisite skills made, DIG nevertheless needs to be practical I think (limited resources, limited time) - suggestions: - roughly define "average technical skills" and write / review for that target group: the libraries in the fore-mentioned case studies would be excellent reviewers - shop around for open access Linux course material and refer to some of this stuff in the Evergreen documentation - like "before you proceed please familiarise your self with .. and point to some Linux skills course material on the web [or include it if it has a CC licence]" - some combination of the above two Yours, Repke (this time with my eIFL FOSS cap [though Greenstone; Tigran Zargaryan is the ILS project coordinator]) [1] http://www.eifl.net/cps/sections/services/eifl-foss/ils/case- studies Op 24-sep-2009, om 17:34 heeft Roma Matott het volgende geschreven: > Hi - > > I haven't added any notes yet. To be honest, the process of making > notes of the upgrade process generated a lot of questions about how > the technical side should be documented. > The upgrade was a two step process for me - I had to upgrade > OpenSRF and Evergreen. The instructions for upgrading OpenSRF > seemed to be more if you were installing the software from scratch > than an upgrade. So, below is what was running through my mind: > > Question 1: How do we determine what to document? Do I document a > separate page for if you are upgrading OpenSRF? Or do I amend the > current documentation so that it is clear that some steps only > relate to a new install? > > Question 2: I am using Ubuntu 8.10, so my commands were (very) > slightly different. Do I just state that these instructions are > for Ubuntu operating system and hope that if someone is using > Debian they know the difference? Or do I add the different > commands in the same step indicating which operation system they > are for? I guess, the underlying question here is should we only > be documenting in the preferred/most widely used os or should we > try to accommodate both? > > While the current documentation is good, I do think it requires > that the user has a solid foundation in Linux commands. I might be > over thinking this, but I would like to create documentation that > is easy enough for a person with average technical skills to > follow. I have the feeling that this is important for the growth > of the Evergreen community. So, if anyone has any thoughts on > this, please share! > > Roma > Systems Librarian > Pioneer Library System > Canandiagua, NY _______________________________________________ OPEN-ILS-DOCUMENTATION mailing list [email protected] http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation
