[OPEN-ILS-GENERAL] Reorganized documentation: proof of concept

Thu Aug 24 15:11:22 EDT 2017

Life is complicated, isn't it?

What I had in mind with my "constantly updated" phrase was that the
documentation was at a community site that would consist of the most recent
documentation.  I wasn't taking into account the need to have all the
different docs for all the different versions. I don't suppose a simple
disclaimer would be sufficient? Linking to the most recent version docs
still would speak to earlier version issues, and describing new features
might act as an incentive to move up to the latest and greatest. Just
looking for the easiest way to find answers.

Thanks for all you insights!

Don

On Thu, Aug 24, 2017 at 2:24 PM, Rogan Hamby <rhamby at equinoxinitiative.org>
wrote:

> I didn't think about this until I saw Kathy's message pop up but I could
> also imagine a location where they don't want traffic going outside their
> defined network for a variety of reasons and it would have to be easy to
> modify or it would break for them.
>
>
>
>
> Rogan Hamby
>
> Data and Project Analyst
>
> Equinox Open Library Initiative
>
> phone:  1-877-OPEN-ILS (673-6457)
>
> email:  rogan at EquinoxInitiative.org
> web:  http://EquinoxInitiative.org
>
> On Thu, Aug 24, 2017 at 2:20 PM, Kathy Lussier <klussier at masslnc.org>
> wrote:
>
>> Hi,
>>
>> I think it has some challenges also.  One of these is that some Evergreen
>> users customize their installs.  You can always say "oh, then they have to
>> modify their links to go to different docs too."  I'd want to hear from
>> community members that might affect.
>>
>> Yes, that was my first reaction. If we had links to documentation in the
>> client, then I would want a setting allowing sites to customize the URL
>> that is used. There are many features / settings in Evergreen that may not
>> be available to our libraries due to policy. I would want them to access
>> documentation specific to their implementation of Evergreen.
>>
>> Related to Don's third bullet point, I also wanted to throw in a comment
>> that we do have something called field documentation available for the
>> patron editor that I think could be expanded to other interfaces in the
>> client. However, it takes a bit of work to configure field documentation.
>> More information is available at http://docs.evergreen-ils.org/
>> 2.1/html/fielddocumentation.html The docs are from 2.1, but my
>> recollection is that the field documentation in the web client displays the
>> same way as it did in the old client.
>>
>> Kathy
>>
>> On 08/24/2017 02:14 PM, Rogan Hamby wrote:
>>
>> Hi Donald,
>>
>> When you say "constantly updated" I'm imagining that you're not thinking
>> of something bundled with the distribution but links that go back to the
>> community site?  At the least this would have to be bound by version I
>> think and the granularity of the version it links to would have to be
>> considered.  For example, if path 31.2 introduces a new feature then we
>> need a new version of the docs to mirror that.  Anyway, that's all a long
>> way of saying I think the idea has merit but it could create accidental
>> confusion if not done just right.  Docs aren't always quite in sync with
>> development now and I think then the expectation that they would be, even
>> on small patches would be even higher.
>>
>> I think it has some challenges also.  One of these is that some Evergreen
>> users customize their installs.  You can always say "oh, then they have to
>> modify their links to go to different docs too."  I'd want to hear from
>> community members that might affect.
>>
>>
>> Rogan Hamby
>>
>> Data and Project Analyst
>>
>> Equinox Open Library Initiative
>>
>> phone:  1-877-OPEN-ILS (673-6457)
>>
>> email:  rogan at EquinoxInitiative.org
>> web:  http://EquinoxInitiative.org
>>
>> On Thu, Aug 24, 2017 at 2:06 PM, Donald Butterworth <
>> don.butterworth at asburyseminary.edu> wrote:
>>
>>> Jillianne and Jane,
>>>
>>> I like what you have done a *lot*. It makes so much sense and is less
>>> intimidating for us cataloger types who shy away from system
>>> administration.
>>>
>>> I wonder ... could the concept be taken a step further to include hot
>>> links, in Webby, to a constantly updated HTML version of the
>>> documentation?  I see 3 possibilities.
>>>
>>>    - Create a "Documentation" dropdown menu, consisting of all 7 docs,
>>>    alongside of Search | Circulation | Cataloging | etc.
>>>    - Add "Documentation" as a line item in the existing dropdown menus.
>>>    - Ideally, right click on any dropdown menu line item, then have a
>>>    line on the popup window with a context sensitive hot link. OCLC does
>>>    something similar with a "MARC Field Help" hot link to its Bibliographic
>>>    Formats and Standards.
>>>
>>> Thanks so much for your great work! +1
>>>
>>> Don
>>>
>>>
>>>
>>> On Wed, Aug 23, 2017 at 4:37 PM, Mary Llewellyn <mllewell at biblio.org>
>>> wrote:
>>>
>>>> I think it looks great, much less overwhelming to have the module
>>>> documentation split up.
>>>>
>>>> Mary
>>>>
>>>>
>>>> On Thu, Aug 17, 2017 at 3:28 PM, Ruth Frasur <
>>>> director at hagerstownlibrary.org> wrote:
>>>>
>>>>> This looks great.  I appreciate the reasoning behind this schema and
>>>>> think it's very usable.
>>>>>
>>>>> On Tue, Aug 15, 2017 at 2:43 PM, Jane Sandberg <sandbej at linnbenton.edu
>>>>> > wrote:
>>>>>
>>>>>> Dear Evergreeners,
>>>>>>
>>>>>> Jillianne Presley and I have put together a proof of concept for a new
>>>>>> direction for Evergreen's documentation, and DIG would really
>>>>>> appreciate your input.
>>>>>>
>>>>>> Rather than the current documentation, which tries to be many things
>>>>>> to many people, the reorganized documentation is separated into
>>>>>> separate manuals, each with its own audience (e.g. catalogers,
>>>>>> front-line circ folks, sysadmins).  The hope is that this organization
>>>>>> will help get the right content to the right people, and help DIG keep
>>>>>> tabs on documentation gaps.
>>>>>>
>>>>>> You can find the new manuals in the bottom half of this page:
>>>>>> http://docs-testing.evergreen-ils.org/
>>>>>>
>>>>>> Keep in mind that -- in this proof-of-concept iteration -- there are
>>>>>> some pieces of documentation that are in the wrong manual.  However,
>>>>>> we hope that it is close enough that you'd be able to tell us:
>>>>>>
>>>>>> a) if you think that reorganized documentation would be a valuable
>>>>>> thing for this community to have.
>>>>>>
>>>>>> b) if the current breakdowns of manuals would make sense for your
>>>>>> library.
>>>>>>
>>>>>> c) other feedback on this project.
>>>>>>
>>>>>> Again, that link is http://docs-testing.evergreen-ils.org/
>>>>>>
>>>>>> Thanks very much for your help,
>>>>>>
>>>>>>    -Jane
>>>>>>
>>>>>> --
>>>>>> Jane Sandberg
>>>>>> Electronic Resources Librarian
>>>>>> Linn-Benton Community College
>>>>>> sandbej at linnbenton.edu / 541-917-4655
>>>>>> Pronouns: she/her/hers or they/them/theirs
>>>>>>
>>>>>
>>>>>
>>>>>
>>>>> --
>>>>> Ruth Frasur
>>>>> Director of the Historic(ally Awesome) Hagerstown - Jefferson Township
>>>>> Library
>>>>> 10 W. College Street in Hagerstown, Indiana (47346)
>>>>> p (765) 489-5632 <%28765%29%20489-5632>; f (765) 489-5808
>>>>> <%28765%29%20489-5808>
>>>>>
>>>>> *Our Kickin' Website <http://hagerstownlibrary.org>,  Our Rockin'
>>>>> Facebook Page <http://facebook.com/hjtplibrary>,  and The Nettle Creek
>>>>> Players <http://nettlecreekplayers.com>*
>>>>>
>>>>
>>>>
>>>>
>>>> --
>>>> Mary Llewellyn
>>>> Database Manager
>>>> Bibliomation, Inc.
>>>> 24 Wooster Ave.
>>>> Waterbury, CT 06708
>>>> mllewell at biblio.org
>>>>
>>>
>>>
>>>
>>> --
>>> Don Butterworth
>>> Collection Management Librarian /
>>> Faculty Associate
>>> B.L. Fisher Library
>>> Asbury Theological Seminary
>>> don.butterworth at asburyseminary.edu
>>> (859) 858-2227 <%28859%29%20858-2227>
>>>
>>
>>
>> --
>> Kathy Lussier
>> Project Coordinator
>> Massachusetts Library Network Cooperative(508) 343-0128klussier at masslnc.org
>> Twitter: http://www.twitter.com/kmlussier
>>
>>
>

-- 
Don Butterworth
Collection Management Librarian /
Faculty Associate
B.L. Fisher Library
Asbury Theological Seminary
don.butterworth at asburyseminary.edu
(859) 858-2227
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://libmail.georgialibraries.org/pipermail/open-ils-general/attachments/20170824/dac06284/attachment-0001.html>