ABC, Inc., Writing Style Guide
Bulleted Lists and Numbered Lists
Use of Bold, Italics, Underline and Quotation Marks
Introduction
The "ABC, Inc., Writing Style Guide" was developed to help employees write clear and concise documents that have a coordinated professional style. By having a set of writing standards implemented on all documents, we will have a consistent writing style that will further aid in creating high quality products for our customers. Please use these guidelines as a tool of writing professionalism, but if a customer specifically asks for special headings, fonts, or style, accommodate their wishes but do not compromise the quality. If there are any questions or problems that are not covered in this document, please ask the technical writers for assistance.
Words Not To Use
There is a distinct difference between computer terminology and proper English, nonetheless many people still use computer terminology or slang in documentation. Words that may mean the same thing in both computer terminology and English are often spelled differently. Computer terminology tends to simplify words while still retaining the same sound and meaning, but it looks different in text. Listed below are some words that are not allowed in documentation. (Every computer slang word is not listed below, so when writing a document or on-line help be conscious of the difference.)
- Do not use shorthand words like "h/w" for hardware or "s/w" for software.
- Do not use words like "grab," use the word "select" instead.
- Do not use the word "you" when referring to the user. Manipulate the sentence so "one" or "user" can be used instead. This rule does not apply to "Notes."
- Do not use numerals (under 10) when writing in formal documents. Write the word one, two, three, etc. Numbers over 10, though, can be in numeric form. This rule does not apply to mathematical equations (e.g. 10+3 = 13).
- Try not to use the word "his," "her" or "his/her" when referring to the user. Sometimes this is unavoidable but do your best.
- Do not write email or online, use a hyphen between the words, e.g. e-mail and on-line. While it may be easier to write email, it is not correct.
- Do not use the word "called" when referring to a title, use the "titled" instead.
Example…
Incorrect: The database called "Customer Data."
Correct: The database titled "Customer Data."
- Always write "go to" as two separate words, not "goto."
- Do not use the word "web" or "net" as abbreviations for "internet" in formal documents. If one is writing about the "web directory" or "web page" that is obviously ok, but do not use "web" as a replacement for "internet."
Abbreviations and Acronyms
Abbreviations are often used in the computer industry to identify programs and projects among people who have the same knowledge-base. The abbreviations that computer specialists use with one another are easily understood among themselves, but to an outsider or customer, the abbreviations may be new and unrecognizable. Therefore, when using an abbreviation, first write out the entire word or phrase and then follow that with the abbreviation in parentheses, e.g. American Medical Association (AMA). Initial explanation of an abbreviation is imperative to the reader understanding the document's message. Imagine if a document read, "I am a member of the WWF." The reader does not know if WWF stands for World Wrestling Federation or World Wildlife Federation.
Acronyms are a type of abbreviation. They are formed by using the first letter of the word(s) and pronouncing the letters together to create one word, e.g. random-access memory (RAM). (Notice there are no periods between the letters in RAM.) Once the acronym has been established in a document, from that point on it should be typed in all capital letters using the "Small Caps" font (see Small Caps).
Abbreviations
- Use e.g. to abbreviate "for example" and use i.e. to abbreviate "for instance." Do not capitalize these abbreviations and do not use them to begin a sentence.
- Do not use the abbreviation "&" use the word "and", unless a company designates it in their name, e.g. Barnes & Noble.
Example…
Incorrect: I went to Barnes & Noble for a book & pen.
Correct: I went to Barnes & Noble for a book and pen.
Acronyms
- Acronyms must first be defined before being used in a document. Even if the acronym is widely known.
Example…
Incorrect: Welcome to the ACLU.
Correct: Welcome to the American Civil Liberties Union (ACLU).
- Acronyms are not placed in quotation marks, use the "Small Caps" font when typing them in.
Example…
Incorrect: I have a new HTML editor on my computer.
Correct: I have a new HTML editor on my computer.
Note: If you are unable to access the "Small Caps" option, then make the font one point smaller than the font being used.
Proper Tense Usage
When writing a document describing an application's function. Do not say the application "will do" this or "is going to do" that. Write it in the present tense.
Another problem is mixing up future, present, and past tense in documents. Past tense describes something that has occurred in the past, e.g. "displayed a character." Present tense describes something that is occurring now, e.g. "displays a character." Future tense describes something that will happen, e.g. "will display a character."
The present tense is most often abused. "Displays" and "displaying" are both present tense, but "displaying" is present perfect. "Displaying" tells the reader that the computer or application is displaying the information at that very moment. On the other hand, "Displays" tells the reader that the computer or application can display the information, but the exact time is irrelevant.
Example…
Incorrect: The document is having three buttons.
Correct: The document has three buttons.
And…
Incorrect: After entering the data, the application is displaying the correct answer.
Correct: After entering the data, the application displays the correct answer.
Punctuation and Spacing
Slashes
Slashes are used to separate words and show omission, e.g. miles/hour for "miles per hour." It can be used to indicate alternatives, e.g. "Please call 555-1099/1098." In formal documents do not use the slash to represent per, write out the entire phrase. The slash can be used to represent "or" or "and." Many people know that the slash miles/hour represents miles per hour, but it is not right to assume a reader knows what the slash will represent in lesser known phrases. If a document read "applications/hard drives" the reader does not know if the slash represents "or," "and" or "per."
- Do not leave any spaces between words and slashes.
Example…
Incorrect: Dog / Worm / Red.
Correct: Dog/Worm/Red.
Parentheses
Parentheses are used to enclose words or sentences. They are mainly used to offset a remark or insert related information. The following are examples on correct punctuation and usage of parentheses.
- Parentheses can be used to display an acronym.
Example…
The user downloaded a recipe from the National Cooking Association (NCA).
- Parentheses do not affect the punctuation of a sentence, unless the entire sentence begins and ends in parentheses.
Example…
The circumference of the racetrack is approximately 5 kilometers (3.1 miles).
And…
The raccoon frightened me. (Raccoons are distant cousins of bears.)
Spacing
- There should be one space after a comma and semi-colon, and two spaces after a period and colon.
- Line spacing in documents should be either double-spaced or single-half spaced, never just single-spaced. Single spacing is much too hard on the reader's eyes.
Links and URL Addresses
Links
When inserting a link into an on-line help page, the link may be in color. If referring to a certain link, but not inserting a link, type it in bold. In documents, simply use quotation marks.
Example (on-line help):
Click on the Company link, to access http://www.widgets.com.
Example (documents):
Click on the "Company" link to access http://www.widgets.com.
URL Addresses
If a user is not familiar with computers, the user might type in everything they see in the directions. When directed to type in a URL address, some users type in the quotation marks that surround the address; some even type in the periods. If a user does this, the page will probably not appear, so to avoid any confusion always bold URL addresses. If a URL address is hyperlinked it will appear in a different color and be underlined, in this case, don't worry about bolding the address.
Example…
Incorrect: For the best price on widgets, go to "http://www.widgets.com."
Correct: For the best price on widgets, go to http://www.widgets.com.
Headers
For headers in documents and on-line help, please follow the guidelines listed below. Remember to indent headers the same distance throughout your document. If a header is followed by a list or directions, insert a colon after the header. All headers should be in the same font throughout the document. The header does not have to be in the same font as the text, but only two different fonts can be used in a document (one for the text, and one for the headers).
HEADER ONE:
The first-level header is bolded, underlined and four points larger than the text. All the letters in this heading may be capitalized as in this example.Exception -
Headings with underscores do not need to be underlined.Example:
Table Name: (IPL/APL)_LABOR_MISC
Header Two:
The second-level header is bolded and two points larger than the text. All the words in this heading should be capitalized (except articles: a, an, the, and, etc).Header Three:
The third-level header is italicized and two points larger than the text. All the words in this heading should be capitalized (except articles).HEADER FOUR:
The fourth-level header is neither bold nor italicized, but it is two points larger than the text. All the words in this heading should be capitalized (except articles).
Capitalization
Capital letters are used for proper nouns, titles, and the first word of a sentence.
- Do not capitalize common nouns such as "user," "customer," "server," "database," "field," "box," or "application," unless the word is part of a title.
Example:
Incorrect: The User selects a Customer name from the "Nightly Customer" field.
Correct: The user selects a customer name from the Nightly Customer field.
And
Incorrect: Springfield Zoo's Database was out of order.
Correct: Springfield Zoo's database was out of order.
Correct: The Springfield Zoo Database was out of order.
And…
Incorrect: The Springfield Zoo user will enter the Tiger Age Data, Lion Height Data, and Puma Weight Data for the Springfield Big Cat Database.
Correct: The Springfield Zoo user will enter data into the fields Tiger Age, Lion Height, and Puma Weight, for the Springfield Big Cat Database.
- Do not use all CAPITAL LETTERS for nouns (unless they are abbreviations like HTML or first-level headers). Capitalize the first letter of the word and use quotation marks instead. The first letter is capitalized because it designates (like a title) the menu, button, etc. to be used.
Example…
Incorrect: The user selects PRINT from the FILE menu.
Correct: The user selects Print from the File menu.
Note:
Table of contents and indices automatically capitalize letters. This is acceptable.
- If all capital letters must be used in on-line help because the word appears in all capitals on-screen in the application, then use the "Small Caps" font.
Example…
Incorrect: Click on the FELINE AGE button in the SPECIES menu.
Correct: Click on the FELINE AGE button in the SPECIES menu.
- Always capitalize ABC, Inc., whether it is ABC, Inc.,
- First-level headers should be in all caps.
- Capitalize acronyms, but remember to use the "Small Caps" font or make it 1 point smaller.
Example…
Incorrect: The user accessed the HTML page.
Correct: The user accessed the HTML page.
- Do not capitalize job titles, unless they are attached to a proper noun.
Incorrect: The Project Manager was assigning tasks.
Correct: The project manager was assigning tasks.
Correct: Project Manager Tom was assigning tasks.
Small Caps
- First click on the "Format" drop-down menu and select "Font."
- Then, click on the box titled "Small Caps."
- If small caps are unaccessible, then highlight the word and decrease the font by 1point.
Bulleted Lists and Numbered Lists
Numbered lists are used when describing a set procedure. Bulleted lists are used when listing qualities.
Example:
Incorrect: The following are holidays at ABC, Inc.,:
- Thanksgiving
- Labor Day
- Memorial Day
Correct: The following are holidays at ABC, Inc.,:
- Thanksgiving
- Labor Day
- Memorial Day
And
Incorrect: How to park at ABC, Inc.,:
- Turn into the second entrance on the left.
- Choose one of the first three rows.
- Select a spot and park diagonally in it.
Correct: How to park at ABC, Inc.,:
- Turn into the second entrance on the left.
- Choose one of the first three rows.
- Select a spot and park diagonally in it.
Use of Bold, Italics, Underline and Quotation Marks
Bold
- Use bold face text when inserting author notes. If writing on-line help, colors may be used, but remember to be consistent with the use of color. If one note is colored blue, then all notes must be blue.
Example:
Incorrect: Note: Select a dealer only if you have the appropriate ID number.
Correct: Note: Select a dealer only if you have appropriate ID number.
- In on-line help, any "text to be inserted" should be bolded.
Example:
Incorrect: In the box, type Yeats/help.
Correct: In the box, type Yeats/help.
- In documents, always bold any text to be inserted. That is, if an application calls for a user to type specific text in an area, that text should be bolded. When ending a sentence with text to be inserted, make sure the period is not bolded.
Example:
Incorrect: In the box, type "JDLL/12."
Correct: In the box, type JDLL/12.
- In documents bold extensions.
Example:
Incorrect: Enter the extensions as ".xls" or ".htm" or ".csv" or ".doc".
Correct: Enter the extensions as .xls or .htm or .csv or .doc.
Italics
- Italics are used to emphasize a word or phrase.
Example:
The brochure didn't say I might have fun, but that I would have fun.
Underline
- Underline is not to be used. It is confusing for some users, who may think that an underlined word is a hyperlink.
Quotation Marks
Quotation marks can be used to display a title or repeated text but not to emphasize.
- Use quotation marks when referencing a "button," "link," "screen" etc when the name of the button is confusing in the sentence. Quotation marks are to be used the first time you refer to a button, but after that, only the name of the button needs to be capitalized. This will reduce the number of keystrokes and give the document a better appearance.
Example:
Incorrect: Click on the "Elk" button. Then select the "Hound" screen. The "Elk" button will now be highlighted on the "Hound" screen.
Correct: Click on the "Elk" button. Then select the "Hound" screen. The Elk button will now be highlighted on the Hound screen.
- Always put the punctuation inside the quotation marks, whether it is a comma, period or question mark.
Example…
John read "Animal Farm," "Cannery Row," and "The Prince."
- Do not use quotation marks for names of companies or applications such as, Microsoft, Netscape, Adobe Photoshop, etc. simply capitalize the names of the applications.
- In on-line help and in documents text displayed by a message box should be in quotation marks.
- If asking a user to type a character or word in a box or field, do not use quotation marks, because the user might type the quotation marks in as well. Underline the text instead (see Underline)
- If one is writing for on-screen help and not a document words should be typed as they appear on- screen. If the button being referred to is in Arial text, the button should be written in Arial text in the on-line help. The size of the font does not necessarily need to match the font as it appears in the actual software, and quotation marks do need to be used if the font is different.
Example:
Incorrect: Press the PRINT button.
Correct: Press the Print button.
Top