Longware, Inc INTERNAL STYLE GUIDE

Transcription

1 1 Longware, Inc INTERNAL STYLE GUIDE [could you go back and listen to my recording again? you miss some stuff here. Table of Contents About This Guide... 2 Highlighting... 3 Bold... 3 Italics... 3 Special Fonts... 3 Capitalization... 3 Quotation Marks... 4 Underline... 4 Grammar and Writing... 5 Serial Commas... 5 Passive Voice... 5 Font... 5 Graphics... 5 Lists... 6 Headings... 6 Usage... 7 Index... 8

2 2 About This Guide Use this guide to answer usage questions, learn about conventions, and pull internal reference information. Not all information in the guide will apply to every project; if a specific style guide exists for your product, consider it primary to this document. The style guide is currently maintained by Ian Alexander. Please contact him with any suggestions or concerns regarding the guide.[include standard ref books and instructions on when to use]

3 3 Highlighting Bold Use bold highlighting in these circumstances: For the lead-in to a special notice. Example: o Caution: Remove the battery before opening the device. For user interface items, such as buttons. Example: o Select the Save As button to save the file under a different name. Do not use bold highlighting for: emphasis figure captions headings punctuation Italics Use italic highlighting in these circumstances: For emphasis. Example o Clicking this button will not save your work. For referencing external documents. Example: o For help with this procedure, refer to the Longware 4844 User Guide. Do not use italic highlighting for: filepaths figure captions Special Fonts See the font section.[ see Fonts?] Capitalization Use these guidelines for capitalization: Only use all-caps style when a product or function name is entirely in caps. Example: o The Longware DEXI-84 functions on lithium power. Use initial caps for headings (except for run-in headings.) Example: o Using This Guide Capitalize the first word of any list item that is a full sentence. Capitalize drive letters and keyboard keys when used as user interface items. Example: o C:\

4 4 o Press the N key. Quotation Marks Do not use quotation marks for emphasis. Underline Do not use underline for emphasis.

5 5 Grammar and Writing Reference the guidelines below regarding grammar questions. Serial Commas The serial comma should be used to end all lists. For example: The user has the option to save, save under a new name, or exit. This function works with the 4844, 8499, and 4877 models. Passive Voice Avoid passive voice whenever possible. Examples of passive voice, followed by appropriate rephrasings: Users should avoid unplugging the device while it is in use. o CHANGE TO: Avoid unplugging the device while it is in use. The program will reset if the red button is clicked. o CHANGE TO: Clicking the red button resets the program. Font Use these guidelines for selecting fonts. Use Verdana for all headings, regardless of text size. Use 11pt Calibri for all body text. Use Courier New for all file paths. Example: o Locate the file at C:/Program Files/Bacon_Frances Do not use any font aside from the three previously listed. Graphics Use these standards for placing art and screenshots in your documentation. For all graphics: Place a 1px border around the graphic. Provide double spacing after the graphic. All screenshots should be square or rectangular in nature. Use a solid white background in any case where a desktop background shows. Do not use figure captions. The graphic should be referenced in the preceding text. Do not separate a graphic from the text introducing or explaining it.

6 6 Lists Use these guidelines shown below for all lists. Use a lead-in with a colon for all lists. Bulleted Lists Use for lists that do not need to be in order Use this bullet format filled circle, empty circle, filled square. Example: The kit contains the following items: Item one Item two Item three Numbered Lists Use for lists that must be in order. Most often, these lists are used for procedural steps. Use this number format Arabic number, lowercase letter, lowercase Roman numeral. Example: To create the document: 1. Select New Document. 2. Enter the document name. 3. Choose a directory to save the file in. [state punctuation for lead-in and bulleted-list items; state need of a lead-in] Headings The standard for headings is as follows: First-level headings: 16pt white Verdana text in a black rectangle. Second-level headings: 14pt black Verdana text Third-level headings: 11pt black Verdana text Run-in headings: Do not use run-in headings.[state capitalization, phrasing reqs. Maybe you do elsewhere but readers are going to get frustrated that not all info related to headings not here]

7 7 Usage Use the usage section to answer questions about usage of various words and phrases. This section also addresses some topics regarding standards and conventions. bytes: the preferred capitalization of the measurement. Example: You need 322 bytes of space. CD: do not use. Use disc instead. computer-users: do not use. Use users where applicable, otherwise use computer users. Control: use instead of CTRL. drive/disc drive: use drive. When a drive address is given, provide the full location. Example: Open the C:/ drive. double-click: do not use. Use open or select instead. Filepad: the preferred use of the product name. Do not use Longview Filepad or other variations. filepath: do not use. Use file path. When providing file paths, use Courier New. folder: do not use. Use directory. pull-down: use drop-down Windows Me: the preferred use of this OS name. Do not use Windows ME.

8 8 Index Bold, 3 Capitalization, 3 Commas, 5 emphasis, 3 Font, 5 Graphics, 5 Headings, 6 Highlighting, 3 interface, 3 Italics, 3 Lists, 6 Quotation, 4 Underline, 4 Usage, 7 Voice, 5