[OPEN-ILS-DOCUMENTATION] Documentation Reorganization Discussion for 2.2

[Turner, Jennifer M]

Robert, 

I like your proposed outline. The order of existing Evergreen documentation has bothered me for a while now; I just hadn't taken the time to propose an alternative! 

I do have a couple of quick comments:
1) Serials should be listed as a heading similar to Acquisitions, Cataloging, etc.
2) I wonder if it would be preferable to list Acq, Serials, Circulation, Cataloging, and the OPAC earlier in the documentation.  These tend to be more front-line-staff-oriented and in my limited experience, the people most in need of this level resource are those that might be scared away from the documentation if the first things they see listed are "Software Installation" and "System Configuration and Customization."  I understand the current organization, but don't want the documentation to look too intimidating to the less tech-savvy among us...at least at first glance! Just a thought...

Thanks for taking a stab at reorganization, Robert.  Your proposed "BASE" items look great to me.

Jenny
_________________________________________________________________________________
Jennifer Turner | PALS, A Program of the Minnesota State Colleges and Universities | 507-389-2000

 

-----Original Message-----
From: open-ils-documentation-bounces at list.georgialibraries.org [mailto:open-ils-documentation-bounces at list.georgialibraries.org] On Behalf Of Soulliere, Robert
Sent: Wednesday, December 14, 2011 12:52 PM
To: open-ils-documentation at list.georgialibraries.org
Subject: [OPEN-ILS-DOCUMENTATION] Documentation Reorganization Discussion for 2.2

Hi All,

Given recent discussion about documentation release times got me to thinking if the documentation needs to be reorganized a bit. A few of my pet peeves about the current organization are.

1. Order: Currently the documentation starts at the most basic local level -  using the OPAC, and ends with "Development". I wonder if it should be organized in a more global to local level as well as in a more chronological order from installation to end use. (I think a lot of software documentation starts with installation).

2. The generic "Core staff tasks" part is bothersome for me: Evergreen has grown out of this generic catch word for any task outside of system administration (Administrators as core staff too! ;-)) . I wonder if we should have separate parts for all the tasks based on the standard library processes. This is especially the case since many new features have been added to the staff tasks.

I created a draft of the proposed 2.2 outline at http://open-ils.org/dokuwiki/doku.php?id=evergreen-docs_2.2:outline

Note that I added "BASE" in brackets to indicate the chapters which should be produced at release time. These include Release Notes, System Requirements, Installation, Upgrading.
It can be expected and doable to ensure these basic chapters are ready to go at release time especially since much of the content will be included in asciidoc format with the code etc. Some coordination steps with developers will need to be adapted.

Let me know if there are others which should be published at release time?

Please discuss and let me know if their are better approaches.

Thanks,
Robert

Robert Soulliere, BA (Hons), MLIS
Systems Librarian
Mohawk College Library
robert.soulliere at mohawkcollege.ca
Telephone: 905 575 1212 x3936
Fax: 905 575 2011

This E-mail contains privileged and confidential information intended only for the individual or entity named in the message.  If the reader of this message is not the intended recipient, or the agent responsible to deliver it to the intended recipient, you are hereby notified that any review, dissemination, distribution or copying of this communication is prohibited.  If this communication was received in error, please notify the sender by reply E-mail immediately, and delete and destroy the original message.
_______________________________________________
OPEN-ILS-DOCUMENTATION mailing list
OPEN-ILS-DOCUMENTATION at list.georgialibraries.org
http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation