[OPEN-ILS-DOCUMENTATION] Problem with the smaller docs manuals

[Lynn Floyd]

This makes since to me.  

 

Lynn Floyd

 <mailto:Lfloyd at andersonlibrary.org> Lfloyd at andersonlibrary.org

Anderson County Library

Anderson, SC

 

 

From: OPEN-ILS-DOCUMENTATION <open-ils-documentation-bounces at list.georgialibraries.org> On Behalf Of Remington Steed
Sent: Monday, July 09, 2018 9:13 AM
To: Documentation discussion for Evergreen software <open-ils-documentation at list.georgialibraries.org>
Subject: [OPEN-ILS-DOCUMENTATION] Problem with the smaller docs manuals

 

Hi DIG,

 

A recent change made by Jane Sandberg caused me to realize a larger problem with our current multi-manual setup.  

 

TL;DR

 

We should manually create real anchors for every section.  Otherwise, when we include some sections in one manual (e.g. "Cataloging") but not in another, our auto-created anchors get different names.  Trouble!

 

The Details:

 

* Our current process of building HTML files automatically creates section "anchors" that we can use for internal links.  These are of the form "_section_name" (or if there are multiple sections with the same name, one will be "_section_name_2").  These have always been a bit tricky, since adding a new section called "Section Name" can change the other sections' anchors without warning, causing links to go to the wrong section.  But it gets worse with our new setup of multiple subject-specific manuals.

 

* If, say, the Cataloging manual only has one of those same-named sections, then "_section_name_2" might end up getting the anchor "_section_name" instead.  But it will still get "_section_name_2" in the consolidate manual.

 

* Wherever we link to that section, we need to know the exact anchor name, or the link will be broken.  And if the name is inconsistent in different manuals, we're in trouble!

 

I suggest we officially adopt a new approach to creating anchors:

 

1. Every section gets a manual anchor.  I suggest a similar format to the auto-created anchors, but without the starting "_".  That way, if we ever see an anchor link starting with "_", we can say "Hey, we forgot to update that."

 

2. When there's multiple sections with the same name, instead of just adding "_2" to the end, let's be more descriptive.  Maybe one is the "_intro" and the other is the "_details", for example.  Or one might be from the Acquisitions perspective ("section_name_acq") while the other is within the Circ docs ("section_name_circ").  That way, they'll still make sense even in manuals where the other section isn't included.

 

As usual, I've gotten way too detailed.  Comments?  Ideas?  If this sounds good to everyone, I bet the main conversion work could be automated.  I'll sketch up some ideas for the process for our next meeting.

 

(Hey Joe, when is our next meeting?)

 

Remington


--

Remington Steed
Electronic Resources Specialist
Hekman Library, Calvin College
http://library.calvin.edu/



Lynn Floyd
Head of Information Technology
Anderson County Library
Anderson, SC
lfloyd at andersonlibrary.org
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://list.georgialibraries.org/pipermail/open-ils-documentation/attachments/20180709/95abc9cd/attachment.html>