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

[Andrea Buntz Neiman]

Jane -- I can devote some time to step 1, but not until next week.  Many
thanks to Cheyenne for taking this on!

Remington -- +1, this is very helpful info (and I've probably messed up
those headings before).  Thanks for adding it to the Style Guide as well.

All -- are we still planning to have a DIG meeting today at 2pm EST?

ABN

On Thu, Mar 7, 2019 at 9:39 AM Remington Steed <rjs7 at calvin.edu> wrote:

> 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
> _______________________________________________
> OPEN-ILS-DOCUMENTATION mailing list
> OPEN-ILS-DOCUMENTATION at list.georgialibraries.org
> http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation
>


-- 
Andrea Buntz Neiman
Project Manager for Software Development
Equinox Open Library Initiative
abneiman at equinoxinitiative.org
1-877-OPEN-ILS (673-6457) x5583
*www.equinoxinitiative.org <http://www.equinoxinitiative.org>*
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://list.georgialibraries.org/pipermail/open-ils-documentation/attachments/20190307/fc1aa4a2/attachment-0001.html>