[OPEN-ILS-GENERAL] Writing an Evergreen manual

Tue Oct 9 14:48:45 EDT 2007

Hi All -

Below is a suggestion from the Open-ILS DEV thread about documentation, and my comments on that.

>From Open-ILS-Dev:

-----Original Message-----
From: open-ils-dev-bounces at list.georgialibraries.org [mailto:open-ils-dev-bounces at list.georgialibraries.org] On Behalf Of Kardos Andris
Sent: Tuesday, October 09, 2007 2:12 PM
To: open-ils-dev at list.georgialibraries.org
Subject: [OPEN-ILS-DEV] documentation

Hello Everyone,

A complete overview of what actually Evergreen does, should be part of

the docs. For example I was surprised, that there is no interface for

authority control in Evergreen. How do you do it then? Also good

overview of import options, with examples, MARC field numbers, etc.

Thanks! Maybe you should first collect the questions - and then answer

those in the docs.

András Kardos

András - I agree that it's a good idea to cover what EG is used for, and collect questions that should be covered in the documentation- documenting useful areas is definitely important.  Since this is a community effort, I see no problem with dealing with different components of the EG manual concurently - I'm primarily interested in the staff client, and day-to-day use thereof (getting started, logging in, adding/editing patrons, checkin/checkout, billing, reporting, etc...) - obviously, we need to have the manual cover other areas as well.

Maybe a 'documentation bounty' section should be added to the Wiki under the "Evergreen Manual" section - here, we can add questions like the ones above.  For people who want to contribute to the document, this would be a great place for them to see what is needed, and for others, adding questions and identifying areas that need to be documented is also a good way to help.  I'm thinking that when someone submits documentation for one of those areas that is entered into the manual repository, we can cross it off in the Wiki as it gets checked into the database - that way, we can all see easily what's already been included, too.  Sort of like an FAQ that is used to identify areas that need to go into the formal documentation.  

Thoughts, anyone?

Some say the world will end in fire and ice.  Others say it will be segfaults.

  _____  

From: open-ils-general-bounces at list.georgialibraries.org [mailto:open-ils-general-bounces at list.georgialibraries.org] On Behalf Of Murphy, Sally
Sent: Tuesday, October 09, 2007 1:16 PM
To: open-ils-general at list.georgialibraries.org
Subject: RE: [OPEN-ILS-GENERAL] Writing an Evergreen manual

Good idea, but lets wait on that until we have something started, documentation-wise, before gettin' all crazy.  I don't know about you, but I tend to stall when projects get too much cool, but ultimately peripheral, tasks added to them.  And documentation really shouldn't stall any more.  I'd be happy if we just had a sample up and a documented procedure for submitting documentation.  

An Evergreen committer should, of course, have final say over how we go about submitting pieces to the manual, otherwise, I'd go ahead and put those instructions I suggested up on the Wiki.  Either way, though, I'd really like to get started on some manual-writing, so let's get on this thing! =)

-Murph

Some say the world will end in fire and ice.  Others say it will be segfaults.

-----Original Message-----
From: open-ils-general-bounces at list.georgialibraries.org [mailto:open-ils-general-bounces at list.georgialibraries.org] On Behalf Of Etheridge, Jason - Gmail
Sent: Tuesday, October 09, 2007 12:15 PM
To: open-ils-general at list.georgialibraries.org
Subject: Re: [OPEN-ILS-GENERAL] Writing an Evergreen manual

On 10/9/07, Murphy, Sally <smurphy at georgialibraries.org> wrote:

> Also, what kind of support does doc books have for graphics, and formatting

> pages with them?  Focusing on end-user stuff, there will be lots of

> screenshots, diagrams of menus, pictures of icons, and such.

Thinking along those lines, it would be great if the documentation

framework could optionally alert folks when there are pertinent

changes to the source code.  For example, if you have a screenshot of

the Item Status staff interface, perhaps the framework could associate

it with an RSS feed of the changelog for the corrresponding XUL and

CSS files, and flag anything that might require a new screenshot

(maybe we could require that commiters embed a magical keyword into

the changelog like DOC_UPDATE_NEEDED).  If a documenter doesn't know

anything about internals, then no biggie, just no magic until someone

else comes along and adds the pertinent meta-data.

Or am I overthinking this and it would just be too complicated to get

something like that working? :)

-- 

Jason Etheridge

 | VP, Community Support and Advocacy

 | Equinox Software, Inc. / The Evergreen Experts

 | phone:  1-877-OPEN-ILS (673-6457)

 | email:  jason at esilibrary.com

 | web:  http://www.esilibrary.com

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://list.georgialibraries.org/pipermail/open-ils-general/attachments/20071009/ef256565/attachment.html