User Tools

Site Tools


evergreen-docs:dig_style_guide

DIG AsciiDoc Style Guide (draft)

General

  • 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).

Formatting

Headers

  • 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.

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
++++++++++++++

Other Formatting

  • 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
  • Numbered list items should simply start with ". " (e.g. ". Text Goes Here"), instead of "1. ", etc.
    • This allows AsciiDoc to auto-number the items as needed.
  • Any code and command line commands should be marked as +code+ or `code`
    • If the code or command is hard to read when included in the paragraph, consider using a code block:
.Optional Title
[source,perl]
----
# This is a *source* block
print "Hello world!";
----

Wording

  • Add after each required field description: "This field is required."
    • (Or is it nicer to have a summary of required fields in a note at the end of the form?)
  • Use consistent action words
    • Enter or Type a value into the text box
    • Check the check box if the situation applies
    • Choose or Select an option from the drop down box (or drop down menu?)
    • Click the button, tab or menu -> menu2 -> menu3
    • Right-click to show the *Actions* menu
  • Location words should use hyphens
    • On the top-right of the page
  • Use clear, standard terms
    • Public catalog or catalog (but not TPAC or JSPAC, unless you are contrasting the two versions of the OPAC; then clarify "TPAC, the new template-based catalog")
  • 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.

Linking

  • Internal Links (i.e. cross references) have two parts
    • ANCHOR (automatically added for section headings):
      • Heading of "Create a provider" becomes section-id: _create_a_provider
        • NOTE: If two sections have the same heading, the second ID will end with "_2"
      • Custom ID: [[section-id]]
        • CAUTION: If you define a custom section ID that already exists, it will cause errors while building the HTML pages.
    • LINK
      • Syntax: <>
      • Example:
        • Read about <<_create_a_provider,creating a provider>> for more details.
  • Add terms to the index

Screenshots

  • Keep them as small and focused as possible while still making 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.
  • 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.

Further Reading

evergreen-docs/dig_style_guide.txt · Last modified: 2017/07/07 08:47 by rjs7

© 2008-2017 GPLS and others. Evergreen is open source software, freely licensed under GNU GPLv2 or later.
The Evergreen Project is a member of Software Freedom Conservancy.