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