IBM eTechnical Support Organization
eTSO standards and style guidelines
Author: eTSO operations team
NOTE: To find an item quickly, press Ctrl+F and type in a
keyword.
Introduction
This guide will help you write clearly and effectively and provides a reference for eTSO documentation standards. If you are new to eTSO, you probably want to read this entire document. If you are using this document as a reference, these brief chapter descriptions might help you find the information that you seek.
IBM and eTSO formatting conventions
This chapter provides rules and guidelines for working with the look and feel of your documents. It deals with topics like formatting tables and headings, emphasizing important information, working with graphics, and using colors in your documents.
IBM and eTSO writing standards
This chapter contains writing rules that are mandated by IBM and eTSO. If you do not follow these rules carefully, not only will your documents not conform to IBM standards, but they also might prompt another party to take legal action against IBM. Therefore, make sure you pay close attention to the rules presented here.
Standards for form types
This chapter provides standards that all brands should follow when creating documents using different form types.
Essential grammar and usage tips
This chapter provides some basic, essential rules and guidelines for English grammar and usage. Although you will not learn everything you need to know from this chapter (it would take several volumes to provide all that information), you will learn the basic necessities for writing correctly and properly.
Essential writing tips
This chapter provides some basic guidelines for writing clear, concise, and effective technical documents.
Writing for international audiences
This chapter provides guidelines that you should follow to make it easy to translate our documents into other languages. These guidelines will also make it easy for people who speak English as a second language to understand our documents.
IBM and eTSO formatting conventions
Follow these rules when you work with the look and feel of your document.
All documents are currently written using U.S. English grammar and usage rules. (Click here for a list of common spelling discrepancies between American and British English.)
For information on how to write and format headings, see the section Creating headings in documents.
Do not let tables conform to the size of the browser window, and make sure they do not exceed 15 cm in width. Otherwise, they may bleed off the screen.
|
Quest does not allow you to create tables that are wider than 15 cm. However, if you are working with a legacy document that contains tables that exceed 15 cm, you will not be able to resize them within Quest. You must edit them in another word processor and import them into Quest (see The Quest User's Guide for more information on importing documents). |
Lists that contain non-sequential items should be bulleted. However, if you refer to items in a list within the surrounding text, you may number the items to make them easy to reference.
For step-by-step procedures and lists in which the order of the items matters, use a numbered list.
NOTE: Always use proper parallel structure when you create a list. (For more information on parallel structure, see the section Creating parallel structure.)
If you include a file attachment within your documents, make sure that the file's size does not exceed 5 MB.
Follow these guidelines when you create graphics and include them in your document:
NOTE: Always include the graphic directly in the document; do not include it as an attachment. The only time you can include a graphic as an attachment is if the graphic is so detailed that it will be difficult for users to understand when viewed on something the size of a normal computer screen.
WARNING: Do not take screen shots of text and place them into documents as graphics! This prevents users from conducting searches on the text in the graphic and also causes problems during translation. The only exception to this rule is if the text is labels for a graphic.
Use these conventions when you use labels to draw attention to specific parts of a graphic.
|
Quest's word processor does not allow you to place text on top of graphics. Therefore, if you want to place labels on top of a graphic, you will need to edit the graphic in a graphics program before you import it into your document. |
The following example shows a graphic with properly formatted labels:
NOTE: Do not use captions in small documents! This section applies only to large documents. In smaller documents, the proximity of the graphic to the surrounding text should make it easy for the user to find the graphic. Thus, you should not need a caption to explain the purpose of the graphic.
You should use captions to label and explain figures and tables. When you create them, use 10 point (medium) Helvetica font. The font should be italicized. Capitalize the label (either Figure or Table) and the first word of the description. Place a period after the label and before the description. Use sentence-style capitalization for the description. If the description contains complete sentences, make sure you use proper punctuation; otherwise, do not punctuate the description.
Ex. Figure 2. Single-partition organization of storage. In a single-partition system, storage is divided into the supervisor area and the background. Only one program at a time can be executed in the background.
Ex. Table 1. List of parts and services
Notice that the description in the second example is not a complete sentence. Therefore, it does not end in a period.
NOTE: Place captions for tables above the table. Place captions for figures below the figure. If you are creating print documentation, make sure the caption is on the same page as the item with which it is associated!
Do not use colors for normal text! Use blue text for headings. (See the section Creating headings in documents.) You can use red to emphasize very, very important information, but use it sparingly. (See the section Emphasizing important information: notes and warnings.) Do not use any other colors.
Emphasizing file names and text output from a program
When you want to emphasize that example text is actual output from a program, use Courier font. You can also use this convention to distinguish file names from regular text.
Ex. "Copy the file newgroup.exe to the New Group folder."
Emphasizing important information: notes and warnings
When you want to call the user's attention to a specific piece of information, include it on a new line preceded by the word "NOTE", in boldfaced type, followed by a colon. Do not include extra line breaks around notes.
Ex. "NOTE: The previous example…"
Do not use any colors to emphasize notes. However, if a piece of information is absolutely essential, you can include it as a warning. Warnings may be either boldfaced and black or, if the information could potentially avert a disaster, boldfaced and red. Include an extra line break both before and after warnings.
Ex. "WARNING: Do not remove the disk while you download the file."
Ex. "WARNING: Do not type "format c:"!
If a procedure calls for users to perform a task that places them at risk of bodily injury, emphasize the risk as a danger note. The word "danger" should be boldfaced, red, and on a line by itself. The text of the danger warning should begin on the line after the word "danger" and should be boldfaced.
Ex. "2. Lift off the protective cover.
DANGER
The exposed board contains high
voltages. Use a fiber probe for the next step.
WARNING: Do not overuse the boldfaced and red formatting. If you do, users will become accustomed to it, and it will no longer contain the visual impact needed for such important information.'
|
If you insert a note or warning on a new line within a numbered list in Quest's word processor, the step immediately after the note or warning will revert to number 1. Until Quest's word processor can resume numbering schemes after a break in the list, you must create a borderless table with two columns (one for the numbers, one for the text of the steps), make each step of the procedure a separate row, insert the note or warning in a new row, and number the list manually. |
IBM and eTSO writing standards
The following chapters include information about IBM documentation standards. You must review this information carefully. If you do not follow these rules, not only will your documents not be consistent with other IBM documents, but they may also cause other parties to take legal action against IBM.
Certain verbs should be used to describe certain common actions. Refer to the following table when deciding what verb to use.
Verb |
Situation in which to use it |
appear |
Use this verb to describe dialog boxes and pop-ups that show up after the user performs certain actions. Ex. "Click New. The New Document dialog box appears." NOTE: Do not substitute the verb "display" for "appear" in instances such as this. |
clear |
Use this verb when referring to check boxes. Ex. "To disable the auto-spellcheck function, clear the Check my Spelling check box." |
click |
Use this verb to describe any single-click actions taken with the mouse, except those actions where the user must highlight items, select a check box, or select a radio button. (See the descriptions for the verbs "highlight" and "select.") Ex. "Click Yes." NOTE: Do not use "click on" to describe this action. |
click and drag |
Use these verbs to describe the action of holding the mouse button while moving an item. Ex. "Click and drag the folder you wish to delete to the Recycle Bin." |
display |
Use this verb only as a transitive verb. A transitive verb appears in sentences that contain an object. If the sentence contains no object, use the verb "appear." Improper ex. "Click Yes. The New Query dialog box displays." Note that, in the previous example, "display" is used as an intransitive verb. This example violates eTSO standards; the verb "appear" should be used instead. The following example shows proper use of the verb "display." Proper ex. "The table displays all the available options." |
depress |
Do not use this verb. Use "press and hold" or "click and hold" instead. |
deselect |
Do not use this verb. Use "clear" instead. |
double-click |
Use this verb to describe any action where the user must double-click the mouse. Ex. "Double-click the My Computer icon." |
enter |
Use this verb to describe an action where users must type in a variable. Do not confuse this verb with "type," which is used to describe an action where users must type in text verbatim (e.g. "At the command prompt, type "install" to begin installing the program"). Ex. "Enter the name of the query in the Query Name field." |
highlight |
Use this verb to describe one of two actions: clicking and dragging the mouse to select specific chunks of text or clicking an item to select it before performing some other action on it. Ex. "Highlight the document you wish to delete." |
press |
Use this verb to describe actions involving keyboard keys. Ex. "Press Enter." |
press and hold |
Use these verbs to describe actions that require the user to hold a keyboard key down while performing another action. Ex. "Press and hold Shift while clicking the document you would like to download." |
populate |
Do not use this verb to describe actions for fields. Use "enter" instead. Improper ex. "Populate the Name field with the query name." Proper ex. "Enter the query name in the Name field." |
select |
Use this verb when the user must activate a check box. Ex. "Select the New User check box." Use this verb to describe actions where the user does not use a mouse. This often occurs when you write instructions for text-based programs, such as VM. Ex. "Select option 3 from the menu." Use this verb when the user must choose a radio button. Ex. "Select the New Documents Only radio button and click OK." |
type |
Use this verb to describe an action where users must type in text verbatim. Do not confuse this verb with "enter," which is used to describe an action where users must type in a variable (e.g. "Enter your name in the Name field"). Ex. "At the A\> prompt, type "install" to begin installing the program." |
This section tells you how to label items that are commonly used in eTSO documents. It also provides proper spelling for these and other words.
Term |
When to use it |
button |
Use this term to refer to any clickable graphical element without a specific name (e.g. you would not use this term to refer to hyperlinks). Ex. "Clicking the Save button, located on the menubar, saves your file." NOTE: Do not use "button" with button names in procedures. The previous example describes what the button does; therefore, you can use "button." However, if you were telling a user to click the Save button as part of a command in a procedure, it would be written as follows: Ex. "Click Save." |
check box |
Spell this term as two words without a hyphen. Ex. "Select the New User check box." |
dialog box |
Use this term to refer to a window that appears and asks the user to respond to some sort of request. (Do not confuse this term with "pop-up," which refers to windows that appear but only give information or warnings.)
Ex. |
drop-down list |
Use this term to describe lists where users click a small down arrow to make the list appear. The following graphic shows a typical drop-down list:
Ex. |
|
Make sure you hyphenate this word. Do not capitalize it unless it is the first word of a sentence or title. |
field |
Use this term to refer to a blank area where users can enter alphanumeric characters. The following graphic shows a dialog box with a field in it.
Ex. |
figure |
Use this term to label graphics, diagrams, and charts to which you refer in the body of your document. Ex. "The Title dialog box appears (see Figure 2)." |
megabyte (MB) |
When you write this term, use all lower-case letters. Do not separate it into two words. When you write the abbreviation for this term, use all upper-case letters. Ex. "The term megabyte is abbreviated MB." |
menu |
Use this term to refer to a list of commands or options in a program. Ex. "The File menu provides a list of basic functions, such as saving or printing." |
menubar |
Use this term to refer to the row of buttons that usually appears near the top of a window in a program. Ex. "Click New, located on the menubar, to open a new document." |
navigation box |
Use this term to refer to a list of hyperlinks on a Web site. For an example of a navigation box, see the IBM Web site, http://www.ibm.com. Ex. "Click the Discussion Forum link, which is located in the navigation box." |
PDF file |
Use this term to refer to a portable document format file. NOTE: Do not refer to such as a file as being in "PDF format." Such phrasing is redundant, since you are really saying, "This file is in portable document format format." Instead, refer to the file as being "PDF style." |
pop-up |
Use this term to refer to a window that appears and offers the user information or a warning, but does not ask for any sort of interaction. The following example shows a pop-up window. Ex. "Click Yes. If you have not filled in the last row, warning pop-up appears." |
radio button |
Use this term to refer to a list of options where the user may select only one at a time. These options usually appear as several options followed by white circles; when the user clicks on one of these circles, a black dot appears in it. When the user clicks a different circle, the black dot disappears from the original circle and appears in the new one. Ex. "Select the New User radio button and click OK." |
table |
Use this term to refer to information arranged in columns and rows, such as the list of terms you are currently reading. Label tables and refer to them within body text just as you would a figure (see the definition for the term "figure"). |
Web site |
Use this term to refer to a site on the World Wide Web. This term should be spelled with an initial capital on "Web" and as two separate words. |
window |
Use this term to describe any window that can not be described as either a "dialog box" or a "pop-up" (see the definitions for these terms). Ex. "Double-click the Documents icon. The Document Maintenance window appears." |
wizard |
Use this term to refer to a feature that guides you through a process within a program. NOTE: Capitalize this term only if it is capitalized within the program. Ex. "The New Document wizard guides you through the process of creating a new document." |
Win95, Win98, WinNT |
Do not use these terms! The first time you refer to one of these operating systems in your document, you must use its full name (e.g. "Microsoft Windows 95"). Afterwards, you do not need to include the name of the company, but you still must spell out the product name (e.g. "Windows 95"). (For more information about referencing non-IBM products, see the section Disclosures and trademarks.) |
worldwide |
When you use this word as an adjective or noun, but not as part of the phrase "World Wide Web," make it all one word and do not capitalize it. |
World Wide Web (WWW) |
Capitalize the initial letters for all three words, and do not hyphenate the first two words. Also, make sure you always capitalize the "WWW" abbreviation. |
When you write headings for procedures, make sure you use the present
participial (-ing) form of the verb.
Improper ex. "How
to create a new directory"
Proper ex. "Creating
a new directory"
Steps within procedures should always begin with a command request (imperative) sentence. Avoid using narrative sentences when you explain the actions that users should perform. However, you should use narrative sentences to describe the results of those actions (i.e. reinforcement).
Numbered items vs. bulleted items
For step-by-step procedures, where the order of the actions matters, you should always use a numbered list. If, however, the user can select from two or more options for one of the steps, you should number the step, provide an intro explaining that they can select from the following list, and include the options in an indented, bulleted list. Consider the following example:
Ex. "Opening a Microsoft Word document
|
Quest's word processor can not create nested lists (such as the one shown in the previous example). Therefore, if you want to create a nested list within a document, you must generate the HTML outside of Quest and import it. For more information on importing documents, see The Quest User's Guide. |
Giving different options within a single step in a procedure
When possible, try to avoid giving the user options within procedures. Instead, give the easiest option available. However, make sure you use that option consistently across the steps in your procedure. Consider the following example:
Improper ex. "Editing a Microsoft Word document
In step 2 of the previous example, the author chose to instruct the user to select a command from the menubar instead of providing directions for how to select the same command from the File menu. However, in step 4, the author did the opposite and chose to instruct the user to select a command from the File menu instead of from the menubar. You should avoid switching back and forth between different alternatives in your procedures. Select one and use it throughout.
Providing reinforcement (i.e. the results of the user's actions)
Whenever possible, you should reinforce users' actions (i.e. provide them with the appropriate results so they know they did the right thing). Place the reinforcement immediately after the action that produces it. Consider the following example:
Ex. "Editing a Microsoft Word document
Notice that the author provided immediate feedback on the results of the action in step 1.
WARNING: Make sure that you only number actions in procedures! Do not make reinforcement a numbered item.
Improper ex. "Editing a Microsoft Word document
Emphasizing items with which the user interacts
Use boldfaced type to indicate an item with which the user interacts. Such items include the following:
Do not boldface the type of item, only boldface the name of the item. Consider the following examples:
Improper ex. "Click the File menu."
Proper ex. "Click the File menu."
When you describe an action involving a submenu, indicate it by using a dash followed by a right-arrow.
Ex. "Click File -> Save."
Do not use contractions in your documents. Instead, write out the words that make up the contraction. Consider the following examples:
Improper ex. "You shouldn't remove the disk while you copy the file."
Proper ex. "You should not remove the disk while you copy the file."
Avoiding gender-specific terms
Do not use gender-specific terms in your documents.
The preferred way to avoid using gender-specific words like "he" or "she" in your documents is to use second person or, in the case of procedures, command request sentences. Consider the following examples:
Improper ex. "The user will see a warning message. She should then click OK."
Proper ex. "You will see a warning message. Click OK."
Another way you can easily avoid using "he" or "she" by making your subject plural. That way, you will use "they" instead. Consider the following examples:
Improper ex. "The user will see a warning message. She should then click OK."
Proper ex. "Users will see a warning message. They should then click OK."
Do not use slang in your documents. Remember that we are creating materials that people from many different backgrounds rely upon. Therefore, we must make sure we do not alienate any portion of our users by using terms and phrases that they do not understand.
WARNING: Do not abbreviate the names of non-IBM products, such as Microsoft Windows 95!
Do not abbreviate words in your documents unless IBM approves of the abbreviations or they are industry standards. Consider the following examples:
Improper ex. "For more information, see the product's HMM."
Although IBM employees will probably understand what HMM stands for, most site visitors (especially first-time users) will not. Therefore, you should spell out such items. However, for industry standard terms, you can use abbreviations.
Proper ex. "This model contains a 3.6 GB hard disk drive."
Almost all users will understand that GB stands for gigabyte. Basically, when you are deciding whether or not to use abbreviations, think of your users, and decide whether they will understand what you mean.
Referencing chapters, sections, or other documents
Try to avoid repeating yourself within a document. If certain information is already available within the same document (or within a different, easily accessible document), you should provide a reference to that piece of information.
NOTE: If you feel the information is very important, you should repeat it instead of providing a reference to it. By doing this, you make sure that readers see the information instead of relying on them to follow your reference to retrieve the information.
When referencing other chapters, sections, or documents, follow these guidelines:
|
The Quest word processor allows you to include doc links to other documents in the Quest database. Therefore, more often than not, you will use the doc link feature to link to other eTSO documents and a hyperlink to link to IBM documents outside of eTSO or to non-IBM sites. |
When you write hyperlinks, make sure you include some content in the link itself. Avoid creating links that force users to search the surrounding text for clues about where the link will take them.
Improper ex. "To download the driver, click here."
Improper ex. "To download the driver, click here."
Proper ex. "Download the driver."
Proper ex. "Click here to download the driver."
NOTE: If you are using hyperlinks for your reference, do not enclose the item in double-quotes.
You should only include URLs if your hyperlink leads to a non-IBM site or an IBM site that is not part of the support site. For documents that are part of the support site, do not include the URL. Instead, write a content-rich hyperlink. (For more information on writing hyperlinks, see the section Writing hyperlinks.)
Improper ex. "To see a diagram of the motherboard, visit http://www.pc.ibm.com/support/motherboard_diagram.htm."
Proper ex. "Click here to see a diagram of the motherboard."
Improper ex. "For information about Lotus Notes, visit the Lotus homepage."
Proper ex. "For information about Lotus Notes, visit http://www.lotus.com."
Referencing figures and tables
NOTE: Do not include formal references to figures and tables in small documents! This section applies only to large documents. In smaller documents, the proximity of the graphic to the surrounding text should make it easy for the user to find the graphic. However, you may use textual references such as the following example:
Ex. "The following table shows the software that comes preloaded on your machine."
There is no difference in the way you should reference figures and tables. Also, unlike references to other chapters, sections, or documents, references to tables and figures do not need to be complete sentences. If the reference is not a complete sentence, however, you must put it in parentheses and place it before the period of the previous sentence. Consider the following example:
Ex. "The sales figures for the past three years show marked improvement (see figure 4)."
NOTE: Diagrams, graphics, and charts should be called "figures" when you reference them. Tables should be called "tables."
However, if you feel the user needs more information about the information provided by the referenced item, make the reference a complete sentence: "Sales have improved over the past five years. (To compare overall sales in 1993 and 1998, see figure 8.)"
NOTE: This section applies only to large documents. In smaller documents, the proximity of the graphic to the surrounding text should make it easy for the user to find the graphic.
Tables and figures should be numbered separately. For normal documents, use a sequential numbering scheme for all the figures and tables throughout the document. Do not use complicated, hyphenated numbering schemes. In other words, if you have 10 figures in your document, the last one should be labeled "figure 10" regardless of the chapter in which it occurs.
Ex. "Connect the lead to J17 (see figure 12)."
In the previous example, the figure’s label shows that it is the 12th to appear in the entire document.
For longer documents, such as HMMs, the numbering scheme should include the chapter number and the item number. Numbering for the second part of the label should begin anew for each chapter.
Ex. "Connect the lead to J17 (see figure 3-12)."
In the previous example, the figure’s label shows that it is the 12th to appear in Chapter 3 of the document.
All standard IBM disclosures and trademarks can be found on the official IBM legal site, http://www.ibm.com/Legal/. To find out when you should use trademarks, consult the IBM trademark guidelines Web site, http://iplwww.ncastle.ibm.com/trademark/trademar.htm.
Follow these rules on trademark use:
NOTE: You do not need provide a trademark symbol on items such as Microsoft in individual documents. The blanket trademark statement on the IBM Web site covers items such as these.
Do not communicate any information about whether or not a particular system (machine make, model) is Year 2000 ready. Do not create or publish any piece of information that includes such information.
If you must include information about Year 2000 compliance, refer the user to the IBM Year 2000 Web site, http://www.ibm.com/pc/year2000/driver.html. Also, when referring to Year 2000 readiness, use the term "Year 2000 ready." Capitalize the "Y" on "Year," but do not capitalize the "r" in "ready." IBM owns the copyright on this term.
Things to delete from documents
This section describes how each brand team should title their documents. Since each brand must include different information, the conventions between brands vary slightly. However, the following rules apply across all document titles:
NOTE: In the "Titling convention" column of the tables that appear later in this section, items that appear within angle brackets are those that the author must provide. All other elements should appear exactly as shown.
Documents in languages other than English
If you are publishing a document that is written in a language other than English, you must include the name of the language after the title in parentheses.
Ex. "Aptiva 2162 – Removing the case (Japanese)"
Form type |
Titling convention |
Example |
Parts information |
<brand> <product family> - <description> |
Ambra Achiever 2000 – 2233 Service parts |
Preloaded software information |
<brand> <product family> - <preload name> Preloaded software package information |
Ambra Achiever 2000 – AMBUBCE Preloaded software package information |
Product information |
<brand> <product family> - Product information index |
Ambra Achiever 2000 – Product information index Ambra Achiever 2000 (Type 2131-D0E) – Technical specifications |
Service hints & tips |
<brand> <product family> - <description> |
Ambra Achiever PC 3000 – Re-installing the original software for systems with USR modem/ESS 1688 sound |
SSD |
<brand> <product family> - <file description> |
Ambra Achiever DP/TP – Flash BIOS update (Level 1.2r1.3) |
Form type |
Titling convention |
Example |
All form types |
Aptiva <type> - <description> |
Aptiva 2140/2142 – Windows 95 Companion CD information |
Special situation |
Titling convention |
Example |
Too many families to list in a title |
Aptiva - <description with a qualifier that limits the machines to which the document applies> |
Aptiva – Updated driver for machines equipped with a 33.6 KBps modem |
Form type |
Titling convention |
Example |
SSD |
<brand> <product family> - <description and operating system> |
IBM PC300XL – Matrox video for Windows NT |
All other form types |
<brand> <product family> - <description> |
IBM Intellistation M Pro – Product information sheet |
Special situation |
Titling convention |
Example |
Two product families |
<brand> <product family 1>/<product family 2> - <follow titling conventions for specific form type> |
IBM PC300XL/PC300GL – Installing new video drivers |
More than two product families |
<brand> - <follow titling conventions for specific form type> |
IBM PC – Installing new video drivers |
Crossover between IBM PC and Intellistation |
IBM PC<product family>/IBM Intellistation <product family> - <follow titling conventions for specific form type> |
IBM PC300XL/IBM Intellistation M Pro – ZA9Q21P – Audio driver for Windows NT |
Form type |
Titling convention |
Example |
Parts information |
<brand> <product family> - <description> |
Ispirati 100 - 1166 Service parts |
Preloaded software information |
<brand> <product family> - <preload name> Preloaded software package information |
Ispirati 100/200 – AMETACF Preloaded software package information |
Product information |
<brand> <product family> - <description> |
Ispirati 200 (Type 1181-3EX) - Technical specifications Ispirati 200 – Product information |
Service hints & tips |
<brand> <product family> - <description> |
Ispirati 400 - Re-installing the original software on 2623 models preloaded Windows 95 |
SSD |
<brand> <product family> - <file description> |
Ispirati 400 – Flash BIOS update (Level 1.2r1.3) |
Form type |
Titling convention |
Example |
Product information |
Network Station <product family> - <description> |
Network Station Series 1000 (8362) – Technical specifications for the PCMCIA adapter |
Service hints & tips |
Network Station <product family> - <description> |
Network Station Series 2300 – Memory, adapters, and machine class files |
Service publications |
Network Station <product family> - <description or title of publication> |
Network Station Series 1000 – Configuring the Network Station for Java applications |
Special situation |
Titling convention |
Example |
Applies to all families |
Network Station - <description> |
Network Station – Technical specifications for the PCMCIA adapter |
Applies to more than one family |
Network Station <product family 1>/<product family 2> - <description> |
Network Station Series 1000/Series 2300 - Technical specifications for the PCMCIA adapter |
Form type |
Titling convention |
Example |
Service Publications |
NSM <version and release> on <operating system> - <description or title of publication> |
NSM V3R0 on Windows NT – Quick Start Server Guide |
All other form types |
NSM <version and release> on <operating system> - <description> |
NSM V1R3 on AS/400 – Editing config files |
Special situation |
Titling convention |
Example |
Applies to all operating systems |
NSM <version and release> - <description> |
NSM V1R3 – Solution to the color problem with Lotus Web Mail on NC Navigator 3.04 |
Form type |
Titling convention |
Example |
SSD |
<product description> - Files and drivers |
PCMCIA 16/4 Token-Ring Adapter – Files and drivers |
Product information sheet |
<product description> - Product overview |
Rapid Access Keyboard – Product overview |
All other documents |
<product description> - <document description> |
ComCentral 33.6 modem – Installation procedures for Windows 95 |
Special situation |
Titling convention |
Example |
Non-IBM product |
<product description> (non-IBM) - <follow titling conventions for specific form type> |
Seagate ATA hard disk drive – Files and drivers |
Form type |
Titling convention |
Example |
All form types |
<product family> <type> - <description> |
Netfinity 7000 – Novell NetWare 4.1 does not recognize more than 64MB of memory |
Form type |
Titling convention |
Example |
All form types |
TP <applicable systems> - <description> |
TP 770 – How to add more memory within OS/2 Warp TP 770 – Utility disk 1.1 for Windows NT |
Special situation |
Titling convention |
Example |
Multiple families and/or multiple submodels |
TP <product family 1><submodel 1> |
TP 770X/XD, 365X/XD – Utility disk 1.1 for Windows NT |
Too many families to list in a title or applicable to all ThinkPads |
TP General - <follow titling conventions for specific form type> |
TP General – Replacing the battery |
Creating headings in documents
When you create headings, try to avoid using complete sentences. If you do use complete sentences, you must punctuate the heading; however, when this happens, try to rewrite the heading if possible.
NOTE:
If your heading introduces instructions, make sure you use the
present participial (-ing) form of the verb.
Improper ex. "How
to create a new directory"
Proper ex. "Creating
a new directory"
Follow these rules when creating any level heading:
The following example illustrates a properly formatted first-level heading:
Ex. "Models supported by this release"
Use these rules to format different heading levels:
Heading level |
Font face |
Font size |
Font style |
Main heading |
Helv |
10 (medium) |
Bold/Blue |
Sub heading |
Helv |
10 (medium) |
Bold |
Sub-sub heading |
Helv |
10 (medium) |
Normal/Blue |
Body text |
Helv |
10 (medium) |
Normal |
Table heading |
Helv |
10 (medium) |
Bold |
Table text |
Helv |
10 (medium) |
Normal |
List heading |
Helv |
10 (medium) |
Bold |
List text |
Helv |
10 (medium) |
Normal |
Emphasized |
Helv |
10 (medium) |
Red |
Labeling versions, releases, and modification levels
Use lowercase for the words "version," "release," and "modification level," unless they appear with an official or shortened name of a system or program. Do not include commas in the official designation.
Spell out the version, release, and modification level and the full official name of the product at the first occurrence within the body of the document. After the first occurrence, you can omit the words "version," "release," and "modification level." Some products use an abbreviation, such as V2R3, to avoid confusion. Not all IBM products follow a consistent scheme for assigning numeric designations to versions, releases, and modification levels. If your product is initially announced as "IBM <product_name> version 1.0," then refer to it as "version 1.0," "v1.0," or simply "1.0," rather than "version 1 release 0" or "V1R0."
Proper ex. "This update applies to Lotus Notes version 4.1. Notes v4.1 users should download the following files."
Improper ex. "This update applies to Lotus Notes V4R1."
Include the version and release in the short titles of online books, because they are used to identify the level of the book. Generally, do not use the version and release in the titles of printed books, but include the version and release on the title page.
NOTE: Minimum required version: To state a requirement that includes later versions of a product, use the phrase "or later" to indicate subsequent versions.
Ex: "To use the transformers, you need DB2 UDB 5.1 or later."
Capitalizing terms from a program
When you use terms from a program in your document, do not capitalize them unless they are capitalized within the program. For example, if the file menu is capitalized on the main menu bar then, when you refer to that menu in your document, you should capitalize the word "File."
NOTE: Make sure you only capitalize a term when you refer to that item within the program. For example, if the word "File" is capitalized on the menubar, you would capitalize it when referring to the File menu. However, you would not capitalize it when writing about downloading a file.
Deciding how many spaces to put after sentence-final punctuation
The convention of putting two spaces after sentence-final punctuation developed to make it easier to distinguish between sentences written on typewriters (monospace fonts). Therefore, if you are using a monospace font (e.g. Courier), place two spaces after sentence-final punctuation. However, for all other font faces, use only one space after sentence-final punctuation.
Outside of document references, try to avoid using parentheses. If you must use parentheses, follow these rules:
Use double-quotes to distinguish text that the user must type or messages that appear in dialog boxes. Make sure you write the text exactly as the user must type it or as it appears on-screen. Consider the following examples:
Ex. "This release deals with the "Not enough virtual memory" error message."
Ex. "Enter "Test page.html" in the Save As field."
NOTE: If this text should be distinguished as output from a program, use Courier font without double-quotes. (For more information, see the section Emphasizing file names and text output from a program.)
Double-quotes should also be used when referencing chapters or sections within the same document. (For more information, see the section Referencing chapters, sections, or other documents.)
NOTE: If your double-quotes come at the end of a sentence, the sentence-final punctuation should be placed within them.
NOTE: If you want to know what information belongs in each individual field for a particular form type, see the appropriate Form type walkthrough document (parts info, preloaded software info, product info, service hints & tips, service pubs, or SSD). If you want to know how each brand should write titles for individual form types, see the section Titling documents.
This chapter provides the standards for each form type. If part of your document is not regulated by either the standard set forth in this chapter or the standards detailed in the rest of the document, that part is subject only to the standards set by your particular brand (see your BPM). In other words, the standards presented here are only those that regulate form types and apply to all brand teams.
This section provides standards that apply to all brands and to every form type. It contains some reiteration of ideas from the previous chapters, but these standards are especially important for you to remember and apply.
Colons should only be used after regular text that precedes a list. Do not use them after a heading even if the heading precedes a list.
Include content-oriented hyperlinks
When you write hyperlinks, make sure you include some content in the link itself. Avoid creating links that force users to search the surrounding text for clues about where the link will take them.
Improper ex. "To download the driver, click here."
Improper ex. "To download the driver, click here."
Proper ex. "Download the driver."
Proper ex. "Click here to download the driver."
Place one line break before level 1 and 2 headings
When you place a line break before level 1 (bold, blue) and level 2 (bold, black) headings, you draw the reader's eyes to them.
Use proper punctuation in all fields
Try to use complete sentences and proper sentence-ending punctuation. However, if you must use a fragment of a sentence, do not use sentence-ending punctuation. This situation will most commonly occur in short fields that do not require more than one piece of information.
Follow these standards when writing instructions in the "Additional Info" or "Body" fields
NOTE: For more information about this form type, see the appropriate form type walkthrough.
You should publish the following types of documents using the parts information form type:
Use the "additional information" column if the information will fit
"Additional information" should include all doc links leading to related items (technical specs, drivers, etc). It will also include pertinent information that might previously have been included as a footnote. If this information is too long, you should provide it as a footnote at the end of the document. In this case, provide a superscript number after the part description that corresponds to the footnote.
Label the column containing FRU numbers as "Replacement part numbers (FRU)"
In order to help customers who might not be familiar with our terminology, use the heading "Replacement part numbers (FRU)" to describe the column containing FRU numbers.
Preloaded software information
NOTE: For more information about this form type, see the appropriate form type walkthrough.
You should publish the following types of documents using the preloaded software information form type:
NOTE: For more information about this form type, see the appropriate form type walkthrough.
You should publish the following types of documents using the product information form type:
NOTE: All documents that you previously labeled "product information sheet" should now be labeled "product index."
Product indexes should be Unclassified, as should all documents to which you link from product indexes. (The doc link will not work if the document to which it links is Confidential or IBM Dealer Confidential and the product index is Unclassified.)
In some cases, you may be required to create two product indexes, one for Dealers and/or the PCHC (IBM Dealer Confidential) and one for the general public (Unclassified).
Exceptions to this rule are if the product is being pre-announced or channel filled--all documents, including product indexes, should be classified IBM Dealer Confidential (unless the Brand otherwise specifies).
NOTE: For more information about classifying documents, see The Quest User's Guide or the product information form type walkthrough.
Product indexes: use these standard headings
The following list shows the standard headings that you should use in your product indexes. If you have headings that can not be changed to one of the following, then they are not covered by our standards and do not need to be changed. However, if you feel your heading should be covered by eTSO standards, contact a member of the Operations team. Make sure you capitalize and spell your headings exactly as they appear in the following list.
Product indexes: do not use borders
Do not include borders around your indexes. Also, do not place a vertical line between columns of information.
NOTE: For more information about this form type, see the appropriate form type walkthrough.
You should publish the following types of documents using the service hints and tips form type:
Troubleshooting information: use these standard headings
The following headings provide an outline for your troubleshooting documents. Make sure you capitalize and spell your headings exactly as they appear.
NOTE: For more information about this form type, see the appropriate form type walkthrough.
You should publish the following types of documents using the service publications form type:
Follow these standards when you create service publications:
System support disks (SSD)
NOTE: For more information about this form type, see the appropriate form type walkthrough.
You should publish the following types of documents using the system support disk form type:
WARNING: All files in SSDs must be in either self-extracting or cabinet format. See the document Creating PFTW files for Web distribution to find out how to convert files into self-extracting (.exe) files or cabinet (.cab) files.
Follow these standards when you create system support disks:
You should mark the following types of documents as Hot news:
Generally, documents are flashed for two weeks--this time may be shortened or lengthened depending on the shelf-life of the document and its importance.
Documents should be labeled as an FAQ if they are written to resolve a problem or question that consistently needs to be answered in the HelpCenter.
If FAQ is set to YES, the document is listed as an FAQ indefinitely--to pull the document from FAQ, you must change the FAQ setting to NO.
Online Assistant standards (formerly Knowledge Base)
The following list gives the standards you should follow when you write Online Assistant documents:
For example: "What component are you having problems with?"
modem
monitor
floppy drive
CD-ROM drive
Application |
ASMA |
ATM |
Audio |
BIOS |
Cable |
CD-ROM |
CD-RW |
Diskette drive |
DVD |
DOS |
ECA |
EISA |
Error message |
Ethernet |
FDDI |
Firmware |
General |
Hard disk drive |
HelpCenter |
HomePNA |
IDE |
Infrared |
Keyboard |
LCCM |
Linux |
Memory |
Microsoft Cluster Server |
Microsoft Windows 3.1 |
Microsoft Windows 95 |
Microsoft Windows 98 |
Microsoft Windows NT |
Modem |
Netfinity Manager |
NetWare |
Networking |
Online service |
Operating system |
OS/2 |
Parallel device |
PC card |
Power |
Power management |
Printer |
RAID |
Remote control |
Serial device |
Scanner |
SCO |
SCSI |
ServeRAID |
Service processor |
SSA |
Startup |
Storage |
Subroutine |
System |
Tape drive |
TCP/IP |
TechConnect |
Telephony |
Token-Ring |
Universal Management Agent |
Update Connector |
USB device |
Video |
VINCA |
Virus |
Workpad c3 |
Workpad z50 |
Workpad |
Zip drive |
Essential grammar and usage tips
This chapter is intended to provide you with some very basic rules of grammar and usage. We have not provided a comprehensive grammar guide; we chose grammar and usage tips that we felt were absolutely essential.
You should make a distinction between grammar and usage. Grammar consists of the rules of English. Grammar rules are inviolable (i.e. don’t break them). Usage, however, consists of guidelines that, through common practice, have become acceptable in English.
A complete sentence consists of a subject and a verb. Complete sentences should end with the appropriate punctuation. Consider the following example:
Ex. "The New Document window appears."
The subject of the sentence is "the new document window," and the verb is "appears." Thus, this example is a complete sentence. Notice that, as is necessary for complete sentences, the example ends in a period.
Recognizing relative phrases and subordinated sentences
A relative phrase is a sentence fragment that begins with a relative phrase ("that," "which," or "who"). The following example illustrates a relative phrase:
Ex. "The dog that hid the bone is in trouble."
The relative phrase in the previous example is "that hid the bone."
A subordinated sentence is a complete sentence that begins with a subordinator, such as "that" or "which." Once you place a subordinator before a complete sentence, it ceases to be a complete sentence. Consider the following example:
"That the dog hid the bone is no reason to punish him."
Notice that the subject of the sentence, "that the dog hid the bone," contains a complete sentence. However, this sentence has been subordinated. It can no longer stand on its own.
Relative phrases and subordinated sentences can easily be confused with complete sentences. However, they are not complete sentences. Therefore, if you use one as, for example, a caption, you would not end it with a punctuation mark.
A run-on sentence occurs whenever you put two or more sentences together without proper sentence coordination. Consider the following example:
Ex. "You have now successfully installed the program, double-click the icon on your desktop to begin."
The previous example contains two independent clauses (clauses that could stand alone as complete sentences), but these clauses are not coordinated properly. As a result, the sentence is a run-on. (In this case, it is a common type of run-on called a comma splice.) To fix this problem, add proper coordination between the clauses or split them up and create two complete sentences. If we revised the previous example, it might look like this:
Ex. "You have now successfully installed the program; double-click the icon on your desktop to begin."
Because a semi-colon joins them, the two clauses are now properly coordinated. Thus, the resulting sentence is no longer a run-on.
A comma splice is a type of run-on sentence that occurs when you join two complete sentences with a comma. According to English grammar, you can only join two complete sentences using either "and", preceded by a comma, or a semi-colon. An example of an incorrect sentence coordination follows:
Incorrect ex. "The red light goes off, this means the hard drive is broken."
NOTE: English usage allows other sentence coordinators besides "and." Other possible coordinators include "or", "but", and "so".
To correct this mistake, replace the comma with either the word "and", preceded by a comma, or a semi-colon. The correct way to write this coordinated sentence is as follows:
Ex. "The red light goes off; this means the hard drive is broken."
Using participial phrases and avoiding dangling participles
The following is an example of a participial phrase:
Ex. "Working on the disk drive, the technician cut his finger."
NOTE: Participial phrases can occur anywhere in a sentence. If they occur at the end of a sentence, they will not be marked with a comma. Therefore, they might be easy to miss. The above example could also be written as follows:
Ex. "The technician cut his finger while working on the disk drive."
The word "working", a form of the verb "work" with an -ing ending, is the participle. Notice that the participial phrase describes something the subject of the sentence is doing while the action of the sentence occurs. Be sure the subject of the sentence matches with the action in the participial phrase. If it doesn't, you have created a dangling participle. Consider the following sentences:
Incorrect ex. "Working on the disk drive, the technician's screwdriver slipped and cut his finger."
Incorrect ex. "The technician's screwdriver slipped and cut his finger while working on the disk drive."
These sentences make it sound like the screwdriver is working on the hard drive, which is probably not what the author intended.
NOTE: Verbs ending in –ing are only one type of participle called a "present participle." Another type of participle is a "past participle." The following example illustrates a past participle:
Ex. "Released in 1998, the current driver is slightly outdated."
You must be aware of parallel structure when you create a series or a list of numbered/bulleted items. The following example illustrates an incorrect structure:
Incorrect ex. "The objective of this course is to learn, to have fun, and read."
Notice that the first two items in the series use the infinitive form of the verb (i.e. they are preceded by "to") while the last item does not. To correct this problem, you could either remove the "to" from the second item or add it to the last. Notice that, if you choose to do the former, you do not need to remove "to" from the first verb. If you remove "to" from the second verb, you can assume the series begins after the initial "to". Therefore, you do not need to delete it.
Correct ex. "The objective of this course is to learn, have fun, and read."
Correct ex. "The objective of this course is to learn, to have fun, and to read."
This rule also applies to items in a list. The following example illustrates an incorrect structure:
Incorrect ex. "Removing the computer case
1. Remove all screws from the rear panel of the case.
2. You should then lift the case off of the frame."
In the previous example, the items in the list switch from a command request (or imperative) sentence to a narrative sentence. To correct this, you must change one of the sentences so that either both are command request sentences or both are narrative sentences.
Correct ex. "Removing the computer case
1. Remove all screws from the rear panel of the case.
2. Lift the case off of the frame."
Ensuring subject-verb agreement
Make sure that, if you use a singular subject, you use a singular form of your verb. Do not be misled by long subjects that include other nouns. Make sure you understand which noun should be coupled with the verb. Consider the following example:
Incorrect ex. "The team of soccer players were practicing."
In the previous example, you might have been mislead by the noun "players." Although it is the noun that is closest to the verb, it is not the subject of the sentence. It is merely part of a prepositional phrase that modifies the real subject, "team." Therefore, since "team" is singular, the verb should be "was."
Correct ex. "The team of soccer players was practicing."
English uses three basic verb tenses: past, future, and present. When you write documents, do not switch between the three unless you have a good, contextual reason. For example, the following paragraph contains improper switches between verb tenses:
Ex. "This summary provides information about the new Microsoft Windows NT driver. It will give you instructions for installing the driver and will tell you how to configure your system. After you install the driver, your system will be updated."
Notice that the paragraph begins in present tense (the summary "provides") but switches to future tense in the next sentence (the summary "will give"). This switch is improper.
There is only one rule for using commas: a comma marks an unusual occurrence. The trick, of course, is recognizing unusual occurrences. The following list gives some common occurrences when you should and should not use a comma:
According to English grammar, a semi-colon is a sentence-coordinator. You should use it to link two complete sentences. According to English usage, these two sentences should be related. Otherwise, you could simply place a period after the first sentence and capitalize the first word of the next sentence.
NOTE: If you join two sentences with a semi-colon, do not capitalize the first word of the second sentence.
The following example illustrates the proper use of a semi-colon:
Ex. "All headings should be sentence-style; only capitalize the first word and proper nouns."
NOTE: If you use a semi-colon, do not use any other sentence coordinators, such as "and" preceded by a comma.
WARNING: Don't confuse semi-colons and colons!
Make sure the two items you are joining with a semi-colon are complete sentences. The following example illustrates an incorrect use of a semi-colon:
Ex. "All headings should be sentence-style, so only capitalize the following things; the first word and proper nouns."
In the previous example, a colon would be appropriate. You can use colons to introduce lists (although the lists usually contain more than two items).
To summarize, use semi-colons to join two complete, related sentences. If you use a semi-colon, do not use any other sentence coordinators, such as "and" preceded by a comma, and do not capitalize the first word of the second sentence.
This chapter is intended to provide you with some very basic guidelines for writing technical documents. We have not provided a comprehensive writing guide; we chose writing tips that we felt were absolutely essential.
Using active and passive verbs
When possible, you should try to use active verbs. Active verbs not only make a sentence much more readable and easy to understand, they also make sure your sentence contains an agent. You should almost always include agency because this ensures that the user always knows who should perform the action.
You can easily tell the difference between an active verb and a passive verb by figuring out whether the subject is doing something or whether it is having something done to it. For example, the following sentence contains a passive verb:
Ex. "This update will be given to you by September."
Notice that the previous example does not say who will give the update. The sentence lacks an agent. Instead, it describes an action that will be done to the update. If you rewrote the previous example in active voice (thus providing an agent), it might look like the following sentence:
Ex. "We will give you the update by September."
The second example says exactly who will give the update (in this case, whoever is writing the document).
NOTE: Although you should avoid passive voice in most circumstances, you can use it to emphasize a specific topic. Consider the following example:
Ex. "This release provides the latest drivers for your system. These drivers will be available by March."
In the previous example, the author wanted to emphasize "the drivers" in the second sentence. Therefore, "the drivers" was used as the subject instead of the object.
Another reason you may want to use passive voice is when you want to avoid using gender in a sentence. Consider the last sentence of the previous paragraph. By using passive voice, I did not need to assign a gender to the author of the example. However, in most cases, you should try to rewrite the sentence to use a plural subject; then, you can use the gender-neutral pronoun "they." (For more information on using gender-specific terms in documents, see the section Avoiding gender-specific terms.)
Nominalizations occur when you transform a verb into a noun. In fact, the word "nominalization" itself is the nominalized version of "nominalize". Although nominalizations are not grammatically incorrect, you should avoid nominalizing verbs because, when you do, it's very easy to slip into passive voice and, consequently, remove the agent from your sentence.
The following example illustrates how nominalizations can remove agency and make a sentence difficult to understand:
Ex. "Execution of the program is not possible until installation is complete."
Notice that, since the author presents the true verbs of the sentence ("execute" and "install") as nouns, the sentence requires passive voice ("execution" is an action, so it can't perform one). Therefore, the sentence has no agent to perform the actions. If you remove the nominalizations from the previous example, you can rewrite the sentence to remove the passive voice and, consequently, add an agent to the sentence. Thus, the sentence becomes much easier to understand.
Ex. "You can not execute the program until you install it."
Writing clear and concise documents
When you write documents, you should keep two important principles in mind: clarity and conciseness. These principles can be achieved in part if you follow the guidelines given in the previous two sections. However, while these guidelines will help make your information clear and concise, you must still answer the following questions:
When you consider the first question, remember that most users do not need or want to know a lot about the inner workings of their computers. They want answers to their problems. Of course, your documents will serve a wide variety of users, and there will be cases where some of them will want to know the technical details associated with their problems. In other words, consider your audience carefully when you decide how much technical detail to include in a document. Will the information help users solve the problem or prevent it from happening again in the future? If the answer is "no," it might be better to remove the information or place it near the end of the document.
Like the first question, the second question can be answered by a careful audience analysis. A good way to figure out what information should come first is to put yourself in your users' minds. What question are they most likely asking themselves when they read your document? Try to answer that question immediately. Any additional information should come later. However, remember that, if your additional information becomes too long, chances are most users will not read it all; consider breaking it up into separate documents.
Writing for international audiences
NOTE: This chapter is taken directly from the IBM Style Guide. It contains guidelines that you should follow to make it easy to translate our documents into other languages. These guidelines will also make it easy for people who speak English as a second language to understand our documents.
The term international audience includes the following people:
Follow these suggestions to ensure that your information is clear for all types of audiences.