DIG AsciiDoc Style Guide (draft)
Proposal: Antora with Some AsciiDoc Changes
A small working group has been testing Antora as a new "framework" for the Evergreen docs. Antora requires some minor changes to the directory structure, and it reveals some AsciiDoc syntax errors (since it uses the more strict AsciiDoctor for converting to HTML).
In addition to these minor changes, the working group proposes the following changes, which are not necessary for using Antora but we believe would make the docs better.
Add a Table of Contents to the top of each AsciiDoc file
This simply means adding this AsciiDoc line near the top of each
.adoc file. (The old system added this during the HTML build process.)
Convert all headings from underline style to prefix/suffix style
The basic reasons are:
It's hard to remember which character means which level heading
It's hard to maintain the correct number of characters (must match length of heading line)
Prefix/suffix style solves these problems, and is more readable in text format than prefix-only style
Example: Change this
== Heading 1 ==
Here's a Python script that could help with the conversion (only adds prefix; we'd need to modify it to add the suffix):
Avoid changing section titles. These are used to auto-generate anchor tags which are often used for links. Change with care, and check for links in other docs.
Always review changes before committing to master (and check the updated web page the next day to make sure it worked right).
Always use spell-check on new content (including when porting old docs into master).
AsciiDoc code lines should be 80 characters long or shorter. (Occasionally, exceptions are necessary for correct syntax.)
Screenshots should be smaller than 1050 pixels wide (when possible).
Headers should be in title case (i.e. capitalize important words)
Headers can be formatted in either of two ways, but a single AsciiDoc file should use the same style consistently.
Changing A Section Heading
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. Example anchor name: "_shelving_location_groups")
Search the docs code for that exact anchor name to find any references. (These will look like "<>".)
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).
NOTE: This may change the docs page URL
, which would break external links and bookmarks. To prevent this, ask the DIG email list
how they handle redirecting pages that move.
Header Prefix Syntax
== Header Level 1
=== Header Level 2
==== Header Level 3
===== Header Level 4
Header Underline Syntax
Header Level 1
Header Level 2
Header Level 3
Header Level 4
Actions that leave the page should be in *bold* (buttons, navigation [links, tabs, menu trails])
Field names (and other special terms) may be in _italics_ for clarity, at the author's discretion
A sequence of actions should have this arrow -> between them
Names for keyboard keys should be in all caps (e.g. "Press CTRL-TAB to switch browser tabs…")
Numbered list items should simply start with ". " (e.g. ". Text Goes Here"), instead of "1. ", etc.
should be left as is (&). Don't use an HTML
entity (which ironically causes errors in our HTML
Any code and command line commands should be marked as +code+ or `code`
# This is a *source* block
print "Hello world!";
Use consistent action words
Enter a value into the text box
Check or Uncheck the check box if the situation applies
Choose or Select an option from the drop down menu
Select the button, tab or menu -> menu2 -> menu3
Right-click to show the *Actions* menu
Location words should use hyphens
Use clear, standard terms
Use words that match the wording in the module you are describing
Example: The "MARC Batch Import/Export" interface is also sometimes labeled "Evergreen MARC File Upload". Both of these names are equally appropriate within the documentation. However, this interface is commonly called "Vandelay" throughout the code. Since the name "Vandelay" is not used in the staff client interface, it should be avoided in the documentation.
Add after each required field description: "This field is required."
Menu Bar: The green bar at the top of the Web Client (includes dropdowns for Search, Circulation, Cataloging, etc.)
Table Action Bar or Grid Function Row: The row just above most grid/tables in the web client (includes table title on the left, and dropdowns on the right for Actions, paging, and column settings)
See the Glossary
for preferred versions of Evergreen terms. Here are some common examples:
When you want to document why a particular feature might be used, it's helpful to put that in an Asciidoc "sidebar" (though it often is displayed as a callout block). Syntax:
This feature is useful in cases where
your library wants to catalog books about
tigers and other big cats.
Keep them as small and focused as possible while still giving enough context to make them useful to readers. If a screenshot focuses on a small portion of the screen, then it takes up less space in the docs and is less likely to need updating when future versions of Evergreen modify other parts of the screen.
Highlight parts of the screen using a border or arrow, when it seems helpful.
Don't add a border or shadow
to the screenshot image. That can be done globally to all screenshots in the docs via CSS
, if we want it.
When replacing a screenshot, if the intention of the image isn't changing, then create a new image with the same file name as the old image. However, if you are essentially removing a screenshot and adding a different one (with a different focus or purpose), it is better to use a different file name (and update the reference to it in the docs!), and probably to change the related text in the documentation also.