Note: for the current DIG Style Guide for the official documentation, see DIG AsciiDoc Style Guide (draft)
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.
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:
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:
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:
APIs:
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:
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.
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.
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.
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.
Use bold to highlight the names of GUI elements such as field and button labels, window names, and menu options.