Authoring Documentation
DocBook ....
Structure: Concept, Task, Reference
Every chapter in Evergreen documentation, and in some cases sections, should begin by
explaining this chapter's concepts, or core ideas, to the 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.
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:
In the staff client, select Circulation→Check Out Items. The Check Out tab
appears.
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.
Enter the item barcode in the text field beside the Barcode: selection in the
drop-down menu.
(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.