- Books, Literature, and Writing»
- How to Write
Technical Communications Text and Paragraph Formatting Procedures - Sample Guide
Conventions are commonly used phrases, or reference methods.
When using the acronym for the first time, use the complete term, then display the acronym in parentheses ( ).
Use the following formats for these terms: Internet, and email.
Anything that may endanger the user, an application, or a device, should be discussed in a caution. CAUTION should be uppercased, bolded and red. Add a colon (:). The actual information in the note should be italicized. Example: CAUTION: This only applies to this screen.
All text must be shown in black, with the exception of Cautions, which are shown in red.
Use the following compound words: Website, Webmaster, Database, Filename.
Always be consistent. What ever terms or approach that you use, use it throughout the document.
Do not use contractions such as don't, isn't, can't, etc.
Whenever another section is referenced, or discussed, include the text in italics.
Refer to fields using the exact field label. Field label text is shown in bold, 10 pt Arial. Example: In the Name field… The exception to this would be fields discussed in a table. Due to limited space, bold the label, but leave it at 9 pt. Arial.
Use the term the user, rather than he/she. Use the term their, rather than his or hers, to indicate possession. Example: The user must enter their proper login and password.
Keep headings as short as possible. Always insert text between headings.
Keys should be shown in brackets. Tagged with Arial 9 bold. Example: Press [ENTER].
Any information to be added to a topic should be tagged as a Note. NOTE should be uppercased, bolded. Add a colon (:). The actual information in the note should be italicized. Example: NOTE: This only applies to this screen.
Page breaks should be used to manually start a new page, rather than manually forcing a new page by entering numerous returns [Enter]s. Page breaks should always be inserted before a Heading 1 paragraph. Page breaks should always be inserted if 1 or 2 lines in a paragraph are widowed or orphaned. Insert a page break in front of the paragraph.
When using acronyms such as PC simply add an s to indicate more than 1. Example: PCs
Positions, Titles, or Departments
When referencing a specific position, title or department, enter them with initial uppercase letters. For generic references to these words, enter the words in lowercase letters.
Keep sentences and paragraphs short. Maximum of 3 sentences per paragraph.
Do not use slang. Always use professional grammar.
Each step is to contain 1 command or action. The result of that action is discussed in the same step. Screen shots are shown below the step. Example: 1. Select Tools from the toolbar. The toolbar menu, shown below, displays. (Menu is inserted here.)
Term to be Defined
A term to be defined is shown in 10 pt. Arial italics. Example: Radio Frequency refers to …
Terminology and Definitions
When using an important or technical term for the first time, italicize the text.
Third Person Use
Third person (you, your, etc.) is acceptable.
Information that the user is to type in is shown in 9 pt. Arial, bold. Example: Type sh – le.
Use white space for clarity and organization.
Use paragraph tags that have been established to format text and paragraph settings. The following table contains a list of common paragraph tags and descriptions.