--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>\r
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"\r
+ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:id="authoring">\r
+ <title>Authoring Documentation</title>\r
+ <info>\r
+ <abstract>\r
+ <para>DocBook ....</para>\r
+ </abstract>\r
+ </info>\r
+ <section>\r
+ <title>Structure: Concept, Task, Reference</title>\r
+ <para> Every chapter in Evergreen documentation, and in some cases sections, should begin by\r
+ explaining this chapter's concepts, or core ideas, to the reader. This gives you the\r
+ opportunity to clarify new or ambiguous terminology for otherwise experienced readers:\r
+ for example, in a circulation overview you will want to differentiate non-cataloged\r
+ items vs. pre-cataloged items. Explaining concepts also gives less experienced readers a\r
+ chance to fill in gaps in their knowledge. </para>\r
+ <para> For example, in the circulation section of the manual, you may write the following\r
+ set of tasks: </para>\r
+ <itemizedlist>\r
+ <listitem>\r
+ <para>Checking out an item Checking in an item Renewing items Recording in-house\r
+ uses</para>\r
+ </listitem>\r
+ </itemizedlist>\r
+ <para> Separating the concepts from the tasks gives your readers the chance to jump directly\r
+ to the task they want to complete, if they are already familiar with the concepts. </para>\r
+ <para> When you write your task information, try to organize it as a set of numbered steps\r
+ that covers the most common cases. Compose each step in two sentences: first, describe\r
+ the action the reader must complete, followed by a sentence describing the results of\r
+ successfully performing the action if applicable. Preface optional steps with\r
+ (Optional):. For example: </para>\r
+ <para> To check out a cataloged item to a patron: </para>\r
+ <orderedlist>\r
+ <listitem>\r
+ <para>In the staff client, select Circulation→Check Out Items. The Check Out tab\r
+ appears.</para>\r
+ </listitem>\r
+ <listitem>\r
+ <para>Enter the patron barcode in the Barcode text field. The system retrieves and\r
+ displays the patron information, with the Check Out button highlighted in the\r
+ action bar.</para>\r
+ </listitem>\r
+ <listitem>\r
+ <para>Enter the item barcode in the text field beside the Barcode: selection in the\r
+ drop-down menu.</para>\r
+ </listitem>\r
+ </orderedlist>\r
+ <!-- the following was copied from the wiki and has not been marked up yet. It is wrapped\r
+ with para elements so that it will not trigger the XML validator -->\r
+ \r
+ <para>(Optional): Select a different due date from the date selector. 4. Click Submit to\r
+ check out the item to the patron. The item barcode, due date, and title appear in the\r
+ transaction summary table. 5. Repeat steps 3 and 4 for each additional item the patron\r
+ wants to borrow. 6. (Optional): Click Print Receipt to print a receipt summarizing the\r
+ transactions for the patron. The Print Receipt window opens. Reference Reference\r
+ information consists of lists of commands, configuration files and settings, software\r
+ prerequisites, APIs, etc that need to be rigorously documented to support use cases\r
+ outside the core task documentation. Reference information is typically organized by\r
+ type, then by alphabetical order. For example, all system commands will be documented in\r
+ their own section of the manual in alphabetical order, and all APIs will be documented\r
+ in their own section of the manual in alphabetical order. System commmands: * autogen.sh\r
+ * import_holdings.pl * marc2bre.pl * osrf_ctl.sh * … APIs: *\r
+ open-ils.auth.authenticate.complete * open-ils.auth.authenticate.init * … Discuss how\r
+ each system feature would be used by each scenario institution If applicable, provide an\r
+ example of how each institutional scenario (Le Grande University vs. Metropolitan Public\r
+ Library Consortium) would likely put the feature being discussed into use. You will\r
+ probably want to include this information in the concept topic(s) introducing the\r
+ feature, or as a separate concept topic or set of topics following the introductory\r
+ concept topic. The scenarios give you a few different facets to describe when explaining\r
+ the topic to your reader: * academic vs. public libraries * consortiums vs. standalone\r
+ libraries * libraries with large collections vs. libraries with small collections Style\r
+ guidelines Use the active voice Avoid the passive voice. For example: Rather than: The\r
+ barcode is checked for a valid check digit when it is scanned. Use the active voice:\r
+ When you scan the barcode, the system checks for a valid check digit. If your sentence\r
+ contains “is”, be careful: it might be using the passive voice. Write concise sentences\r
+ Try to keep your sentences brief. Avoiding complex phrases with related clauses helps\r
+ readers concentrate on a single idea at a time. It also helps translators. Prefix\r
+ conditional clauses If your sentence is conditional, place the conditional clause at the\r
+ beginning of the sentence. When your reader skims your text and only sees the first part\r
+ of the sentence, they might take the wrong action. For example: Rather than: Click the\r
+ **Cancel** button to prevent the changes from being applied if the results did not match\r
+ your expectations. Use: If the results did not match your expectations, click the\r
+ **Cancel** button to prevent the changes from being applied. Contractions,\r
+ abbreviations, and acronyms Do not use contractions (“you're”, “we've”, “it's”) or Latin\r
+ abbreviations (e.g., etc., i.e.). These can be hard to translate and hard to read. If\r
+ you use an acronym, provide the full form of the acronym and include the acronym in\r
+ parentheses in the first use in your topic. After the acronym has been introduced, you\r
+ can use the acronym on its own for the remainder of the topic. Highlighting Use bold to\r
+ highlight the names of GUI elements such as field and button labels, window names, and\r
+ menu options. </para>\r
+ </section>\r
+</chapter>\r
projects / Evergreen_Website.git / commitdiff