[OPEN-ILS-DOCUMENTATION] documented developmnt

[Lori Bowen Ayre]

"Man Pages" +++  I recall them quite fondly from my old Unix admin days!

Lori

On Wed, Feb 9, 2011 at 2:21 PM, Sharp, Chris <csharp at georgialibraries.org>wrote:

> Regarding this:
>
> > > I think a distinction should be made here between documenting
> > > workflows and documenting functionality. Take the Booking Module, for
> example.
> >
> > Yes, functionality (all the things you could possibly do) is broader
> > than workflows, but based on my experiences at IBM talking with
> > customers who worked with the documentation that my information
> > development department wrote, their priority was to answer the
> > question "How do I do X?". They didn't want to be told that there are 10
> > different ways you could do X, and here are all the different ways you
> > can configure the system to support those different ways, they wanted
> > to follow the beaten path as much as possible so that they could get
> > their jobs done as efficiently as possible and run into as few edge-case
> > bugs as possible.
>
> As a technical (but non-developer) user, I would like to see Evergreen "man
> pages" (term from Unix/Linux - see here:
> http://en.wikipedia.org/wiki/Man_page ) - or some equivalent - that would
> describe functionality, not just specific workflows.  I've been
> investigating the SIP Server we all use for third-party products and it
> includes a very useful set of documentation with it (in POD ("plain old
> documentaion") format, but it can be transformed into man page-type
> documentation in plain text or HTML or even DocBook format with a single
> command), which could serve as an example (see
> https://github.com/atz/SIPServer ).  This is the sort of documentation
> that only developers (or those with a code-level knowledge of Evergreen)
> could write, but would be incredibly valuable for the sys-admin class of
> users who otherwise resort to having to search the code for what we *think*
> might be the correct designation for what we're looking for.  This would
> probably go beyond what the majority of the DIG volunteer membership (who do
> a bang up job of end user documentation) would be technically capable of, so
> I'm not sure it would be a DIG project.  I'm trying to get enough Perl,
> JavaScript, SQL, etc. knowledge under my own belt to understand things at
> this level, and would be happy to contribute, but much of this would need to
> come directly from the code's authors, IHMO.
>
> I just wanted to mention this need in the midst of this discussion.
>
> --
> Chris Sharp
> PINES Program Manager
> Georgia Public Library Service
> 1800 Century Place, Suite 150
> Atlanta, Georgia 30345
> (404) 235-7147
> csharp at georgialibraries.org
> http://pines.georgialibraries.org/
> _______________________________________________
> OPEN-ILS-DOCUMENTATION mailing list
> OPEN-ILS-DOCUMENTATION at list.georgialibraries.org
> http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation
>



-- 

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-==-=-=-=-=-=-=-=-=
Lori Bowen Ayre // Library Technology Consultant
The Galecia Group // www.galecia.com
(707) 763-6869 // Lori.Ayre at galecia.com

<Lori.Ayre at galecia.com>Specializing in open source ILS solutions, RFID,
filtering,
workflow optimization, and materials handling
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://list.georgialibraries.org/pipermail/open-ils-documentation/attachments/20110209/9dfb9903/attachment.htm