From: kgs Date: Wed, 9 Sep 2009 19:44:42 +0000 (+0000) Subject: Uploading XML for Evergreen documentation styleguide-in-progress, for the DIG team... X-Git-Url: https://old-git.evergreen-ils.org/?a=commitdiff_plain;h=48646023524257b92176f8ef1c19e4bdc8d55225;p=Evergreen_Website.git Uploading XML for Evergreen documentation styleguide-in-progress, for the DIG team to review. git-svn-id: svn://svn.open-ils.org/ILS-Contrib/evergreen-ils.org@674 6d9bc8c9-1ec2-4278-b937-99fde70a366f --- diff --git a/docs/styleguide/authoring.xml b/docs/styleguide/authoring.xml new file mode 100644 index 0000000..9d45c84 --- /dev/null +++ b/docs/styleguide/authoring.xml @@ -0,0 +1,93 @@ + + + Authoring Documentation + + + DocBook .... + + +
+ Structure: Concept, Task, Reference + 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. + 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. 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. +
+