[OPEN-ILS-DOCUMENTATION] Help requested: updating terminology in the docs

[Remington Steed]

One note about changing section headings:

Whenever we make changes to section headings (which have those lines of "+" or "^" or "~" below them), that causes a change in the autogenerated section anchor and page URL (if it's a higher level section).  We've often relied on these for linking to specific sections/pages throughout the docs, and obviously changing a URL would break any bookmarks or external links to that page.

Recent example (notice the URL change):

Before change:
http://docs.evergreen-ils.org/reorg/3.1/staff_client_admin/_modifying_copy_location_order.html

After change:
http://docs.evergreen-ils.org/reorg/3.2/staff_client_admin/_modifying_shelving_location_order.html

To prevent breaking bookmarks and external links, we'd need to setup a redirect for the old URL to the new URL.  I don't think AsciiDoc can do this, so we'd need to work with the server admin (Robert) to choose a solution.

To prevent breaking internal links:
-------------------------------------------
- Any time we edit a section heading (even fixing a typo), first check the HTML of the docs for the autogenerated anchor name.  (This will be in an <a id=""> tag, just inside the "<h2>" tag, or "<h3>", etc.)
- Search the docs code for that exact anchor name to find any references.
- Update the section heading and any references you found (it's okay to guess at the new anchor name; the docs committer can double-check this after it's published).


Comments?  Thoughts?  (I've added this to the DIG Style Guide wiki page for now; edits are welcome.)

We could improve this somewhat by adding explicit anchor names to every section heading.  Then if someone changes the anchor name, it's more clear that they need to change references to it also.  I've started this process and will share a branch soon.

Remington

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

-----Original Message-----
From: OPEN-ILS-DOCUMENTATION <open-ils-documentation-bounces at list.georgialibraries.org> On Behalf Of Jane Sandberg
Sent: Wednesday, March 06, 2019 9:16 PM
To: Documentation discussion for Evergreen software <OPEN-ILS-DOCUMENTATION at list.georgialibraries.org>
Subject: [OPEN-ILS-DOCUMENTATION] Help requested: updating terminology in the docs

Hi all,

Our fantastic technical services student worker -- Cheyenne Jones --
went through the official docs, replacing the out-of-date terms
"copy", "volume", and "copy location" with the consistent terms
"item", "call number", and "shelving location".  Her work can be found
here: https://urldefense.proofpoint.com/v2/url?u=https-3A__github.com_Cheyenne-2Djones_Evergreen&d=DwIGaQ&c=4rZ6NPIETe-LE5i2KBR4rw&r=XMUuJ_zlJ9I1qg9tP7WLhw&m=6JsWik9ElLl3W2_XmACZ_c04citWWRRrHXyWn2PlVN0&s=cOM4lifkdLz2Qe1M4h5SEIxV5rpd2-GhlQzMkHoJU3o&e=

Cheyenne can no longer work on this project, but she made a great
start.  I think the next steps are to:

1) Do some light checking of Cheyenne's commits for any false
positives (there should not be very many, since Cheyenne was comparing
these pretty carefully against a recent version of Evergreen)
2) Apply Cheyenne's changes to master and rel_3_2 branches (you would
have to be a docs committer to do this part)
3) Remain vigilant for other inconsistencies in terminology in the
documentation.

I'm going to have really limited time in the next few weeks.  Are any
of you able to work on steps 1 and 2?  It would be great to get these
changes in before 3.3 is released.

Thanks,

   -Jane

-- 
Jane Sandberg
Electronic Resources Librarian
Linn-Benton Community College
sandbej at linnbenton.edu / 541-917-4655
Pronouns: she/her/hers
_______________________________________________
OPEN-ILS-DOCUMENTATION mailing list
OPEN-ILS-DOCUMENTATION at list.georgialibraries.org
http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation