[OPEN-ILS-DOCUMENTATION] documented developmnt

[Sharp, Chris]

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/