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

Fri Aug 25 09:17:38 EDT 2017

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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://libmail.georgialibraries.org/pipermail/open-ils-general/attachments/20170825/12b0501a/attachment-0001.html>