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

Thu Sep 7 19:22:19 EDT 2017

Hi all,

Thanks very much for your enthusiastic responses and ideas about
making the documentation more available to users when they need it.

A quick update: the Documentation Interest Group has decided to
present the documentation for Evergreen 3.0 and later releases in a
re-organized format.  We will likely need a lot of help
reviewing/cleaning up the documentation after it is split, so if
you're interested in getting involved in this project, please stay
tuned on the documentation email list
(http://libmail.georgialibraries.org/mailman/listinfo/open-ils-documentation).

Thanks very much,

   -Jane

On Fri, Aug 25, 2017 at 6:17 AM, Terran McCanna
<tmccanna at georgialibraries.org> wrote:
> I love that idea!
>
> Terran McCanna
> PINES Program Manager
> Georgia Public Library Service
> 1800 Century Place, Suite 150
> Atlanta, GA 30345
> 404-235-7138
> tmccanna at georgialibraries.org
>
>
> On Thu, Aug 24, 2017 at 6:00 PM, Galen Charlton <gmc at equinoxinitiative.org>
> wrote:
>>
>> Hi,
>>
>> But without complications, would life be interesting? ;)
>>
>> More seriously, I could envision a way for the web staff client to
>> link to the appropriate version (and section) of the community
>> documentation in a reasonably maintainable way.  Most pages in the web
>> staff client have predictable URLs; for example, if the path contains
>> 'cat/bucket/record', documentation on copy buckets is what's needed.
>> An Evergreen system knows its own version, so that plus the relevant
>> part of the URL gives us something that could be converted to a link
>> to the documentation site. There would have to be some sort of index
>> mapping from version + staff interface URL to the appropriate
>> documentation section, of course; depending on how we do it, that
>> mapping could be maintained as part of Evergreen or on the
>> documentation website.
>>
>> Since the documentation also lives in the Evergreen source tree, I can
>> also imagine building the HTML version of the documentation as part of
>> the Evergreen installation process, allowing the documentation to be
>> pointed at a local copy (and one that could be customized).
>>
>> Upshot: I think the idea has merit, and it would also take some effort
>> to pull off, but I think it would be achievable.
>>
>> Regards,
>>
>> Galen
>>
>> On Thu, Aug 24, 2017 at 3:11 PM, Donald Butterworth
>> <don.butterworth at asburyseminary.edu> wrote:
>> > 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; f (765) 489-5808
>> >>>>>>
>> >>>>>> Our Kickin' Website,  Our Rockin' Facebook Page,  and The Nettle
>> >>>>>> Creek
>> >>>>>> Players
>> >>>>>
>> >>>>>
>> >>>>>
>> >>>>>
>> >>>>> --
>> >>>>> 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
>> >>>
>> >>>
>> >>>
>> >>> --
>> >>> Kathy Lussier
>> >>> Project Coordinator
>> >>> Massachusetts Library Network Cooperative
>> >>> (508) 343-0128
>> >>> klussier 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
>>
>>
>>
>> --
>> Galen Charlton
>> Infrastructure and Added Services Manager
>> Equinox Open Library Initiative
>> phone:  1-877-OPEN-ILS (673-6457)
>> email:  gmc at equinoxInitiative.org
>> web:  https://equinoxInitiative.org
>> direct: +1 770-709-5581
>> cell:   +1 404-984-4366
>
>

-- 
Jane Sandberg
Electronic Resources Librarian
Linn-Benton Community College
sandbej at linnbenton.edu / 541-917-4655
Pronouns: she/her/hers or they/them/theirs