User Tools

Site Tools


documentation:style_guide

The Book of Evergreen: Style Guide

Note: for the current DIG Style Guide for the official documentation, see DIG AsciiDoc Style Guide (draft)

Structure: Concept, Task, Reference

Concepts

Begin a new topic by explaining the concepts – the core ideas – to your reader. This gives you the opportunity to clarify new or ambiguous terminology for otherwise experienced readers: for example, in a circulation overview you will want to differentiate non-cataloged items vs. pre-cataloged items. Explaining concepts also gives less experienced readers a chance to fill in gaps in their knowledge.

If you are an artist, diagrams that display relationships between elements of the system can be a very powerful way of conveying concepts to visual thinkers.

Tasks

Follow the concepts with one or more tasks relating to the topic. For example, in the circulation section of the manual, you may write the following set of tasks:

  • Checking out an item
  • Checking in an item
  • Renewing items
  • Recording in-house uses

Separating the concepts from the tasks gives your readers the chance to jump directly to the task they want to complete, if they are already familiar with the concepts.

When you write your task information, try to organize it as a set of numbered steps that covers the most common cases. Compose each step in two sentences: first, describe the action the reader must complete, followed by a sentence describing the results of successfully performing the action if applicable. Preface optional steps with (Optional):. For example:

To check out a cataloged item to a patron:

  1. In the staff client, select Circulation->Check Out Items. The Check Out tab appears.
  2. Enter the patron barcode in the Barcode text field. The system retrieves and displays the patron information, with the Check Out button highlighted in the action bar.
  3. Enter the item barcode in the text field beside the Barcode: selection in the drop-down menu.
    1. (Optional): Select a different due date from the date selector.
  4. Click Submit to check out the item to the patron. The item barcode, due date, and title appear in the transaction summary table.
  5. Repeat steps 3 and 4 for each additional item the patron wants to borrow.
  6. (Optional): Click Print Receipt to print a receipt summarizing the transactions for the patron. The Print Receipt window opens.

Reference

Reference information consists of lists of commands, configuration files and settings, software prerequisites, APIs, etc that need to be rigorously documented to support use cases outside the core task documentation. Reference information is typically organized by type, then by alphabetical order. For example, all system commands will be documented in their own section of the manual in alphabetical order, and all APIs will be documented in their own section of the manual in alphabetical order.

System commmands:

  • autogen.sh
  • import_holdings.pl
  • marc2bre.pl
  • osrf_ctl.sh

APIs:

  • open-ils.auth.authenticate.complete
  • open-ils.auth.authenticate.init

Discuss how each system feature would be used by each scenario institution

If applicable, provide an example of how each institutional scenario (Le Grande University vs. Metropolitan Public Library Consortium) would likely put the feature being discussed into use. You will probably want to include this information in the concept topic(s) introducing the feature, or as a separate concept topic or set of topics following the introductory concept topic.

The scenarios give you a few different facets to describe when explaining the topic to your reader:

  • academic vs. public libraries
  • consortiums vs. standalone libraries
  • libraries with large collections vs. libraries with small collections

Style guidelines

Use the active voice

Avoid the passive voice. For example:

Rather than:

The barcode is checked for a valid check digit when it is scanned.

Use the active voice:

When you scan the barcode, the system checks for a valid check digit.

If your sentence contains "is", be careful: it might be using the passive voice.

Write concise sentences

Try to keep your sentences brief. Avoiding complex phrases with related clauses helps readers concentrate on a single idea at a time. It also helps translators.

Prefix conditional clauses

If your sentence is conditional, place the conditional clause at the beginning of the sentence. When your reader skims your text and only sees the first part of the sentence, they might take the wrong action. For example:

Rather than:

Click the **Cancel** button to prevent the changes from being applied if the results did not match your expectations.

Use:

If the results did not match your expectations, click the **Cancel** button to prevent the changes from being applied.

Contractions, abbreviations, and acronyms

Do not use contractions ("you're", "we've", "it's") or Latin abbreviations (e.g., etc., i.e.). These can be hard to translate and hard to read. If you use an acronym, provide the full form of the acronym and include the acronym in parentheses in the first use in your topic. After the acronym has been introduced, you can use the acronym on its own for the remainder of the topic.

Highlighting

Use bold to highlight the names of GUI elements such as field and button labels, window names, and menu options.

documentation/style_guide.txt · Last modified: 2018/04/30 20:27 by sandbergja

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