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 <[email protected]> On Behalf Of Jane Sandberg Sent: Wednesday, March 06, 2019 9:16 PM To: Documentation discussion for Evergreen software <[email protected]> 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 [email protected] / 541-917-4655 Pronouns: she/her/hers _______________________________________________ OPEN-ILS-DOCUMENTATION mailing list [email protected] http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation _______________________________________________ OPEN-ILS-DOCUMENTATION mailing list [email protected] http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation
