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

Thu Aug 24 18:00:09 EDT 2017

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