|
|
|
|
Technical Writing 101: A Real-World Guide to Planning and Writing Technical Documentation capitalization in table titles capitalization of window parts
possessive form of noun
|
acronyms back to topAvoid excessive use of acronyms. In each chapter, introduce every acronym by writing out the full wording and putting the abbreviation in parentheses. Thereafter, use only the acronym. Example: The graphical user interface (GUI)... acronymswith indefinite articles back to topThe article used (a or an) depends on the usual pronunciation of the acronym. Examples: a North Carolina State University professor, an NCSU professor, a NATO treaty bold type back to topGenerally, use bold type for the names of things that users can select.
The following items are not bold; however, they are capitalized according to how they appear in the software:
Exception: desktop menu (not capitalized, not bold) Do not use bold for callouts when pointing out selectable items in figures. callouts back to topUse .5 pt. lines for callouts. capitalizationin lists back to topCapitalize the first word in each list item. capitalizationin captions back to topUse sentence style (initial cap first word only). For window titles, match capitalization in the software. Do not capitalize the word window. Example: The Open File window is displayed. capitalizationin headings back to topUse initial capitalization for every word in the book title, except prepositions, articles, and conjunctions. Use sentence style (initial cap first word only) for all other headings. capitalizationin table titles back to topUse sentence style (initial cap first word only). capitalizationof window parts back to topMatch capitalization in the software. Do not capitalize words such as field, tab, pane, button, list box, and window. Example: The Personal tab is displayed. Do not capitalize window classes or window types. Example: A warning window is displayed. Always use OK for the button on the GUI. Always use ID as the abbreviation for identification. compound words back to topUse a hyphen to form compound words. Exception: Use the en dash in compounds when combining open compounds. (See en dash for examples.) computers are not people back to topAvoid "humanizing" machine interactions. Problem: The machine remembers your choices. Example: The machine stores your choices. Courier font back to topUse Courier font to highlight what the user types. Use italic Courier to show variable information typed by the user. Example: To start the IOT server, type the following command:RUNiot_Server pathname ellipses in GUI objects back to topWhen describing a part of the GUI, omit any ellipses. If, for example, the File menu has an "Open..." choice, describe it as the Open choice in your document. em dash back to topUse for a break in thought or abrupt change in sentence structure. See also parentheses. Do not put spaces before or after the em dash. Example: The snowalways welcomed by childrenclogged the roads. en dash back to topUse the en dash to connect dates, times, and numbers. Use the hyphen for compound adjectives. Use the en dash in compounds only when combining open compounds. Examples: 19891995, the North CarolinaVirginia border figures, introducing back to topAlways precede a figure with a reference to the figure by number. The Location window is displayed
(Figure 2-5). The Location window is displayed
(Figure 2-5 on page 2-10). The status bar in the Location
window shows this information (see Figure 2-5). The Location window, shown
in Figure 2-5, has three sections. Search the Last Name field
to display an alphabetical list of clients, as shown in Figure 2-5. figures, placement back to topAnchored frames should hang off a blank anchor or tiny paragraph. (Ask the template designer to create one of these formats if your project's template doesn't have either of them.) Shrink wrap the anchored frame around the graphic (Esc m p). Be sure the frame's Anchoring Position is set to Below Current Line. future tense back to topReplace with present tense when possible. gender back to topUse plurals or specific descriptions to avoid he, she, he or she, s/he, and it. See the example below. Problem: The programmer writes code. He then compiles it. Example: The programmer writes
code and then compiles it. indexing back to topNo initial capitalization unless it's a proper name. Use gerunds whenever possible. Use singular for nouns. Collapse similar entries with secondary entries:
Instead of: planting bulbs italic type back to topGenerally, use italic type for emphasis. Some docs also use italic type for placeholders. keystrokes back to topUse a hyphen to connect keystrokes that are performed simultaneously. Example: Ctrl-D [press the Ctrl key and the D key simultaneously] Use a space to separate keystrokes that are pressed in sequence. Example: Press Ctrl-M N to display the New window. Latin abbreviations back to topUse the English equivalents. See e.g., etc., and i.e. noun strings back to topAvoid noun strings. If you
have one, hyphenate the words that are used as adjectives to aid comprehension. Example: UNIX-based workstation, end-user access, newly acquired software only placement back to topPlace only with the sentence part it modifies. parentheses back to topUse for tangential material. If the material is crucial to the sentences, parentheses are inappropriate. See also em dash. Example: All students are required to study calculus (offered by the mathematics department). passive voice back to topAvoid passive voice. possessive form of noun ending in s back to topIf a singular noun ends with an s, create the possessive form by adding 's. Example: Dr. Seuss's books procedures, introducing Use a complete sentence ending with a colon, and follow the same grammatical pattern for all introductions in a document. Example: To print the document, follow these steps: punctuation after emphasis back to topPunctuation that follows an emphasized item is also emphasized. Example: Press Ctrl-D, then press Ctrl-S. punctuation in figure captions back to topUse no punctuation at the end of the caption. punctuation in lists back to topDefault punctuation: None. If one item is a complete sentence that stands alone, put a period at the end of every item in that list. punctuation in quotes back to topPeriods and commas go inside the quotes unless the quote is something that the user types. Other punctuation is placed with the clause it modifies. selection, describing back to topDescribe selections in the order the user makes them. Example: Select the File menu, then Open. serial comma back to topPrecede the final "and" in a series with a comma. Example: breakfast, lunch, and dinner slash (/) back to topNo space before or after a slash. space after periods back to topUse one space after a period. FrameMaker's Smart Spaces feature will prevent you from typing multiple spaces. split infinitive back to topAvoid split infinitives, but do not mutilate your sentence to remove a split infinitive. tables, placement back to topHang tables from a blank tiny or anchor paragraph. trademarks back to topUse trademarked terms as adjectives, not nouns. Mark the first instance of a trademark in the front matter and in the body of the document. Omit the trademark symbol in subsequent mentions. Example: The Widget (TM) product offers... never Widget offers... Copyright © 1997-2001 Scriptorium Publishing Services, Inc. All rights reserved. Last update: May 25, 2004 . Maintained by Alan Pringle. |