documentation:style_guide
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
documentation:style_guide [2008/02/10 11:12] – Where to place scenario information 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, | ||
+ | |||
+ | =====Structure: | ||
+ | |||
+ | ====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, | ||
+ | |||
+ | To check out a cataloged item to a patron: | ||
+ | - In the staff client, select **Circulation**-> | ||
+ | - Enter the patron barcode in the **Barcode** text field. The system retrieves and displays the patron information, | ||
+ | - Enter the item barcode in the text field beside the **Barcode: | ||
+ | - (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, | ||
+ | |||
+ | 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// | ||
+ | |||
+ | 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 " | ||
+ | |||
+ | ====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, | ||
+ | |||
+ | 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, | ||
+ | |||
+ | ====Contractions, | ||
+ | Do not use contractions (" | ||
+ | |||
+ | ==== Highlighting ==== | ||
+ | Use **bold** to highlight the names of GUI elements such as field and button labels, window names, and menu options. |
documentation/style_guide.txt · Last modified: 2022/02/10 13:34 by 127.0.0.1