Differences

This shows you the differences between two versions of the page.

--- documentation:style_guide [2008/02/10 11:08] – Mention "(Optional):" prefix as a standard task step element dbs
+++ documentation:style_guide [2022/02/10 13:34] (current) – external edit 127.0.0.1
@@ Line 1: / Line 1: @@
+======The Book of Evergreen: Style Guide======
+Note: for the current DIG Style Guide for the official documentation, see [[evergreen-docs:dig_style_guide|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:
+  - 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.
+  - Click **Submit** to check out the item to the patron. The item barcode, due date, and title appear in the transaction summary table.
+  - Repeat steps 3 and 4 for each additional item the patron wants to borrow.
+  - (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.