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

[Jane Sandberg]

Just gave you calendar access, Remington.

On Thu, Mar 7, 2019 at 7:13 AM Remington Steed <rjs7 at calvin.edu> wrote:
>
> Meeting?!  Hmm, we need reminders for such things…
>
>
>
> Can’t Google Calendar easily send email reminders, say, to the DIG email list a few days ahead of the event?  Anyone with access want to play with that, or give me access to the calendar?
>
>
>
> Remington
>
>
>
> --
> Remington Steed
> Electronic Resources Specialist
> Hekman Library, Calvin College
> http://library.calvin.edu/
>
>
>
> From: OPEN-ILS-DOCUMENTATION <open-ils-documentation-bounces at list.georgialibraries.org> On Behalf Of Andrea Buntz Neiman
> Sent: Thursday, March 07, 2019 9:47 AM
> To: Documentation discussion for Evergreen software <open-ils-documentation at list.georgialibraries.org>
> Subject: Re: [OPEN-ILS-DOCUMENTATION] Help requested: updating terminology in the docs
>
>
>
> 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
>
> _______________________________________________
> OPEN-ILS-DOCUMENTATION mailing list
> OPEN-ILS-DOCUMENTATION at list.georgialibraries.org
> http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation



-- 
Jane Sandberg
Electronic Resources Librarian
Linn-Benton Community College
sandbej at linnbenton.edu / 541-917-4655
Pronouns: she/her/hers