[OPEN-ILS-DOCUMENTATION] Including technical information in end-user docs

[James Keenan]

I prefer having the information all in one place. When I was first learning to install Evergreen (and before a bunch of doc work was done), it seemed pretty  inconvenient for me to search around for various bits of knowledge here and there in different docs on the same topic.

Jim

Jim Keenan
Library Applications Supervisor
jkeenan at cwmars.org
508-755-3323 x23
 
C/W MARS
67 Millbrook St., Suite 201
Worcester, MA 01606

   Save a tree! Please don't print this e-mail unless it's really necessary.
Currently reading Zen at War by Brian Victoria
Just finished World War Z by Max Brooks

-----Original Message-----
From: open-ils-documentation-bounces at list.georgialibraries.org [mailto:open-ils-documentation-bounces at list.georgialibraries.org] On Behalf Of Kathy Lussier
Sent: Thursday, August 01, 2013 2:03 PM
To: Documentation discussion for Evergreen software
Subject: [OPEN-ILS-DOCUMENTATION] Including technical information in end-user docs

Hi all,

This question came up during some recent discussions I had with Equinox regarding some documentation they were doing for one of our development projects, and it seemed like a topic that DIG might want to discuss. It relates to how much technical documentation should be included in the end-user docs that are created for a feature in Evergreen. In this case, it is a new feature, but I suppose the question relates to any functionality we want to document for Evergreen.

We've seen documentation come in various forms when a new feature is
introduced:

* The release notes include a description of the new feature and, ideally, also include any new settings or permissions associated with the feature.
* The docs include information for end users to use the new feature. It also sometimes contains information on settings and permissions.
* There is also a TechRef directory that is available with the code that contains more technical information on some features.

The question is how much technical information should be included in those end-user docs?

My personal opinion is that any information in the Release Notes should also be included in the docs because there are many people who probably never look at the release notes. However, should end-user docs include information on library settings and permissions that are usually configured by the admin, not the end-user? Should a separate technical details section be included in the end-user docs?

What structure do you think would work best for the community?

Kathy

--
Kathy Lussier
Project Coordinator
Massachusetts Library Network Cooperative
(508) 343-0128
klussier at masslnc.org
Twitter: http://www.twitter.com/kmlussier

_______________________________________________
OPEN-ILS-DOCUMENTATION mailing list
OPEN-ILS-DOCUMENTATION at list.georgialibraries.org
http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation