[open-ils-commits] r674 - evergreen-ils.org/docs/styleguide (kgs)

[svn at svn.open-ils.org]

Author: kgs
Date: 2009-09-09 15:44:42 -0400 (Wed, 09 Sep 2009)
New Revision: 674

Added:
   evergreen-ils.org/docs/styleguide/authoring.xml
Log:
Uploading XML for Evergreen documentation styleguide-in-progress, for the DIG team to review.

Added: evergreen-ils.org/docs/styleguide/authoring.xml
===================================================================
--- evergreen-ils.org/docs/styleguide/authoring.xml	                        (rev 0)
+++ evergreen-ils.org/docs/styleguide/authoring.xml	2009-09-09 19:44:42 UTC (rev 674)
@@ -0,0 +1,93 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"
+    xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:id="authoring">
+    <title>Authoring Documentation</title>
+    <info>
+        <abstract>
+            <para>DocBook ....</para>
+        </abstract>
+    </info>
+    <section>
+        <title>Structure: Concept, Task, Reference</title>
+        <para> 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. </para>
+        <para> For example, in the circulation section of the manual, you may write the following
+            set of tasks: </para>
+        <itemizedlist>
+            <listitem>
+                <para>Checking out an item Checking in an item Renewing items Recording in-house
+                    uses</para>
+            </listitem>
+        </itemizedlist>
+        <para> 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. </para>
+        <para> 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: </para>
+        <para> To check out a cataloged item to a patron: </para>
+        <orderedlist>
+            <listitem>
+                <para>In the staff client, select Circulation→Check Out Items. The Check Out tab
+                    appears.</para>
+            </listitem>
+            <listitem>
+                <para>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.</para>
+            </listitem>
+            <listitem>
+                <para>Enter the item barcode in the text field beside the Barcode: selection in the
+                    drop-down menu.</para>
+            </listitem>
+        </orderedlist>
+        <!-- the following was copied from the wiki and has not been marked up yet. It is wrapped
+        with para elements so that it will not trigger the XML validator -->
+        
+        <para>(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. </para>
+    </section>
+</chapter>