LONGWARE, Inc. Style Guide

Transcription

1 [well, this is the most thorough style guide on that document I have ever seen. I sense that you have been around some style guides in your life. how about a revision for perfection?] LONGWARE, Inc. Style Guide

2 Copyright Notice Copyright 2001 LONGWARE, Inc. All rights reserved. First Printing January 2001 Documentation version 5.0. No part of this publication may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any language or computer language, in any form or by any means, electronic mechanical, magnetic, optical, chemical, manual, or otherwise, without the prior written permission of LONGWARE, Inc. Trademarks Filepad and The Text File Company are trademarks of LONGWARE, Inc. Windows is a trademark of Microsoft Corporation. Technical Support For technical support, call or log on to our web site at Longware.com.

3 LONGWARE, Inc. About This Document The Text File Company Edition Updated 04/15/2011 This guide is for writers, editors, proofreaders, and others who work on LONGWARE, Inc. documents, product training programs, and electronic instructional and reference material. This guide is designed as a random access reference tool and it includes the following information: Section Style and Usage Description Shows how certain terms are used in LONGWARE, Inc. publications and provides preferred style for those terms and also provides general rules for style and usage. 3 P a g e

4 Standard Editorial Resources In general, follow the style and usage rules in: The American Heritage Dictionary The Chicago Manual of Style Exceptions to certain guidelines in these resources are noted in this guide. In cases where reference sources conflict with each other, follow: The American Heritage Dictionary for questions of spelling The Chicago Manual of Style for questions of usage Conventions This book uses the following conventions: Hardcopy refers to books and documents that are delivered in print or as online PDF files. Help refers to all online Help types that LONGWARE, Inc. writers create. In reference to styles that you should never use, without exception, this document uses Do not use. In reference to styles that you should not use as a general rule, this document uses Avoid. Providing Feedback If you find an error in this document or you would like to request additional guidelines, send an message to the technical publications team at the following address: dochelp@dough.com

5 LONGWARE, Inc. The Text File Company Style and Usage Overview This section shows how certain terms are used in LONGWARE, Inc. publications and provides preferred style (capitalization, spelling, and hyphenation) for those terms. It also provides general rules of style and usage for LONGWARE, Inc. publications. Entries appear in alphabetical order, including entries that begin with numerals. For example, you can find the entry for 10Base T in the section for the letter T and you can find 100Base T in the section for the letter O. You can find alphabetized entries on the following pages: Note: The formatting used to create this document may not adhere to the current format for creating documents. Always use the guidelines listed as they are written and not how they are formatted within this document. A... 6 B...7 C...8 D...10 F...10 H...11 I...13 L...14 M...14 N...14 P...14 R...15 S...15 T...15 U...15 W P a g e

6 A abbreviations and acronyms An acronym is a pronounceable word formed from the initial letter or letters of major parts of a compound term. An abbreviation is usually formed in the same way but is not pronounced as a word. Acronyms are almost always all caps, regardless of the capitalization style of the spelled out form. Abbreviation: mph for miles per hour Acronym: ROM for read only memory When to spell out: Always spell out an abbreviation or acronym on first occurrence if you think your audience may not be familiar with it. Define the term if its meaning isn t self evident. Consider including acronyms and abbreviations in the glossary. (In some cases, such as reference material that is not likely to be read sequentially, you may want to repeat the spelled out form on first occurrence in each chapter or major section.) Punctuation: Don t use periods except in abbreviations for customary (nonmetric) units of measurement or in the abbreviations U.S., a.m., and p.m. Plural form: Don t add an apostrophe before the s when you form the plural. RAMs, ROMs If the acronym or abbreviation ends in an s, add es. RTOSes able (suffix) When you add able to a word ending in e, drop the e unless the word ends with a soft c or a soft g. browsable, deletable, scalable, sharable, sizable, upgradable changeable, pronounceable, purgeable, serviceable and/or Rewrite to avoid this construction. application A computer program that performs a specific task, such as word processing, database management, and so on. Don t use app or apps. The terms application, program, and software can all be used to refer to this type of program.

7 LONGWARE, Inc. B The Text File Company boldface Use italics, not boldface, for emphasis. In instructions, boldface type highlights information that you enter or GUI elements that you select. Select Custom Reports from the Reports menu. Click the New Report tab. book components The following items must be included in every user's guide, user's manual, book or corporate release, in the following order when intended for consumer use: Cover page Copyright and legal notices on its own page Edition notice page including date of completion Preface Table of contents Body content Index Back cover button Buttons always initiate an action when clicked or pressed. You click an onscreen button; you press a mechanical button, such as a button on a keyboard. Click the Save As PDF button. Press the Reset button. Button names: Write the names of buttons exactly as they appear onscreen. If the button s name uses sentence style caps, use italics. Click Cancel. Unlabeled buttons: If a button does not have a label (and there is no established name for the button), consult your product team to determine what to call it. Capitalize the name of the button. Click the Lock button. "displays a lock" Click the Search button. "displays a magnifying glass" Buttons and icons: If an element in the user interface looks like a button and acts like a button (causes something to happen when clicked), always call it a button (do not call it an icon). 7 P a g e

8 Icons that act like buttons: If an element in the user interface looks like an icon (displays a picture) but acts like a button (causes something to happen when clicked), you can call it either a button or an icon, but be consistent. See also icon. C can, may Use can to express the ability to perform a function. Use may (or might) to express the possibility of an action or event. Avoid using may to indicate permission granted by an operating system or program; use can instead. Correct: You can select other print options by clicking Options. Correct: You may want to use a timer to handle actions such as updating a clock. Correct: If interference is a problem, you might need to move your base station to a different location. Incorrect: You may print single sided or double sided pages. capitalization See headings. CD Abbreviation for compact disc. CD technologies include the following: CD ROM (read only) CD R (recordable) CD RW (rewritable); not CD R/W or CD/RW Refer to the specific technology of the disc or drive or use the general term CD, depending on the context. To refer nonspecifically to a drive that accommodates both CDs and DVDs, use optical disc drive or optical drive. Types: Types of CDs include audio CDs or music CDs, MP3 CDs, and data CDs. Noun form: Don t use CD ROM, CD RW, or CD R as a noun; the term must modify another word, such as drive or disc. Plural: As the plural, don t use CD ROMs, CD RWs, and so on. Instead use CD ROM discs, CD RW discs, and so on, or simply CDs. Disc and disk: Use disc, not disk, to refer to CD media. CD-ROM drive Not CD-ROM player. The speed of a CD ROM drive is measured in terms of a standard speed of 150 kbps. CD ROM drives transfer data at double speed, 4x speed, 6x speed, and so on. Hyphenate the adjective form: 24x speed CD ROM drive (Don t leave out the x.)

9 LONGWARE, Inc. The Text File Company click Use click to describe the act of positioning the pointer on an object and briefly pressing and releasing the mouse button. Don t use click on. (You don t click the mouse button, you press and release it.) Use left click and right click when you need to distinguish between clicking using the left and right mouse buttons. code font Code font is a fixed-width font used for code. Always use Courier. Uses: Use code font for the following: Code listings Small pieces of sample code Computer-language elements such as reserved words, literals, variables, and routines Commands that appear in running text colons When possible, a colon in text (including a colon used before lists or steps) should be preceded by an independent clause (a complete thought, with both subject and verb). Your computer includes these storage devices: A hard disk drive A CD ROM drive It s okay for a colon to precede lists or steps even if it is preceded by only a partial thought (exception to The Chicago Manual of Style). Your computer includes: A hard disk drive A CD ROM drive See also lists. commas Use the serial comma (a comma preceding and or or in a list of three or more items). Filepad is compatible with Windows 95, Windows 98, Windows Me, Windows NT Workstation, and Windows 2000 Professional. copyright page All documentation must have a copyright page or copyright notice. In a printed book, the copyright information is usually on the second page, which does not have a page number or a running footer. LONGWARE, Inc. templates should include required copyright information. If not, consult the Legal department. 9 P a g e

10 D dialog box Use dialog box and not pop-up or a variation thereof. disc Use when you refer to a compact disc, videodisc, optical disc, or other laser technology discs; otherwise, use disk. In ongoing references to laser technology discs, disc is preferable to CD or DVD. See also CD. Insert the disc in the optical drive of your computer. disk Not diskette, flexible disk, floppy, or floppy diskette. Use disc when you refer to a compact disc, videodisc, optical disc, or other laser technology discs. (If the medium is magnetic, it s disk.) Don t use disk as a short form for disk drive. Floppy disk: Use floppy disk to distinguish from hard disks or compact discs; never use just floppy for this purpose. Disk references: In user documentation, use disk instead of volume to refer in general to floppy disks, hard disks, and shared disks. Articles: Use an article when appropriate. the disk; a disk double click (n.), double-click (v.), double-clicking (n., v.) Note hyphenation. Double clicking allows you to work faster. You do this by double clicking the icon. F file Refers to any entity stored on a disk, regardless of whether the user can open, edit, or print it. Filepad Capitalize only the first letter, never use FilePad. first person Don t use; rewrite in terms of the reader or the product.

11 LONGWARE, Inc. H The Text File Company headings Capitalization: Use title case for all headings Determining System Requirements Structure: Use gerund based task-oriented headings where applicable. Installing Filepad highlighting Use notes and other notices sparingly. They lose their effectiveness if they appear too often. Don t use a Note tag immediately before or after a Warning or Important notice or immediately after a text head. Bold, Boldface: Use italics, not boldface, for emphasis. In instructions, boldface type highlights information that you enter or GUI elements that you select. Select Custom Reports from the Reports menu. Click the New Report tab. Italics: Use italics to emphasize a word or phrase (but don t overdo it). Make sure that the power cable is plugged in and that power is available at the outlet. Notes: Use the Note tag for information that is relevant to a topic but that may not apply to all readers. You can also use a note for a bit of information that s tangential to a topic. Warnings: Use a Warning notice when the reader needs to know that an action may cause bodily injury, damage to hardware or software, or loss of data Important: Use an Important notice to alert the reader to significant potential trouble spots that do not cause bodily injury, damage, or loss of data. hit (v.) Don t use to instruct users to press a key; use press instead. hyphenation In general, hyphenate two words that precede and modify a noun as a unit. Follow this rule especially when: Confusion might result if the hyphen were omitted, as in read only memory The second word is a participle, past or present, as in binary coded decimal or color matching algorithm The two modifiers are a number or a single letter and a noun or a participle, as in 16 bit word or D shaped connector (always use a nonbreaking hyphen in this case) Follow these guidelines in various specific cases: Units of measure: When you use a spelled out unit of measure in a compound adjective, hyphenate the compound (3.5 inch floppy disk). When you use an abbreviation or a metric unit of measure, including KB, MB, mm, and so on. Location compounds: Hyphenate compounds such as lower left corner, top right portion. 11 P a g e

12 Special cases: Don t hyphenate disk drive or hard disk as nouns or as adjectives. Adverbs: Don t hyphenate compounds with very or with adverbs that end in ly. very good time recently completed project Combination keystrokes: In combination keystrokes, use nonbreaking hyphens to signify that the first key or keys should be held down while the last key is pressed. (Don t use hyphens if each key should be pressed and released separately. In such a case, use a nonbreaking space.) Be sure to explain this convention on first use. Control Shift N Esc N I icon An icon is a graphic that represents another item, such as a file in a window or on the desktop. Icons that don t act like buttons: If an element in the user interface looks like an icon (displays a picture) and doesn t act like a button (does not initiate an action when clicked), always call it an icon. For example, always call the following items icons: An album icon A film roll icon A hard disk icon Icons that act like buttons: If an element in the user interface looks like an icon (displays a picture) but acts like a button (causes something to happen when clicked), you can call it either a button or an icon, but be consistent. For example, the following interface elements act like buttons, but look like icons: A toolbar button A Quick Launch icon in the taskbar Icon without a label: If an icon does not have a label (and there is no established name for the icon), consult your product team to determine what to call the icon. Lowercase the name of the icon. See also button. important See highlighting. italics See highlighting.

13 LONGWARE, Inc. L The Text File Company left click See also click. lists Two types of lists are available: bulleted and numbered. Avoid nesting bulleted lists within bulleted lists or numbered lists within numbered lists. Also avoid using combinations of numbered and bulleted lists that contain more than a few items. In such cases, the hierarchy can easily become confusing. See also lists (bulleted); lists (numbered). lists (bulleted) Use a bulleted list when you want to stress the parallelism of a number of options, elements, or rules or to present instructions that do not need to be performed in a particular order. Introductory punctuation: Precede all lists with colons, whether the text before the colon is a complete thought or a partial thought (exception to The Chicago Manual of Style). See also colons. Capitalization: All list items start with a capital letter. Punctuation with a list: List items that are fragments or that complete the thought started by the main clause have no period; list items that are complete sentences have a period. Parallelism: Within a single list, all bulleted items should be parallel. In Filepad you can cut, copy, or paste text as follows: To cut text, select the text. In the Edit menu, click Cut. To copy text so you can paste it in another location, select the text. In the Edit menu, click Copy. To paste text that you have cut or copied, place the cursor at the point where you want to paste the text. In the Edit menu, click Paste. lists (numbered) Use a numbered list when you want to stress the sequential nature of steps, rules, or instructions Each item in the list should be a complete sentence. Use sentence-style caps for each item and end each item with closing punctuation. To save a document as text only: 1. Click on File and select Save As. 2. Specify the filename and location. 3. Select Text Only format. 4. Click Save. 13 P a g e

14 M MB Abbreviation for megabyte and megabytes. Use a nonbreaking space between the numeral and the abbreviation. Adjective: Don t hyphenate the adjective form. 20 MB hard disk Noun: In the noun form, use the preposition of before the unit quantified by the value. 20 MB of memory menus Anything that can be chosen in a menu is a menu item; some menu items are also menu commands (or simply commands). Use menu item to refer to items that aren t commands, such as window names in the Window menu. Don t use menu option. A menu item is in a menu, not on or under a menu; a menu contains items or commands. Pull-down menus: List each item in order. You Click a menu and Select an option. Click on the File menu. Select Open. Click on the File menu. Select Save As. menu titles Note capitalization: Edit menu, File menu, and so on. Write menu titles exactly as they appear onscreen. If the menu s name uses sentence style caps, use italics. menu types Note hyphenation: pop up menu, pull down menu. Another type of menu is the shortcut menu. N Note See highlighting P pop-up, pop up See dialog box. pull-down (adj.) Note hyphenation.

15 LONGWARE, Inc. R The Text File Company right-click See also click. S save You can save a file on a disk or to a disk, but not onto a disk. T text file Two words. toolbar One word, lowercase. An area containing buttons, such as at the top of some application windows. Don t call toolbar buttons shortcuts. U user's guide, user's manual Not user guide or user manual. W warning See highlighting Windows Use the product name excluding the Microsoft brand name except where necessary for clarity. Correct: Windows 95, Windows ME, Windows 7 Incorrect: Microsoft Windows P a g e