[OPEN-ILS-DOCUMENTATION] Need for solid foundation in Linux commands Re: Where to put reviewers notes .. Re: Evergreen DIG Test Server Available

[Repke de Vries]

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