IBM DeveloperWorks Editorial Style Guide For Technical Writing

IBM developerWorks editorial style guide
Published on May 31, 2014
Since the launch of developerWorks in 1999, the site has focused on a single mission: to help enterprise
developers and IT professionals do their jobs effectively. developerWorks relies on a modern and
engaging editorial style that is consistently applied across all its content. As a developerWorks editor,
you can achieve that style by following the standards and guidelines outlined here.
After an overview of developerWorks editorial style, sections are arranged alphabetically. Each topic
addresses the most common situations and gives examples where appropriate. With some exceptions,
developerWorks style is based on the IBM style, which is defined in The IBM Style Guide: Conventions for
Writers and Editors. Sidebars indicate the relevant sections in the IBM Style Guide. Refer to the IBM
guide for more examples and for cases not documented in this developerWorks guide.
Most of the conventions and style guidelines outlined here are standard practices and have been in
place since the inception of the developerWorks website. However, like any effective editorial style,
developerWorks style evolves to adapt to shifts in how readers consume content. Consider the following
ideas for modernizing article style as you apply the standards and guidelines.
A modern editorial style

Authors of developerWorks articles should sound as though they are speaking to a
respected professional acquaintance, using clear language and short declarative
sentences. Text should educate or persuade readers, not dazzle them with verbal
acrobatics. A casual and conversational tone is acceptable and appropriate; overly
informal language, slang, jargon, and disparaging or heavily opinionated comments are
not.
developerWorks articles:
• Use second person ("you") when speaking to or about the reader. Authors can refer to
themselves in the first person ("I" in single-author articles or "we" in multiple-author
articles) but should keep the focus on the reader.
• Focus on facts, real user tasks, and real user benefits. Avoid promotional hype at all
costs.
• Prefer shorter words over longer alternatives. Examples: "helps" rather than
"facilitates" and "uses" rather than "utilizes."
• Use active voice where possible. Passive voice is acceptable when any of these
conditions is true:
o The system performs the action.
o It is more appropriate to focus on the receiver of the action.
o You want to avoid blaming the user for an error, such as in an error message.
o The information is clearer in passive voice.
• Start a sentence that contains a conditional phrase with the conditional phrase so that
the reader can skip the rest of the sentence with confidence if the condition doesn't
apply.
Rich article guidelines

When editing an article that uses the rich template, apply the following additional
guidelines. Example of a rich article: "Build a sentiment analysis application with
Node.js, Express, sentiment, and ntwitter."
• Include the template-provided call-to-action links and populate the <related-topics-
block> element, instead of in-text links, to refer readers to related resources.
• See Linking in rich articles.
• Introduce the topic with a personal story. Example: "I did this, ran into this issue, and solved it
this way...." After the introduction, shift the focus back to the reader by using "you."
• Use tooltips. A tooltip is explanatory text, such as a definition, that pops up when a reader's
mouse pointer hovers over a highlighted term.
• Aim for economy. Tell just enough and link elsewhere for more details.
• Use shorter sentences and shorter paragraphs to help with mobile display.
• Split long articles into a series, published simultaneously, so that each article is shorter.
• Omit captions for figures, tables, and listings when possible (see Captions for figures, tables, and
code listings).
• Aim for economical expression. Omit weak modifiers such as "quite," "very," and "extremely."
Avoid weak verbs such as "is," "are," "has," "have," "do," "does," "provide," and "support."
(Weak modifiers have a diluting effect, and weak verbs require more wordy constructions.) A
particularly weak verb construction to avoid is starting a sentence with "There is ..." or "There
are...")
• Write conversationally:
• Prepositions are okay to end sentences with.
• And another thing. You can start sentences with "And" or "But."
• Avoid lengthy abstracts. (See Abstract for details.)
• Include pullquotes (author declarations).
• Link inline to both internal (developerWorks) and external (non-developerWorks) content.
Maximize in-context links, and minimize Resources. (See Resources for details.)
Abbreviations, acronyms, and initialisms

Do not abbreviate product or brand names unless the abbreviations are approved by
brand name and legal representatives.
Define technical terms and avoid jargon. Define acronyms and abbreviations on first
occurrence if they're likely to be unfamiliar to the intended audience (for example,
"message-driven beans (MDBs)").
Do not use periods in all-uppercase abbreviations, such as SWAT or IBM.
Use s (not 's) to create the plural form of an all-uppercase abbreviation. Example: "The
ship sent out several SOSs."
Abbreviations for units of time and measurement
Table 1 shows the abbreviations that developerWorks uses for certain units of time and
measurement when they are preceded by a numeral. Use no space between the
numeral and the abbreviation, and use the same abbreviation for both singular and
plural unless Table 1 indicates otherwise. Use the same form for both nouns and
adjectives: "The directory contains 5GB of data; the PC has a 16GB disk."
Table 1. Abbreviations for units of time and measurement
Unit of time or
measurement Abbreviation Notes
ampere A
bit b
bits per second bps
British thermal
unit Btu Plural: Btus
byte B
centimeter cm
decibel dB
The code for the degree symbol

is °. Indicate Fahrenheit
degree ° or Celsius: 32°F, 10°C
Abbreviate in tables and

graphics only. Spell out when
foot, feet ft used in a sentence.
gram g
Unit of time or
gigabit Gb
gigabits per
second Gbps
gigabyte GB
gigabytes per
second GBps
gigahertz GHz
hertz Hz
Abbreviate only in tables and

graphics, and use the ending
period. Spell out when used in
inch, inches in. a sentence.
Binary thousand — 1024; used

kilo K for memory
Metric thousand — 1000; used

k for transmission speeds
kilobit Kb
kilobits per
second kbps
kilobyte KB
Unit of time or
kilobytes per
second kBps
kilogram kg
kilohertz kHz
kilometer km
kilowatt kW
Binary million (1,048,576); used

mega M for memory megabit Mb
megabits per
second Mbps
megabyte MB
megabytes per
second MBps
megahertz MHz
meter m
milligram mg
millimeter mm
Unit of time or
millions of
instructions per
second mips
millions of
packets per
second mpps
millisecond ms
milliwatt mW
nano n
nanometer nm
nanosecond ns
ohm ohm Do not abbreviate. Plural: ohms
packets per
second pps
Spell out percent when used in

a sentence. Use the % symbol
percent % only in tables and graphics.
pound lb
rack unit RU
Unit of time or
rotations per
minute rpm
terabit Tb
terabits per
second Tbps
terabyte TB
terabytes per
second TBps
volt V
watt W
Abbreviations for longer units of time

In sentences, do not abbreviate these units of time: seconds, minutes, hours, days,
months, and years. Abbreviate them only when space is limited, as in tables or
graphics. When you must abbreviate them, use the following abbreviations for both the
singular and plural forms, and include the period: sec., min., hr., d., mo., and yr.
Accessibility
By law in the U.S. and other countries, content must be accessible to people who have
disabilities, such as visual impairments. Remember this: Anything that the reader must
know or do needs to be in text, too, not just in images.
• Include figure tags (<figure>) and alternative text tags (<alt> tags) for all illustrations. Limit
the alt text to 50 characters.
• Introduce illustrations or code listings with a clear lead-in sentence. Detailed instructions and
explanations can come after the image or code example.
• Convey code to all readers. Articles should not use screen captures or other graphics as the sole
way of showing code, commands, or screen output that readers must do something with or
know about. Ensure instead that all code is in either listings or text (in code font) so that it is
readable by software for the vision-impaired.
• Use simple tables. Avoid rowspan or colspan (span tags) if possible.
• Spell out months, as in 21 April 2014, rather than 20 Apr 2014.
• Don't depend on color to convey information. For example, don't refer to the red text in a
figure.
"Web content accessibility for authors" explains how to write and format articles and web pages to
ensure that they comply with federal laws and corporate policies and reach more readers.
Capitalization
Capitalize all proper names. When referring to GUI elements, match the capitalization used in the
interface.
Use sentence-style capitalization for headings and captions; that is, capitalize only the first letter of the
first word and any proper nouns or acronyms.
In text, capitalize the first word after a colon only if it starts a complete sentence. But always capitalize
the first word after a colon in headings and captions. Example: "Lambda expressions: Higher-order
functions at last"
Otherwise, follow this commonsense rule: If in doubt, do not capitalize.
Captions for figures, tables, and code listings

Numbers and captions make it easy for the author to refer clearly to individual figures,
tables, and code listings in the article.
• Use sentence-style capitalization for captions.
• Include captions for all tables, figures, and code listings of five or more lines.
• For rich articles, omit captions unless needed for cross-references.
• If any figure (or table or listing) in an article is cross-referenced, all figures (or tables or listings)
in the article must have numbers/captions.
• When a number/caption can be omitted, ensure that the figure, table, or listing is preceded by a
meaningful lead-in sentence or two.
GUI elements: Terminology and usage

Use these terms for the generic parts of a GUI:
screen
Use to refer to the physical surface of a display device, not to the information that
is displayed.
window
Use to refer to an area of the screen with visible boundaries in which the
operating system or a non-browser-based application program displays
information to or gathers information from the user.
dialog box
A dialog box is a secondary window that gathers additional information from the
user. Use the term only when it is important to distinguish parts of the interface.
Do not use "dialog" to mean "dialog box."
pane
Use to refer to a separate area within a single, split window.
page
Use to refer to:
• A web-based UI that is displayed in a browser
• The area that each sequential step in a wizard uses to display or gather
information
• The area that is displayed when the user clicks a tab in a tabbed (notebook-style)
interface
panel
Do not use to refer to any area of a GUI. (Use it only to refer to the display area
of nongraphical UIs.)
wizard
A wizard is an interactive program that guides users through a series of steps to
achieve a specific goal. Each step in a wizard is displayed in a page.
tab
A tab is a UI element (in a website or an application) that resembles a physical
notebook or file-folder tab. Tabs are used to organize distinct sets of information
and enable easy navigation among them. Users click a tab to display a page.
menu
Use to refer to all types of menus unless it's important to specify how ("pop-up
menu" or "pull-down menu") the menu operates. Do not use "context menu" or
"shortcut menu." Do not use "pop-up" or "pull-down" as nouns. Use > to signify a
string of menu choices, such as File > Edit.
In text that describes actions relating to a GUI, follow these guidelines:
• Windows, dialog boxes, and wizards open; they do not "appear," "display," or "pop up."
(But when you're describing a series of steps in a GUI, it's often unnecessary to state
the obvious — that the window, dialog box, or wizard opens.)
• Messages are displayed; they don't "appear."
• You close a dialog box or window; you don't "dismiss" it.
• Use enabled in reference to UIs only to describe an interface control has been made
available. An interface control that is displayed and enabled is available (not "active").
An interface that is displayed but not available is disabled (not "inactive," "dimmed,"
"grayed," or "grayed out"). A control that is not displayed is unavailable (not "inactive").
• You move a slider or cursor.
Highlighting and formatting

Not sure how to highlight code strings? Do you italicize an article or book title? When should you use no
highlighting at all? Table 2 shows the highlighting conventions for developerWorks content.
Some general rules apply:
• Use bold ():

• To emphasize text that is particularly important, bearing in mind that overusing bold reduces its
impact and readability.
• For any GUI element that the reader must select or click to follow the article's instructions.
• Use italic ():
• When introducing a word that you will also define or are using in a special way. (Use rarely, and
do not use for slang.)
• For titles of books, journals, or other publications.
• Use inline code font (<code>):
• For anything that the reader must type or enter.
• For names of methods, classes, keywords, variables, interfaces, attributes, and other code and
command elements.
• Use quotation marks for links (or unlinked references) to:
• Titles of developerWorks articles
• Titles of non-developerWorks articles or papers
• Headings cited. Examples: "Getting started" or the "Download" section. (See the recommended
highlighting table for specifics.) Example: See the section "Introduction in Software Cost
Estimation with COCOMO II."
• No quotation marks are needed for links (or unlinked references) to:
• developerWorks zones or landing pages. Example: "Check the Rational software section of IBM
developerWorks for more information."
• Non-developerWorks websites
Table 2. Recommended highlighting
Highlighted Recommended
element highlighting Example of XML coding
API name No highlighting search API
"Introduction to Android
"Article title" Quotes development"
Attribute ALT attribute on

name Inline code the figure tag
AI Application
Book title Emphasis Programming
Button (or
key) name,
hardware No highlighting Press Enter
Button
name,
software Bold Click Next
Select the Set as

Checkbox Bold default checkbox
<code>Command</code>
Class Inline code class
<code-listing>
<pre>
struct my_data_structure {
int value;
struct list_head list;
1 Code listing };
Code 2 Code listing </pre>
listing 3 Code listing </code-listing>
Code string
in a <code>my_hrtimer_callback<
sentence Inline code /code>
The Java theory and

Column or practice series on
series name Emphasis developerWorks
Command <code>Print</code>
name Inline code command
Containers No highlighting Java container

Currency Use international format. USD100 or US$100
Dates Use international format. 21 April 2014 or April 2014
Open the
Browse
Dialog name Bold dialog to select a file
Go to
Directory /developerworks/downloads/i
name No highlighting ndex.html.
Strong emphasis. For

example: "The maximum The maximum code line
code line length is 105 length is 105
Emphasis characters." characters.
Add the new directory to the

Environment <code>CLASSPATH</code>
variables Inline code environment variable
Field name Bold User ID
File name No highlighting sample.zip
GUI
elements
(tabs, menu
choices, Strong emphasis. For Click
menu example: Options >
names, "ClickOptions > Preferenc Preferences.
HTML
element Inline code <code>title</code> element
<Inline code and anchor Surround your paragraphs

HTML tags brackets> with the <code>p</code> tag.
Click the
Icon name Bold Back icon.
"Irony" Quotes There is no "right" solution.
Do not change the

<code>HKEY_CURRENT_USER</c
Key name Inline code ode> registry key
<code>cloud</code>
Keyword Inline code keyword
Note: Skip
Labels (Tip, this step if the software is
Note) Bold already installed.
Letters, if Type R to

only one Bold re-run the command.
Select File
List boxes Bold from the drop-down box.
<code>LIST_HEAD</code>
Macro Inline code macro
Magazine
title Emphasis Linux Magazine
Message
text or <code>The queue was
prompt Inline code created successfully</code>
addressed
to the user
<code>execute()</code>
Method Inline code method
One through nine: Spell out.

10 and greater: Use
Numbers No highlighting numerals.
<code>Zend_Service_Amazo
Object Inline code n_Sqs</code> object
The default parameter for

User ID is
websphere
Parameters Inline code .
Path name
or directory No highlighting C:\jdk1.6.0_18
No highlighting. In some common systems

Pattern contexts, patterns are architecture pattern for public
name capitalized. sector organizations
Storage save the file in the file

areas No highlighting storage area
Table title or
name,
reference in Check the database names
text No highlighting table for the value
Tags in
markup <Inline code with anchor Use the <code>figure</code>
languages brackets> tag to set off images.
After you finish the

Tasks No highlighting configuration task
Terms
defined in
context Emphasis timer wheel
Type (such
as int or
long) Inline code <code>int</code> type
www.ibm.com/developerwork
URL in text No highlighting s/
Use the list utility to create a

Utilities No highlighting set of items.
Values for
arguments Type <code>none</code> to
or commands Inline code specify no backup.
Placeholders
within
commands
and code Emphasis your-file
View name No highlighting Check the Log view.
Website
name No highlighting The developerWorks website
Window or The Installation options

panel name No highlighting window
<XML tags
or <Inline code with anchor <code>heading</code>
portions> brackets> element
Hyphenation
Prefixes and suffixes
Do not hyphenate prefixes and suffixes, with the following exceptions:
• When adding "-like" to a word that ends in l.
• When adding a modifer prefix to a proper name, or to an abbreviation, acronym,
or initialism. Examples: "non-IBM," "non-developerWorks," "anti-British," "pre-NATO."
Exception: "Antichrist."
• When a prefix creates a double-vowel. Example: "anti-establishment." Exception:
"pre" and "re."
• When the hyphen eliminates ambiguity about the word's meaning. Example: "re-
create."
Compound modifiers
Use hyphens in compound modifiers when they are needed for sense, as in: "rich-
article author." Watch for triple compounds and hyphenate according to what's being
modified, as in "rich article-based submission" and "second-rate opera company."
Exceptions:
• Do not hyphenate when one of the words is an adverb that ends in -ly. Example:
"easily duplicated error."
• Do not hyphenate when the compound modifer is part of a commonly used, well-
understood English phrase or tech industry term. Example: "home equity loan" or
"cloud computing software." (But use your judgment and hyphenate if necessary to
avoid ambiguity.)
Lists
Use a list when you have three or more important points to reinforce or amplify. Use a list rather than a
two-column table because it reduces the likelihood of accessibility errors. Use ordered lists for task
steps, rather than burying them in hard-to-follow paragraphs of text.
Follow these guidelines for both ordered and unordered lists:
• You can nest lists, but do not go more than three levels deep, and try to keep it to two.
• Always introduce a list with a sentence or two.
• Never create a list with only one item and use two-item lists sparingly, if at all.
• Use ordered lists when the sequence of items is important. Otherwise, use unordered (bulleted)
lists.
• Use sentence case (initial capital letter only) for list items, other than for proper names.
Example:
• Use-case model
• Design model
• Implementation model
• Use parallel construction for items and active voice. Example:
• Start each item with a verb.
• Keep each item in active voice.
• Be consistent with end punctuation. If one item is a complete sentence or more than one
sentence, use end punctuation for all items.
Product names
Explicitly identify all IBM products that the article applies to, including full product name, edition, and
version.
• Do not abbreviate any IBM product name. If an abbreviation is legally registered as a

trademarked short name or acronym, use the full name along with IBM and the brand name
(Rational, InfoSphere, and so on) on the first occurrence. Examples to avoid:
o WSAD
o WPS
• Approved exceptions: WAS and RAD (for search optimization.)
• Use only approved short names. If a product name has an approved short name, it can be used
after the first occurrence, such as "WebSphere Studio Application Developer (hereafter called
Application Developer)".
• Use the trademark symbol and full name on first occurrence. Examples:
• First use: IBM® Rational Unified Process® (RUP®)
o Thereafter: RUP
• First use: IBM® Rational® Method Composer
o Thereafter: Rational Method Composer
o Do not use: RMC
• Use the brand name on all occurrences of product names. Even on subsequent use, include the
brand (Rational, InfoSphere, and so on.) On feature and tool names, the brand name can be
omitted. Product names are adjectives, legally, so they must always be followed by nouns.
Example: (after first use) "Rational Application Developer platform...."
Bluemix
When referring to a Bluemix service, use "IBM service name for Bluemix" the first time, then use the
service name. Do not use Bluemix service name unless you are referring to a group, for example,
Bluemix Mobile services.
Examples
First time: IBM Mobile Analytics for Bluemix

Then: Mobile Analytics
First time: IBM Cloudant NoSQL Database for Bluemix

Then: Cloudant NoSQL DB
See the Bluemix catalog for service names.
Punctuation
Check this list for the most common punctuation quandaries, such as whether to end this lead-in
sentence with a period or a colon:
• Lead-in punctuation for figures, lists, code-listings, and so on: If the lead-in is fairly short, use a
colon (preferred, but not mandatory.) Be consistent throughout the article.
• Exclamation marks: Use them sparingly, unless you want your text to appear breathless and
trite! (See?)
• Do not use slashes as substitutes for words (and, or): Slashes are ambiguous and problematic
for translation. Instead, use the construction x or y or both. Example: "use-case scenarios or
state machines or both".
• Comma in a series: In a series of items connected by "and" or "or," retain the comma before the
"and" and "or."
• Comma between an independent and a dependent clause: Do not use a comma between an
independent clause and a dependent clause that are separated by a coordinating conjunction
unless the sentence might be misread without a comma. Example: "All of the JVM languages
include currying but implement it in different ways." (Use no comma before "but.")
• Ellipses: Avoid the ellipsis (...) except to indicate omitted words.
• Long dashes: Use the mdash (<mdash/>) to signal a brief and relevant detour in thought. Keep
spaces on both sides of the dash.
• Hyphens: See Hyphenation.
• Periods: Omit periods in all-uppercase abbreviations.
Structure
developerWorks articles communicate economically and clearly:
• Arrange sentences in a paragraph to flow in an intuitive order. Move from the known to the
unknown, the old to the new, or the familiar to the unexpected.
• Limit each paragraph to a single idea. Ideally, express that idea in the first sentence.
• Keep sentences short, 25 words or fewer. Emphasize important points with the occasional short
sentence (fewer than 10 words).
• Use subject-verb-object sequence (active voice). Place the subject and verb as close together as
possible for rapid comprehension.
• Include the implied "that" in relative clauses. Example: "Repeat the value that you entered in
the text field." Possible exceptions include headings, short sentences, and rich articles in which
the author is speaking casually.
• Use gerunds and participles except when clarity is compromised. Examples of acceptable
usage:
o "Writing code is fun."
o "I shortened the code to five lines, reducing it by half."
o "I shortened the code by using a different algorithm."
o Example of usage to avoid: "I shortened the code using a different algorithm."
o For classic articles, include the following elements. For rich articles,
some exceptions apply.
Author biography
The author biography is brief, written in third person, and includes:
• A clear, digital head shot, 60x60 pixels
• Job title
• Related experience and education
• Author credentials (what makes the author an expert on the topic?)
Titles, series titles, and subtitles

• Title: Use a short, keyword-rich title that captures the intent of the article and draws the
reader in. Ensure that the title clearly and concisely conveys the content or subject
matter and is meaningful to a global audience.
• Series title: In a collection of articles on the same topic, use the same series title for
each article in the collection:
o Include the part number in the series title. Example: "An introduction to Apache
ZooKeeper, Part 1."
o Point to all other parts in the series from each article in the series. Example: Part 1
points to Parts 2 and 3. Part 2 points to Parts 1 and 3. Part 3 points to Parts 1 and 2.
o Italicize series titles in references that include the rest of the title, and in references that
don't. Examples:
▪ "Michael's Java.next series reveals...."
▪ "Read more about Clojure approaches to concurrency and understand when each is
appropriate in the article "Java.next: Clojure and concurrency" (Michael Galpin,
developerWorks, September 2010)."
• Subtitles: Use subtitles in classic articles.
Abstract
For the abstract, use a short, enticing, keyword-rich description of the article.
• Keep the length to three to five sentences.
• Lure in the reader by describing the problem or challenge that the article helps solve.
• Specify the task (what the reader can do with the content) and its relevance (why the
reader should care).
• Mention any specific products and versions (or operating systems) that are central to
the article.
• Keep the text succinct. Put key points and search phrases near the beginning of the
abstract, because it might be truncated in search results.
• Address the reader directly as "you" (implied "you" is fine).
• Write in the present tense. Example: Use "shows," not "will show."
• Refer to the author, if necessary, by first and last name (as though developerWorks is
writing the abstract, not the author).
• Code HTML tagging and special characters, such as trademark and registered
trademark symbols, in the abstract-extended. (Copy the abstract element and add the
anchor tags, highlighting, trademark symbols, and so on.)
• Expand technical terms or jargon. Remember that your article might run on additional
zones whose readers are less familiar with those terms.
• Amplify, but don't repeat, the abstract in the opening paragraph (and link to any
previous articles in series).
Introductory section
Start with an introduction or overview, which lays down the foundation of the article and
outlines the scope. In rich and classic articles, the opening paragraphs need no
heading. By virtue of position, they are the introduction.
Headings
Include frequent headings to avoid long, dry deserts of unscannable text.
• Aim for about three headings per full web page (about 600 words/web page).
• Make headings specific, concise, and meaningful.
• Summarize the underlying content and help tell the overall story of the piece in an
interesting, provocative way.
• Use parallel syntax in headings for parallel sections.
• Avoid empty headings devoid of technical content such as "Going further," "Next steps,"
"Considerations," and so on.
• Each major section should be assigned a heading-level 2. Subsections get a heading-
level 3.
• Use no more than three levels of headings (H2, H3, and H4).
• Don't use academic-style numbering (1.1, 1.1.1, 1.1.1.1, and so on).
• Use sentence-style capitalization for all headings and subheadings and no end
punctuation. Example: Structure of a typical developerWorks article
• Use unique text for all section headings and all subheadings.
• Ensure that transitional text precedes each heading to create a logical segue from one
section to the next.
• Never put a subheading immediately after a heading with no text in between.
• Avoid using only one subheading under a heading.
Conclusion
Use a heading such as "Summary," or "Conclusion." In two to four sentences, wrap up
the article:
• Restate the original value statement introduced in the abstract.
• Describe how the reader has attained the objectives and how the reader can now apply
the information.
• Mention logical next steps. Depending on the nature of the article content, include
caveats, related topics to explore, future anticipated developments, or suggestions for
further experimentation.
Downloads (other than product trials)

Classic articles can optionally have associated downloads such as sample code or
related PDFs (other than the PDF of the article itself). Use the <target-content-
file> tag to include them as target content files. The tag creates a Download section
that appears immediately above the Resources section. See the instructions in the
article template for details.
Resources
Linking in rich articles
Is the link a key call-to-action for the article (get the code, run the app, download
a trial, or other mandatory action)? If so:
• Use the <button-link>element to place one or two call-to-action buttons near the top
of the article.
• Place two buttons side-by-side by using the<button-block-two-column> element.
• Keep the link text brief on each button (three or four words, maximum).
Is the link essential to completing the task the reader is reading about, such as
prerequisite knowledge or software? If so, link directly in the sentence where the item is
first mentioned.
Is the link highly relevant but optional for task completion (and not mentioned in a
sentence where you can link to it)? If so, make the link a READ or WATCH item at the
end of the section by using the <call-to-action-block> element. Use READ and
WATCH items sparingly, no more than six.
Do rich articles end with links to related topics? Yes. In the<related-topics-
block>element, include up to three related topics. Link to related developerWorks
articles or to a relevant topical aggregation page, such as the Android topic for an article
on Android apps.
Classic articles include a Resources section. (Rich articles do not; see the Linking in
rich articles sidebar for guidelines on linking to resources from rich articles.)
Until late 2013, developerWorks confined external (non-developerWorks) hyperlinks to
the Resources and encouraged comprehesive, wide-ranging Resources lists. That
policy is obsolete. To optimize discovery and usability — and guide readers to rapid
task completion — put essential assets in easy reach by linking to them in the
sentences in which they're mentioned. At the same time, try not to overwhelm readers
with too many link distractions. Use in-context links for:
• Information that's crucial to readers' ability to complete the task that they are reading
about — such as prerequisite knowledge or a URL where the reader must perform an
action.
• Software that the reader must download and install to complete the article task. (These
software-download links must also appear in the Resources, as detailed below.)
• Any developerWorks content or ibm.com pages that the article text mentions directly.
Classic articles can also optionally use same button links that rich articles are
required to use for key calls-to-action. See the Linking in rich articles sidebar for
details.
Use the Resources for other relevant links — 7 to 10 at most. Organize them under the
following headings:
• Learn: Include informational content, such as:
o Other developerWorks articles in the same series, on the same topic, or by the current
article's author.
o Documentation related to the article content.
o A related topical aggregation page or a custom library view on developerWorks.
o Content that is somewhat related to the article but largely tangential, so that readers can
explore it later.
Do not introduce additional topics that are not included in the article and do not include
generic links, such as links to the developerWorks topic area ("zone") where the article
is to be published.
• Get products and technologies: Include links to downloadable sample code, libraries,
or products. Repeat the essential in-context links to software downloads here.
• Discuss: Link to forums, online communities, and Twitter chats where discussion on
the article topic occurs. Use caution when linking to social media conversations, which
tend to have minimal enduring value.
Formatting link text
In both classic and rich articles, follow the developerWorks highlighting conventions for
in-context links to developerWorks content or external content. For example, if the link
text is an article title, put quotation marks around the title (without including the
quotation marks in the link); if the link text is a book title, italicize the title.
Put a link to another section of the same article in quotation marks; use the section
heading as the link text. (Do not include the quotation marks in the link.) Exception: Put
no quotation marks around "Resources" or "Downloads" when you are directing readers
to those sections of a classic article.
In each Resources entry, follow the link with a colon and a complete sentence
that describes the resource and conveys its value. ("Learn more about...,"
"Download...," "Read how to....") For formal "Learn" items such as articles and books,
precede the colon with the source and publication (or revision) date in parentheses;
author names are optional. Examples:
• "Build a reactive sales chart app with Meteor" (developerWorks, May 2014): Create your
own Meteor real-time sales chart application on DevOps Services and deploy it to
BlueMix for global web access.
• "Add Push notifications to Android apps" (developerWorks, updated April 2014): Learn
how to add the Push and Node.js Cloud services to the BlueList app so that notifications
are sent when a list is updated.
• "Clojure and concurrency" (Michael Galpin, developerWorks, September 2010): Read
more about Clojure approaches to concurrency and understand when each is
appropriate.
If the current article's author is mentioned in a Resources item, use third person for his
or her name. For example:
Functional Thinking (Neal Ford, O'Reilly Media, 2014): Learn more about functional
programming in this book by the series author.
Trademarks
developerWorks content uses the appropriate symbol to mark the first occurrence of
trademarked terms belonging to IBM.
• Check the IBM copyright and trademark information list for product names that should
be trademarked.
• Mark only the first occurrence in the abstract or in the body of the article, whichever
comes first.
• Do not use trademark symbols in headings.
• Do not mark non-IBM trademarks, except for "Java." Use "Java" as an adjective.
Example: Java™ technology
• Do not use trademarked terms as possessives. Example to avoid: IBM's WebSphere.
Word usage
This section provides guidance on spelling, capitalization, and usage for many terms
that can occur in developerWorks content:
indicates that the term is correct as shown in terms of spelling, casing, or
punctuation. Within some of these entries, the symbol precedes a qualifier or warning.
indicates that the term should not be used.
indicates a term that might be correct in certain contexts but is incorrect, or should be
used with caution, in the specified context.
Tip: To find guidance for a specific term, search for the term rather than scan the list.
Even if the term doesn't have a main entry, useful information about it might be
elsewhere in the list.
3D [n., adj.]
10BASE-T [n., adj.]
Use a hyphen when a letter follows "BASE"; do not use a hyphen when a number
follows it (for example, "10BASE2").
A
a Hadoop [n.]
Do not use "an Hadoop."
Correct: " a Hadoop cluster."
a lot of, a lot [n.]
Replace with "many" or "much."
a number of [n.]
Replace with "several."
a.m. [adj.]
abend [n., adj.]
Do not use as a verb.
abort [v.]
Replace with "cancel" or "stop."
about [adv.]
Do not use to mean "approximately."
above [adj.]
Do not use to indicate a relative location in a document. Use "previous" or "preceding."
Correct: "the above restrictions apply to...."
Correct: "The previous restrictions apply to..."
Incorrect: "The above restrictions apply to..."
access-control list (ACL) [n.]
across [prep.]
Do not use to mean "to" or "for."
Correct: "applications for multiple platforms"
Incorrect: "applications across multiple platforms"
actionable [adj.]
Do not use to mean that action can be taken. Use only in the legal context of providing
grounds for a lawsuit.
Incorrect: "Transform data into actionable business information."
ad hoc [adj.]
adapter [n.]
Use "adapter" — not "adaptor," "card," or "adapter card" — to refer to hardware that
enables a computer to use a peripheral device for which it lacks the necessary
connections, ports, or circuit boards.
add-on [n., adj.]
administrate [v.]
Replace with "administer."
afterward [adv.]
Not "afterwards"
agile [adj.]
Use only as an adjective followed by a noun. Do not use as a noun.
Correct: "The agile team advocates multiple biweekly iterations."
Incorrect: "Agile advocates multiple biweekly iterations."
Incorrect: "The Agile team advocates multiple biweekly iterations."
Ajax [n., adj.]
Ajax stands for Asynchronous JavaScript + XML, according to Jesse James Garrett,
whose essay coined the term in February 2005.
all caps [n.]
Replace with "uppercase."
allow [v.]
Avoid stating that inanimate objects grant abilities to people, as in "the product allows
you to..." Whenever possible, use a direct, user-focused alternative such as "you can
use the product to..." or "with this product, users can..."
See may, might, can and enable.
alpha [adj.]
Do not use to mean "alphabetic."
alphabetic [adj.]
Use "alphabetic" to mean of, relating to, or employing an alphabet. Do not use to mean
arranged in the order of the letters of the alphabet.
Correct: "You must specify alphabetic characters."
alphabetical [adj.]
Use "alphabetical" to mean arranged in the order of the letters of the alphabet. Do not
use to mean of, relating to, or employing an alphabet.
Correct: "The names are displayed in alphabetical order."
alphanumeric [adj.]
Not "alphameric" or "alphanumerical"
Correct: "The password must contain at least five alphanumeric characters."
alternate [adj.]
Use "alternate" (or one of its forms, such as "alternating") to mean "every other."
Correct: "Add data points to warehouse data on alternate days."
alternative [adj.]
Use "alternative" to indicate a choice.
Correct: "If the main system console becomes unavailable, you can designate an
alternative system console."
analog [adj.]
Not "analogue"
and so on [n.]
Use only when you list a clear sequence of elements, such as "1, 2, 3, and so on" or
"Monday, Tuesday, Wednesday, and so on." When you list items that do not form a
clear sequence, use appropriate descriptive wording, such as "device drivers, firmware,
and other code."
and/or [conj.]
Do not use. Depending on the context, use a construction such as "a or b" or "a, b, or
both."
ANSI [n.]
Abbreviation for "American National Standards Institute." Use to refer to the institute
itself or as part of the identification number of a standard, such as "ANSI X3.23-1974."
any more [adj., n.]
Two words, meaning "any additional," when used as a noun or adjective.
Correct: "If you have any more existing snapshots ... "
anymore [adv.]
One word, meaning "any longer," when used as an adverb.
Correct: "The user does not have permission to create the alarm anymore."
any time [n.]
Two words when used as a noun.
Correct: "The message might arrive at any time."
anytime [adv.]
One word when used as an adverb.
Correct: "You can do this task anytime you want."
API [n.]
Abbreviation for "application programming interface"; no need to spell out.
appendixes [n.]
Not "appendices"
architect [n.]
Use only as a noun. When you need a verb, use "design," "plan," or "structure."
architected [adj.]
Do not use unless you have no better alternative. Consider using a simpler word, such
as "designed."
as [adv.]
Do not use to mean "because."
Correct: "Because you created the file, you can delete it."
Incorrect: "As you created the file, you can delete it."
as long as [conj.]
Do not use to mean "on condition that." Use "if" or "provided that."
Correct: "Do not stop the process if the map is active."
Incorrect: "Do not stop the process as long as the map is active."
Correct: "You can leave the field blank, provided that there are no other users."
Incorrect: "You can leave the field blank as long as there are no other users."
as per [prep.]
Do not use. Use a phrase such as "according to," "as," or "as in."
as well as [conj.]
Do not use to mean "and."
assembler [n.]
Do not use to refer to the language used for an assembler. Use either "assembly
language" or "assembler language," depending on the terminology used in your product.
Use "assembler" only to refer to a computer program that converts assembly language
instructions into object code.
assembly language [n.]
In most cases use "assembly language," rather than "assembler language," to refer to
low-level programming languages used by assemblers.
Use "assembler language" only to refer to the language used by products that include
the term "Assembler" in their name (for example, "High Level Assembler for z/OS).
attach [v.]
Do not use as an intransitive verb unless the subject performs the action without human
intervention. Instead, use "attach" as a transitive verb.
Correct: "The cable is attached to the monitor."
Incorrect: "The cable attaches to the monitor."
attention notice [n.]
Not "warning notice"
auxiliary storage [n.]
Not "offine storage" or "secondary storage"
B
back end [n.], back-end [adj.]
If possible, use a more specific term, such as "server," "operating system," or
"network." If "backend" is part of the established product terminology, for example in
some compilers or in the Python programming language, write as one word with no
hyphen.
backup [n., adj.], back up [v.]
back-level, backlevel
Replace with "earlier," "previous," or "not at the latest level."
backslash [n.]
Refers to the \ character.
backward compatible, backward-compatible [adj.]
Replace with "compatible with earlier versions."
bean [n.]
The word "bean," apart from its use in the term "JavaBeans," is a generic term and
should be lowercase.
because of [prep.]
Use "because of," not "due to," in adverbial clauses. Although the use of "due to" as a
synonym of "because of" has some acceptance in modern English usage, it is imprecise
and, therefore, not suited to technical writing.
Correct: "Because of the power failure, the update stopped."
Incorrect: "Due to the power failure, the update stopped."
below [adj.]
Do not use to indicate a relative location in a document.
Correct: "The information later in this section ..."
Correct: "The following table shows ..."
Incorrect: "The information below ..."
benchmark [n., v.]
best-of-breed [adj.]
Use only to describe a product that is demonstrated to be the best of its type, based on
concrete evidence. (Unsubstantiated claims can cause legal problems.)
best practice [n.]
Use to describe a process or method that is demonstrated to be the most effective
process or method for achieving a particular outcome, based on concrete
evidence. Do not use "best practice" as a generic term to describe a suggested
course of action.
beta [adj.]
Lowercase. Avoid using "beta" as a noun when a noun phrase is more accurate.
Correct: "beta program" or "beta code"
between [prep.]
Do not use to show a range of numbers; it is not clear whether the two numbers are the
boundaries of the range or are included in the range. See "Ranges of numbers" (p. 159)
in the IBM Style Guide for a more detailed explanation.
Big Blue [n.]
Avoid; use "IBM" instead.
big data [n.], big-data [adj.]
billion [n.]
Do not use. Use the number rather than the word because it has different meanings in
different countries. To US readers, one billion means 1,000,000,000 (one thousand
million), and in some other countries, one billion means 1,000,000,000,000 (one million
million).
binary [adj.]
Do not use as a noun. Use only as an adjective, as in "binary file."
bit field [n.]
bit string [n.]
bit stream [n.], bitstream [adj.]
bitmap [n., adj.]
bitness [n.]
Do not use. Refer to the bit version of an operating system, not to its "bitness."
black box [n.]
Although it is widely used in the computer industry, "black box" is jargon and might not
be understood by all readers. Try to find an alternative, but if you must use it in technical
documentation, provide a definition.
BlackBerry [n.]
(Registered trademark of the mobile device and the company that makes it.)
blink [v.]
Do not use to refer to indicator lights. Use "flash."
blue screen of death [n.]
Do not use. Use "stop error," and describe the type of message received. You can
mention "blue screen," but only as additional contextual information.Example: "You
might receive a stop error on a blue screen, with the message *** Fatal System
Error: ..."
Bluemix [n.]
Use IBM® Bluemix™ on first occurrence.
board [n.]
Do not use by itself to refer to a computer component. Use as part of the term "system
board," or use "adapter."
Boolean [adj.]
Initial cap except in API programming information when boolean (all lowercase) refers to
a primitive return type.
boot, reboot [v.]
Acceptable when referring to or in connection with a computer, but use "start" when
possible.
both [conj.]
Use to refer to two items only (for example, "Create a password for both the
administrator and the user"). To conform to modern usage, and to be precise, use
"both" for only two items when used as a conjunction. (This usage advice is contrary to
the example shown in the Merriam-Webster Collegiate Dictionary.)
bottom left, bottom right [n.]; bottom-left, bottom-right [adj.]
Do not use. Use "lower left" / "lower right" [n.] or "lower-left" / "lower-right" [adj.] to refer
to the location of an item in an interface. Accessibility requirement: People who are blind
or have low vision might not be able to understand information if it is conveyed only by
location. Provide additional text information other than location. For example, write "The
tables are displayed in the Table List pane, which is in the lower right of the window,"
not "The list of tables is displayed in the lower right of the window."
breadcrumb [n.]
Use only to refer to a web interface element that displays the reader's current position
within a site at the top of the web page.
breadcrumb trail [n.]
Do not abbreviate as "BCT."
breadcrumbing [n.]
Do not use to describe the act of navigating on the web. Use "breadcrumb trail" instead.
breakpoint [n.]
bring up [v.]
Do not use with reference to hardware, software, or UI elements. Replace with "open"
or "start."
broken [adj.]
Use to describe a connection that has been disconnected. Do not use "lost."
browse [v.]
Use when referring to or in connection with a site (but not a list).
buffer pool [n.]
built-in [adj.]
Correct: "built-in diagnostic tools."
bus master [n.]
buses [n.]
Plural of bus
business partner [n.]
Do not use "business partner" generically to refer to the relationship that IBM has with
another company; it implies a legal business partnership. Use "IBM Business Partner"
when referring to a participant in the IBM Business Partner program. You can use
"business partner" to refer to the partnership that companies (real or fictitious) other
than IBM have with each other.
business-to-business [adj.]
Do not use the abbreviation "B2B" in technical writing. Spell out "business-to-
business," but consider using a phrase that is less marketing oriented. For example,
instead of "a business-to-business relationship," consider writing "a relationship
between one business and another."
business-to-consumer [adj.]
Do not use the abbreviation "B2C" in technical writing. Spell out "business-to-
consumer," but consider using a phrase that is less marketing oriented. For example,
instead of "a business-to-consumer relationship," consider writing "a relationship
between a business and a consumer."
business-to-employee [adj.]
Do not use the abbreviation "B2E" in technical writing. Spell out "business-to-
employee," but consider using a phrase that is less marketing oriented. For example,
instead of "a business-to-employee relationship," consider writing "a relationship
between a business and an employee."
button [n.]
Use a qualifier with "button" (for example, "radio button" or "toolbar button") or just
refer to a control by its label (for example, "Click New"). Do not use "button" to refer to
a key on a keyboard.
button area [n.]
Use to refer to the area at the bottom of a wizard page that contains the push buttons
that apply to the entire wizard, not just one individual page.
bytecode [n.]
C
cache [n., v.]
Use as a noun rather than a verb in most cases. If possible, avoid the verb form by
using a suitable alternative, such as "store in a cache."
callout [n., adj.] call out [v.]
camel case [n., adj.]
Avoid this imprecise colloquialism when possible. Instead, explicitly state your
convention and give an example. If you must use this term, enclose it in quotation
marks, and include an explanation and an example. Because this term is only one of
several terms for the same concept, it causes problems for translators. In addition, it is
ambiguous because the capitalization scheme varies.
can [v.]
Use to indicate ability. Use instead of "could." (See may, might, can.)
canceled [adj., v.], canceling [v.], cancellation [n.]
canned [adj.]
Do not use. Depending on the context, use a more precise word such as "preplanned,"
"preconfigured," or"predefined." "Canned" is a jargon term that has many slang
interpretations, and it is too vague to use for a wide range of meanings.
card [n.]
Use to refer to a circuit board that is integral to the computer, unless another term (such
as "system board") is more appropriate.
card reader [n.]
carry out [n.]
Do not use if more direct wording is possible. For example, replace "Carry out testing of
the scenarios" with "Test the scenarios"; replace "Carry out these commands" with "Run
these commands."
Cascading Style Sheets (CSS) [n.]
case insensitive [adj.]
Replace with "not case-sensitive."
case-sensitive [adj.]
catalog [n., v.]
catastrophic error [n.]
Replace with "unrecoverable error" or use wording that indicates that the error disrupts
operations.
catch [v.]
Do not use to refer to the detection of an undesirable status situation except in Java
documentation, as in "catch an exception."
Correct: "detect an error"
Incorrect: "catch an error"
CBE [n.]
Do not use this abbreviation of "Common Base Event." "CBE" is a trademark of another
company.
CBTS [n.]
Do not use "CBTS" as the abbreviation of "CICS Transaction Services." "CICS BTS" is
the recommended diminution, although "BTS" is acceptable in the appropriate context.
CD drive [n.]
Use "CD drive" if the read/write characteristic of the drive varies, cannot be predicted, or
is irrelevant.
CD-ROM [n.]
Use "CD-ROM" or "CD-RW" only if you must be specific about the read/write
characteristic of the CD. Do not use to refer to a compact disc; use "CD" instead.
CD-ROM drive [n.]
Use to refer to a read-only CD drive. If the read/write characteristic of the drive varies,
cannot be predicted, or is irrelevant, use "CD drive."
CD-RW drive [n.]
Use to refer to a CD drive that can be read from and written to (a CD read/write drive). If
the read/write characteristic of the drive varies, cannot be predicted, or is irrelevant, use
"CD drive."
central processing unit [n.]
Use only when the term is used explicitly in the product interface. Otherwise, use
"processor" or "microprocessor." The same advice applies to the abbreviation "CPU."
"Central processing unit," or "CPU," is an older term for "processor" or
"microprocessor."
character-based interface [n.]
Use this term to contrast with a graphical user interface. Do not use "green screen."
check [v.]
Do not use to refer to marking a check box. Use "select" and "clear."
check box [n.]
check in [v.], check-in [n., adj.], check out [v.], check-out [n., adj.]
check mark [n.]
checklist [n.]
checkpoint [n.]
child [n.]
Use "child," not "children," to describe a noun.
Correct: "child processes"
chip set [n.]
choose [v.]
Do not use to refer to actions performed on interface elements. Use "click" or "double-
click" for menu commands, push buttons, and other interface elements. Use "select"
and "clear" for check boxes.
chronological [adj.]
Not "chronologic"
class of service (plural: classes of service) [n.], class-of-service [adj.] [n.]
class path [n.]
Two words except when used in code or commands (classpath).
cleanup [n.], clean up [v.]
clear [v.]
Use "clear," not "deselect" or "unselect," to refer to removing a mark from a check box.
CLI [n.]
Abbreviation for "command-line interface." In most cases, use "command line" unless
you need to make specific reference to the command-line interface, as opposed to the
graphical interface.
click [v.]
Not "click on"
Use when referring to or in connection with a menu, option on a pop-up menu, icon,
folder, button (such as the OK button), radio button, or tab on a dialog box.
client [n.]
Use "client," not "customer," in marketing collateral. "Client" implies a higher level of
strategic consultation and partnership than "customer."
client/server [n., adj.]
Not "client-server"
client side [n.] client-side [adj.]
code base [n.]
code page [n.]
code point [n.]
code set [n.]
cold boot, cold start [n.]
Replace with "hardware restart" or similar alternative wording.
combination box [n.]
Use only in information for interface developers to explain how to create a graphical
interface. Do not use in instructions about how to use a graphical interface; use the
name of the field instead.
combo box [n.]
Do not use.
comes with [v.]
Replace with "includes."
comma-separated values (CSV) [n.]
command console [n.]
Do not use.
command line [n.], command-line [adj.], command prompt [n.]
In Windows documentation, use "command prompt." In non-Windows or cross-system
documentation, use "command line."
comment out [v.]
Use to describe the act of adding characters to the beginning of a line of code to
indicate that the line is not to be compiled.
Common Base Event [n.]
Do not use "Common Base Event" as a noun. Instead use the generic term "event." If
you must be more specific, write something like "an event that conforms to the Common
Base Event specification."
Communications Server [n.]
State the operating system to which the server applies, such as "Communications
Server for AIX" or "Communications Server for z/OS." Do not use "CommServer."
compile [v., adj.], compiler [n., adj.], compilation [n.]
Use "compile" as an adjective only in industry-standard phrases such as in "compile
time." Otherwise, use "compilation." Use "compiler" when referring to the actual
compiler, as in "compiler option."
complete [v.]
Do not use as a reflexive verb. Use "is completed."
Correct: "the program is completed."
Incorrect: "the program completes."
componentization [n.]
Replace with "component-based development," "component model," "component
architecture," "shared components," or another similar expression unless
"componentization" is part of the existing product terminology.
componentize [v.]
Replace with "develop components" or a similar phrase unless "componentize" is part of
the existing product terminology.
compress [v.]
Use to mean the compressing of files with a compression utility. Do not use "jar," "tar,"
or "zip" as a verb.
comprised of [v.]
Do not use. "Comprise," which means both "be made up of" and "make up," is often
used incorrectly. Consider replacing it with a clearer alternative such as "consist of,"
when possible.
Correct: "The array comprises five disks."
Correct: "Five disks comprise the array."
Correct: "The array consists of five disks."
Incorrect: The array is comprised of five disks.
congratulations [n.]
Do not use in technical information. If you believe that it is useful to inform readers that
they have completed a tutorial or a complex procedure, state the obvious: "You have
now completed the tutorial."
connect [v.]
Do not use as an intransitive verb.
Correct: "The power cord is connected to the computer."
Incorrect: "The power cord connects to the computer."
connect with [v.]
Replace with "connect to."
console [n.]
Do not use interchangeably with "workstation" or "terminal."
consumability [n.]
Do not use in technical information. Use more precise terms relating to specific features
of a product. Although this term is widely used, it causes translation difficulties.
consume [v.]
Do not use when a simpler term such as "use" would be more appropriate. Use only to
mean "use up."
Correct: "The number of disk pages used by all indexes defined on a table ..."
Correct: "Because the resources have been consumed, they can no longer be used."
Incorrect: "The number of disk pages consumed by all indexes defined on a table..."
context menu [n.]
Do not use. Use "menu" if possible. Use "pop-up menu" if you must emphasize how the
menu functions.
context-sensitive help [n.]
Use "context-sensitive help" when you are describing how to create different types of
help information. When addressing users of help, use just "help."
contextual help [adj.]
Do not use to describe how to use the help. Use "help" when you are addressing users
of help. If you are describing how to create different types of help information, use
"context-sensitive help."
control-click [v.]
Replace with "press Ctrl and click."
conversion [n.]
Use "conversion," not "translation," to refer to the conversion of internal data to a
different format.
copybook [n.]
corrupt [v.]
Use only as a verb. Use "corrupted" for the adjective form.
corrupted [adj.]
Use "corrupted," not "corrupt" (for example, "The file is corrupted").
Correct: "The file is corrupted."
Incorrect: "The file is corrupt."
cost-effective [adj.], cost-effectively [adv.]
could [v.]
Do not use in the present tense to mean "might" or "can." Use only in the past
conditional form.
Correct: "files that could not be identified"
CPU [n.]
Use "central processing unit" and its abbreviation, "CPU," only when the terms are used
explicitly in the product interface. Otherwise, use "processor" or "microprocessor."
"CPU," or "central processing unit," is an older term for "processor" or "microprocessor."
crash [v.]
Use a more specifc term, such as "fail," "lock up," "stop," or "stop responding."
criterion (singular), criteria (plural) [n.]
CRM [n., adj.]
Abbreviation for "customer relationship management"
cross-reference [n.]
CRUD [n.]
Do not use. Instead, write what it means: "create, retrieve, update, and delete."
Ctrl-click [v.]
Replace with "press Ctrl and click."
customer [n.]
Replace with "client."
customer relationship management (CRM) [adj.]
customers [n.]
Talk to your readers ("you"), not about them ("customers").
D
daemon [n.]
data [n.]
Use as a singular noun with a singular verb, even though "data" is the plural of "datum."
data center [n.], data-center [adj.]
data file [n.]
data flow [n.]
data mart [n.]
data pool [n.]
data set [n.]
data sheet [n.]
data source [n.]
data store [n.]
(Exception: Use "datastore" in the context of a VMware datastore.)
data type [n.]
Two words except when used in code or commands (datatype).
database [n.]
datum [n.]
Do not use. Use "data" as a singular noun with a singular verb.
daughterboard [n.]
Do not use. Use the specific name or function of the plug-in adapter that you are
referring to.
daylight saving time [n.]
DD statement [n.]
Spell as shown. Do not use as a synonym for "ddname."
ddname [n.]
All lowercase to represent the name of a DD statement. Do not use "ddname" to mean
"DD statement." Not "DDNAME."
distributed denial of service (DDoS) [n.], distributed denial-of-service
(DDoS) [adj.]
deactivate [v.]
Not "inactivate"
deallocate [v.]
Not "unallocate"
debuggable [adj.]
Do not use. Rephrase the sentence to use the verb or noun "debug."
Correct: "You must rebuild the version that can be debugged."
Incorrect: "You must rebuild the debuggable version."
decision maker [n.], decision making [n.], decision-making [adj.]
decompress [v.]
Use "decompress" to refer only to converting compressed data to its expanded or
original size. See also "extract."
decompressed [adj.]
Use "decompressed" to refer to data that was previously compressed. Use
"uncompressed" to refer to data that was not previously compressed.
deconfigure [v.]
Replace with "unconfigure."
deinstall [v.]
Replace with "uninstall."
deinstallation [n.]
Do not use. Replace with "uninstallation."
demilitarized zone [n.]
Do not use "demilitarized zone," which has military connotations, or "perimeter network."
Use "DMZ." A "DMZ" is a configuration that includes multiple firewalls, which add layers
of protection between a corporate intranet and a public network, such as the Internet.
demo [n., v.]
Do not use, except in marketing content. Use "demonstration" (n.) and demonstrate (v.).
demount [v.]
Use "demount" except in information for a UNIX system, such as AIX. For UNIX
systems, use "unmount" or "remove."
deploy [v.]
Use only as a verb. The noun or adjective is "deployment."
depress [v.]
Do not use to refer to pressing keys, buttons, or latches or typing on a keyboard. Use
"press" or "type" to refer to a keyboard, and use "press" with reference to hardware
devices.
deregister [v.]
Replace with "unregister."
deselect [v.]
Do not use to refer to removing a mark from a check box. Use "clear." Use instead of
"unselect" in other situations.
designed to [v.]
In technical information, do not use "designed to" to describe a concrete product
function. In some situations, it is appropriate to use "designed to," for example, to refer
to potential performance benefits but ensure that you do not make a false claim.
Correct: "product X provides..."
Incorrect: "product X is designed to provide..."
desire [v.], desired [adj.]
Replace with "want" [v.] or "required" [adj.]
destroy [v.]
Do not use to indicate removal of an object from a database. Write specifically what
happens to the object, such as "delete from the database."
developer kit [n.]
Use "developer kit," "Java developer kit," or "Java SDK" as a generic reference to a
developer kit that is not from Oracle.
developerWorks community [n.]
Use "developerWorks community" when you're referring collectively to the community
applications or to the community network of users. Note: Continue to use "My
developerWorks profile" or "My developerWorks home" when you're referring
specifically to a user's personalized profile or customized home page.
diagnostic [adj.]
Do not use as a noun.
Correct: "diagnostic tests"
diagnostics [n.]
OK to use as an alternative to "diagnostic tests."
dial-up [adj.]
Correct: "dial-up connection"
dialog, dialogue [n.]
Use "dialog" to refer to communication with a computer. Use "dialogue" only when
referring to a conversation between people. Do not use "dialog" for "dialog box."
dialog box [n.]
Use only in technical information for programmers when it is important to distinguish
parts of the interface. Do not use "dialog" or "dialogue box." For most user information,
use "window" when referring to a graphical interface. A dialog box is a secondary
window that gathers additional information from the user.
discuss [v.]
Acceptable in developerWorks content when used to refer to describing a subject in
written information. (Exception to theIBM Style Guide.)
disk [n.]
Spell as shown for all types of disks except compact discs and digital video discs.
dismiss (a window, a dialog box) [v.]
Replace with "close."
dismount [v.]
Replace with "demount" except in information for a UNIX system, such as AIX. In that
case, use "unmount" or "remove."
display [v.]
Use only as a transitive verb.
Correct: "The message is displayed."
Correct: "The system displays a message."
Incorrect: "The message displays."
DMZ [n.]
Use in preference to "demilitarized zone." Do not use "perimeter network." A "DMZ,"
also referred to in the industry as a "demilitarized zone" or "perimeter network," is a
configuration that includes multiple firewalls, which add layers of protection between a
corporate intranet and a public network, such as the Internet.
do (a step) [v.]
Use "complete" or "perform."
Domain Name System (DNS) [n.]
domestic [adj.]
Do not use "domestic" and "foreign" to differentiate geographic locations. Use the
names of the respective countries or regions, or use phrases such as "United States
only" and "countries other than the United States."
done [adj.]
Use "finished."
dos and don'ts [n.]
DOS session [n.]
Use "DOS session," not "DOS environment" or "virtual DOS machine."
dot-com [n., adj.]
dotted decimal [adj.]
double quotation mark [n.]
Not "double quote" or "double quote mark"
double-byte [adj.]
double-check [v.]
double-click [v.]
Not "double-click on"
doubleword [n.]
downgrade [v]
Do not use to refer to the opposite of "upgrade." Use a term such as "fallback," "fall
back," "rollback," or "roll back," or use a phrase such as "revert to an earlier version."
downlevel, down-level [adj.]
Replace with "earlier, "previous," or "not at the latest level."
downtime [n.]
downward compatible [adj.]
Replace with "compatible with earlier versions."
drag [v.]
Use when referring to or in connection with an icon or object that can be moved.
drag and drop [v.]
Replace with "drag," which includes the action of dropping an object.
drag-and-drop [adj.]
drill down [v.]
Correct: "Drill down to the folder that contains your file."
drill up [v.]
Replace with "navigate."
driver [n.]
Use "device driver," "network driver," or another appropriate descriptive qualifier on first
occurrence in a topic or paragraph. Use "driver" alone only when you are referring to the
circuit that sends signals to a device.
drop-down list [n.]
Preferred over "pull-down list"
due to [prep.]
Use only in adjectival clauses. In adverbial clauses, replace with "because of."
Correct: "Because of the power failure, the update stopped."
Correct: "The power failure was due to an electrical storm."
Incorrect: "Due to the power failure, the update stopped."
dump file [n.]
E
ebook [n., adj.]
e-commerce [n.]
Acceptable in developerWorks content when used to mean the subset of electronic
business that involves the exchange of money for goods or services purchased over an
electronic medium such as the Internet. (Exception to the IBM Style Guide.)
e-discovery [n.]
Hyphenated and lowercase, except when referring to IBM product names that include
the word eDiscovery.
e-fix, eFix [n.]
Replace with the appropriate term, such as "fix," "interim fix," "program temporary fix,"
or "test fix."
e-Kit [n.]
Use the hyphen and init cap on K. (At the start of a sentence, add init cap on E.)
email [n., adj.]
Correct: "Send email to your representative."
Incorrect: "Email your representative."
e-learning [n.]
e.g. [conj.]
Replace with "for example" or "such as."
EAR file [n.]
For generic references, use uppercase and a noun.
Correct: "Java packages often include EAR files."
.ear file [n.]
For specific references, use a dot, lowercase, and a noun.
Correct: "Open the .ear file."
earlier [adv.]
Use to refer to a previous software version or fix level.
either [adj.]
Use to mean "any one of two." Although "either" can be used to mean "each," as in
"close the latch on either side of the cover," avoid this usage. Use "each" to avoid
confusion or imprecision.
EJB [adj.]
Abbreviation for "Enterprise JavaBeans." Use only as an adjective, as in "EJB server" or
"EJB component." The artifact that is created by EJB programmers is called enterprise
beans, EJB beans, or EJB components, not EJBs.
enable [v.]
Acceptable in dW content to mean "to render able," whether the subject is human or an
inanimate object. However, whenever possible, use a direct, user-focused alternative
such as "you can use the product to..." or "with this product, users can..." (Exception to
the IBM Style Guide)
end [v.]
Use when referring to or in connection with communications or network connections.
end user [n.]
Replace with "user."
end-user interface [n.]
Replace with "graphical interface" or "interface."
endpoint [n.]
ensure [v.]
Not "insure," except in the context of an insurance policy.
enter [v.]
Use to refer to entering text in fields in a graphical interface. Alternately, use "type." Use
"type," "enter," or "issue" to refer to entering a command on a command line or at a
command prompt; use one term consistently throughout your information.
enterprise resource planning (ERP) [n.]
EPUB [n.]
Use as a noun only to refer to the file type, not to refer to an EPUB file.
Correct: "The following file types are supported: EPUB, HTML, PDF,..."
Incorrect: "Download the EPUB."
errata (plural), erratum (singular) [n.]
error message [n.]
Not "error," to refer to a message that notifies the user of an error. Use "message" as a
generic term to refer to an informational message, a warning message, or an error
message.
etc. [n.]
Replace with "and so on" when you list a clear sequence of elements, such as "1, 2, 3,
and so on" or "Monday, Tuesday, Wednesday, and so on." When you list items that do
not form a clear sequence, use appropriate descriptive wording, such as "device drivers,
firmware, and other code."
Ethernet [n.]
EUI [n.]
Do not use "end-user interface" or "EUI." Use "graphical user interface" or "interface."
euro [n.]
even-numbered, odd-numbered [adj.]
executable [adj.]
Use only as an adjective, followed by the noun that it is modifying.
Correct: "executable program"; "executable routine"
execute [v.]
In technical content, use only if a simpler, less technical term, such as "run" or "issue,"
or a more specific term, such as "start," "enter," or "open" is inappropriate. If execute is
used as a keyword, you can use "execute" in related text to maintain consistency.
expand [v.]
Use when referring to or in connection with a navigation tree or a folder.
expose [v.]
Replace with "display," "show," or "make available."
extract [v.]
Use "extract" to refer to restoring data from an archived or compressed file either when
the extraction of the data is separate from the decompression and you must distinguish
between them, or when the extraction and decompression occur in a single action. See
also "decompress."
extranet [n.]
F
fail [v.]
Use when referring to or in connection with a disk
failback [n., adj.], fail back [v.]
failover [n.], fail over [v.]
fast path [n.], fast-path [adj.]
fatal [adj.]
Use only to refer to situations resulting in death, and not to refer to the failure of a
program or application. Use "unrecoverable" or other wording that indicates that an
operation is disrupted.
fax [n., v.]
Fibre Channel [n., adj.]
field [n.]
In the UI context, use "field" instead of "text field" or "text entry field" in most cases. Use
a qualifier such as "entry" if necessary to distinguish between different types of fields for
a specific audience such as programmers.
Correct: "the User ID field"
Incorrect: "the User ID text field"
file mode [n.]
Two words except when used in code or commands (filemode).
file name [n.]
Two words except when used in code or commands (filename).
file set [n.]
Two words — unless you are using it in the context of a UNIX system (such as AIX), in
which case it is one word (fileset).
file system [n.]
Two words as a generic term, except in an entrenched usage like the Filesystem
Hierarchy Standard (FHS). In an article about the FHS, for example, keep all instances
one word (your "filesystem") for consistency throughout the article.
file type [n.]
Two words except when used in code or commands (filetype).
fill in [v.]
Replace with a more precise verb, such as "complete," "enter," or "specify."
Correct: "Complete the remarks section."
Correct: "Enter the name and address."
Correct: "Specify the job queue parameter."
Incorrect: "Fill in the remarks section."
finished [v.]
Use when referring to or in connection with completing a task.
firewall [n.]
fix pack [n.]
Use initial uppercase letters only when referring to a specific fix pack number, Correct:
"Install the first fix pack."
Correct: "Next, install Fix Pack 2."
fixed disk drive [n.]
Replace with "hard disk drive."
flash [v.]
Use "flash," not "blink," to refer to indicator lights.
flash memory [n.]
Not "flash storage"
flavor [n.]
Replace with "version" or "method."
floppy, floppy disk, floppy drive [n.]
Replace with "diskette" and "diskette drive."
flyout [n., adj.]
Not "fly-out." Refers to a type of menu in a GUI. Use only when it's important to
distinguish the menu type; otherwise use "menu."
follow up [v.], follow-up [n., adj.]
following [n., adj.]
Do not use as a noun except to refer to a group of followers, adherents, or partisans.
Otherwise use as an adjective.
Correct: "Complete the following steps:"
Correct: "The adapter has the following functions:"
Incorrect: "Do the following:"
Incorrect: "The adapter's functions include the following:"
foo, foobar, fubar [n.]
Do not use. These terms are variants of an acronym of a profanity that is sometimes
used by developers in code. If you see either term in sample code, revise the example
or do not publish it. Rewrite any text to omit these terms.
foreign [adj.]
Do not use to differentiate geographic locations. Use the names of the respective
countries or regions, or use phrases such as "United States only" and "countries other
than the United States."
forward compatible [adj.]
Replace with "compatible with later versions."
forward slash [n.]
Refers to the / character.
free [adj.]
The current IBM legal guideline the adjective "free" only if "all qualifying conditions
needed to establish eligibility for the free item are fully disclosed...in close promixity to
the offer." So, if there are no qualifying conditions (the item is truly free), then use "free."
freeze [v.]
Do not use to refer to a software application that stops responding.
Correct: "The application stops responding."
Correct: "The application hangs."
Incorrect: "The application freezes."
front end [n.], front-end [adj.]
FTP [n., adj.]
Abbreviation for "File Transfer Protocol." Do not use as a verb.
Correct: "Use FTP to send the file."
Incorrect: "FTP the file."
full-time [adj., adv.]
fullword [n., adj.]
functionality [n.]
Use only to refer to a set of functions and their specified properties. Consider using a
simpler term, for example "functions."
G
generally [adv.]
Use to mean "in disregard of specific instances" or "in all instances." The definitions of
"generally," "normally," "typically," and "usually" are similar, and in some cases, more
than one of these terms might be applicable. Use your judgment in deciding which term
best applies.
Correct: "Generally, hot-swap devices can be removed and replaced while the server is
operating."
geography [n.]
Do not use to mean "geographical area."
Correct: "This version is available worldwide."
Incorrect: "This version is available in all geographies."
Gigabit Ethernet [n.]
globalize [v.], globalization [n., adj.]
Use to refer to adapting software by providing multicultural support and translation for all
locales.
green screen [n.]
In most cases, use a more precise term such as "3270 application," "5250 application,"
or "character-based interface." "Green screen" is occasionally used to refer to
monochrome display devices. If you need a term to contrast with "GUI," use "character-
based interface." If you must use "green screen," for example because you believe your
audience will use it as a search term, enclose the first occurrence in quotation marks to
indicate that it is a nonstandard term, clarify what it means, and thereafter use preferred
alternatives.
gray [adj.]
Not "grey"
group ID [n.]
guarantee [n., v.]
Do not use.
GUI [n., adj.]
Acronym for "graphical user interface"; no need to spell out.
gzip [v.]
Do not use mean to compress files with a compression utility. Use "compress," which
applies to a variety of formats and utilities.
gzipped [adj.]
Do not use to refer to a compressed file. Use "archive" or "compressed file," which
applies to several formats and utilities. To refer to a file that was compressed with the
gzip program, it is acceptable to use "file in gzip format."
H
halfword [n., adj.]
handheld [adj.]
hard boot [n.]
Do not use.
hardcopy [n.]
hard disk [n.]
Use to refer to the disk in a hard disk drive.
hard disk drive [n.]
"Hard disk" is a common short form, but the longer, more complete term is preferred.
hard drive [n.]
Replace with "hard disk" or "hard disk drive" as appropriate.
hard file [n.]
Replace with "hard disk" or "hard disk drive" as appropriate.
hardcoded [adj.]
hash, hash sign [n.]
Use "number sign" to refer to the # character unless you are writing information
exclusively for a UK audience.
healthcare [n., adj.]
heartbeat [n., adj.]
heat sink [n.]
help [n.]
Correct: "Consult the online help."
Incorrect: "Consult the online Help."
help desk [n.], help-desk [adj.]
hence [adv.]
Replace with "therefore."
higher [adj.]
Do not use to describe versions of software or fix packs. Use "later."
hit [v.]
Do not use to refer to pressing keys or typing on a keyboard. Use "press" or "type."
home page [n.]
"Home page" has an initial uppercase H only when it is part of a proper noun. The
terms "home page," "web page," and "website" have different meanings and should not
be used interchangeably.
host ID [n.]
host name [n.]
Two words except when used in code or commands (hostname)
hostfile [n.]
Use only in code or commands. Otherwise, use "host file" or "hosts file."
hover help [n.]
Use "hover help," not "tooltip" to refer to explanatory text, rich text, or links that can be
viewed by moving a cursor over a graphical user interface (GUI) element, such as an
icon, field, or text string. The term "tooltip" refers to a brief, plain text description that is
displayed when a cursor is moved over a graphical image, such as an icon, that does
not otherwise have a label.
how-to [adj.]
Not HOWTO. Do not use as a noun.
Correct: "how-to procedure"
HTML [n., adj.]
Abbreviation for "Hypertext Markup Language"; no need to spell out
HTTP, HTTPS [n., adj.]
Abbreviations for Hypertext Transfer Protocol and Hypertext Transfer Protocol Secure;
no need to spell out.
I
i.e. [conj.]
Don't use. Use "that is," or some other appropriate phrase.
I/O [adj.]
IBM Business Partner [n.]
In formal communication, keep the init caps. Avoid using "partner," "partnership,"
"partnering" with respect to IBM. You can use "business partner" to refer to the
partnership that companies (real or fictitious) other than IBM have with each other.
IBM Global Services [n.]
Use all three words. Avoid IGS or Global Services.
IBM Knowledge Center [n.]
In March 2014, most IBM product documentation that was published in information
centers moved to a new publication vehicle: IBM Knowledge Center. Use "IBM
Knowledge Center" (with no preceding article) to refer to the collection of IBM product
documentation. To refer to the type of content in IBM Knowledge Center, use a general
term such as "product documentation" or "documentation." Do not use "Knowledge
Center" on its own, because it is the trademarked product name of another company.
IBM Redbooks [adj.]
Do not use as a noun. See Redbooks [adj.]
IBM Redpaper [n., adj.]
IBM's [n.]
Avoid "IBM's," especially before product names; for example, saying "IBM's AIX"
suggests a distinction between IBM's version of AIX and some other company's.
ID [n.]
Abbreviation of "identification" or "identifier."
Correct: user ID
Incorrect: user id
if...then [conj.]
Avoid using "then" to introduce an independent clause that follows an "if" clause.
Correct: "If you set a password, access is restricted."
Incorrect: "If you set a password, then access is restricted."
But the "if...then" construction can improve clarity when you are joining two long
clauses.
ifix, i-fix, iFix, i-Fix [n.]
Replace with "interim fix."
illegal [adj.]
Use only for matters of law. Otherwise, use a term such as "invalid," "not allowed," or
"incorrect."
impact [v.]
Use as a verb only to mean "to strike forcefully." Otherwise, use "affect."
in-depth [adj.], in depth [adv.]
in order to [prep.]
Use "to" in most cases to avoid wordiness.
in other words [prep.]
Replace with "for example" or "that is." Ideally, state the original information clearly so
that it does not require explanation.
in spite of [prep.]
Replace with "regardless of" or "despite."
in the event [conj.]
Replace with "in case," "if," or "when."
inactivate [v.]
Replace with "deactivate."
independent software vendor (ISV) [n.]
Use instead of "software vendor," "third-party software vendor," or other terms for non-
IBM software vendors. An ISV that has joined PartnerWorld for Developers is thereafter
referred to as a "member" or "IBM Business Partner."
indexes [n.]
Use "indexes" for the plural of "index" unless the context requires "indices," as in
mathematics.
infocenter, info center, information center [n.]
Do not use to refer to IBM product documentation. See IBM Knowledge Center.
information on [prep. phrase]
Replace with "information about."
information technology [n., adj.]
Use "IT" instead.
Infrastructure as a Service (IaaS) [n., adj.]
ingest [v.]
Use to refer to processing data only when the term is part of the existing product
terminology. Otherwise, use "import," "load," "obtain," "process," or a similar term.
initial capital letters [n.]
Do not abbreviate to "initial caps."
inline [adj.]
input [n., adj.]
Do not use as a verb. Replace with "type" or "enter" as appropriate.
install [v.]
Use only as a verb. For the adjective and the noun, use "installation."
InstallShield [adj.]
Do not use to refer to an installation program that was created by using the
InstallShield product. Use "installation program" or "installation wizard." InstallShield is a
trademark of another company.
instant message [n.]
Use only as a noun.
Correct: "Send her an instant message."
Incorrect: "Instant message her."
instead of
Replace with "rather than."
insure [v.]
Replace with "ensure, " except in the context of an insurance policy.
internationalize [v.], internationalization [n., adj.]
Do not use in relation to IBM software products. (They are no longer relevant in IBM
software development, because products are no longer internationalized and then
localized.) For IBM products, replace with "globalize" and "globalization."
interim fix [n.]
internet [n.]
Write with a lowercase i to refer to a general collection of interconnected networks that
use the Internet suite of protocols.
Internet [n.]
Write with an uppercase I to refer to the well-known, worldwide collection of
interconnected networks that use the Internet suite of protocols and that permits
universal public access.
Internet address [n.]
Do not use unless the term is part of existing product terminology. Use a more specific
term such as "IP address," "URL," "Internet email address," or "web address," as
appropriate.
Internet of Things (IoT) [n.]
intranet [n.]
invoke [v.]
Use a simpler term, such as "start" or "call," if it conveys the same meaning. Although
"invoke" is prevalent in the industry, it might cause problems for translators and readers
whose first language is not English.
irrecoverable [adj.]
Replace with "unrecoverable."
is displayed [v.]
Use when referring to or in connection with message
issue [v.]
Use "type," "enter," or "issue" to refer to entering a command on a command line or at a
command prompt. Use one term consistently throughout your information.
IT as a Service (ITaaS) [n., adj.]
itself [pron.]
Do not use.
J
jar [v.]
Do not use to refer to the action of creating a Java archive (JAR) file. Use a verb such
as "compress" or "archive."
JAR file [n.]
Correct: "Java packages often include JAR files."
.jar file [n.]
Correct: "Open the .jar file."
Java Development Kit (JDK) [n.]
Use only to refer to a developer kit from Oracle. For a generic reference, use "developer
kit," "Java developer kit," or "Java SDK."
Java SDK [n.]
Use "Java SDK," "Java developer kit," or "developer kit" as a generic reference to a
developer kit that is not from Oracle.
JavaBeans [n.]
Not "JavaBean"
Javadoc [adj.]
Do not use as a noun. To refer to the output of the Javadoc tool, use "Javadoc
information," "Javadoc HTML documentation," "API documentation," or "Java API
documentation."
JavaScript [n., adj.]
JavaServer Pages (JSP) [adj.]
Because this is a trademark, it must be used as an adjective. Follow with "technology,"
"pages," or some other appropriate noun.
JDBC [n.]
JDBC is the trademarked name and is not an abbreviation.
job log [n.]
job stream [n.]
Just-in-time (JIT) compiler [n.]
K
kanji [n., adj.]
keep in mind [v.]
Replace with "remember."
keepalive message [n.]
Use only in the context of Internet communication. Do not confuse with the similar but
unrelated term "liveness message."
key [v.]
Do not use as a verb. Use "type" or "press."
keystore [n.]
kill [v.]
Do not use except when you are documenting a UNIX system, such as AIX. Use "end"
or "stop."
L
labeled [v., adj.]
laptop [n.]
Do not use to refer to hardware. Use "notebook" to refer to a mobile computer. For
safety, do not use wording that implies that such a computer can be used while placed
on a person's lap.
later [adv.]
Use to refer to a subsequent software version or fix level
latest [adj.]
Do not use "latest" to describe products, functions, features, technologies, or standards
when the term will become obsolete if another version is released. A topic that
describes something as the "latest" might be in circulation long after the "latest" item
has become established or obsolete.
Latin abbreviations
Do not use Latin abbreviations. They interfere with translation, and people who speak
languages that are not based on Latin might not understand them. Instead, say what
you mean.
Correct: "through," "compared to"
Incorrect: "via," "versus"
launch [v.]
Replace with "start" or "open."
launchpad [n.]
Layer [followed by a numeral] [n., adj.]
Capitalize when referring to the seven layers of the OSI model and the layer number is
included; no hyphen when used as adjective.
Correct: "...is part of the Layer 6 architecture."
Correct: "...is part of the data layer."
Left Arrow key [n.]
left-align [v.], left-aligned [adj.]
Not "left-justify," "left-justified" (to refer to text that is aligned at the left margin)
left-hand [adj.]
Replace with "left."
leftmost [adj.]
Use to refer to something farthest to the left (for example, on a page or a panel).
legacy [adj.]
OK to refer to "legacy data." Do not use "legacy" to refer to older software, applications
(as in "legacy product"), values, programming languages, or technologies that are being
supplemented or replaced. In particular, avoid any implication that a product is old-
fashioned or might not include up-to-date technologies. Because this usage can cause
problems for our clients, specify the product information without any explanatory
adjectives. For products that are still supported, but are not being actively developed,
use "existing," "heritage," "traditional," "established," "mature," "earlier," or another
appropriate neutral description in preference to "legacy." To compare an existing value
with a newer one, use words showing time relationships, such as "earlier" or "previous."
let [v.]
Avoid stating that inanimate objects grant abilities to people. Whenever possible, use a
direct, user-focused alternative.
Correct: "You can do a, b, and c."
Incorrect: "The program lets you do a, b, and c"
let's [v.]
Always avoid "let us" language.
leverage [v.]
Replace with "use."
lifecycle [n., adj.]
Lightweight Directory Access Protocol (LDAP) [n.]
like [conj.]
Do not use to mean "such as."
line cord [n.]
Replace with "power cable" or "power cord."
link-edit [v.], link-editing [n.]
lite [adj.]
Avoid using this term to describe or explain that a function or product has limited
capabilities. It is appropriate to use the term when it is part of a formal, approved
product or function name, but in those instances, it is still preferable to avoid the term in
explanatory text.
localize [v.], localization [n., adj.]
Do not use in relation to IBM software products. (They are no longer relevant in IBM
software development, because localized versions of products are no longer developed
as separate entities.) For IBM products, replace with "globalize" and "globalization."
load time [n.], load-time [adj.]
LAN [n., adj.]
Abbreviation for "local area network"; no need to spell out.
lock up, stop [v.]
Use when referring to or in connection with a program
log file [n.]
login [n., adj.], logon [n., adj.], log in [v.], log on [v.]
logoff [n., adj.], log off [v.]
log off from [v.]
Not "log off of." In documentation for UNIX systems (such as AIX), use "log off."
log in to [v.]
Not "log into"
log on to [v.]
Not "log onto"
look and feel, look-and-feel [n.]
Replace with wording that more specifically expresses what you mean.
look up [v.], lookup [n.]
lower left, lower right [n.]; lower-left, lower-right [adj.]
Not "bottom left" or "bottom right," to refer to the location of an item in an interface.
lowercase [adj.]
M
machine [n.]
Use a more specific term such as "workstation," "personal computer," "server," or
"component." In the mainframe context, use the name of the operating system followed
by the word "system" — as in "OS/390 system."
main directory [n.]
Replace with "root directory."
makefile [n.]
mashup [n., adj.]
mash up, mashup [v.]
Do not use as a verb. Use "create" or another, similar verb. For example, replace "mash
up your reports" with "create a mashup of your reports."
master and slave [n.]
In a UNIX system (such as AIX), "master and slave" is acceptable usage. Otherwise,
use "subordinate" — not "slave" — to refer to the devices controlled by the master
device.
matrixes [n.]
Not "matrices"
may, might, can [v.]
Use "may" to indicate permission. Use "might" to indicate possibility. Use "can" to
indicate ability. Because "may" (which indicates permission) can cause translation
problems, reword to avoid using it.
medium-size business [n.]
memory stick [n.]
Replace with "USB flash drive."
menu bar [n.]
[menu choices] [n.]
Use > to signify a string of choices, such as File > Edit.
Correct: File > Edit
Incorrect: File->Edit, File=>Edit
message [n.]
Use "message" as a generic term to refer to an informational message, a warning
message, or an error message.
metadata [n.]
mice [n.]
Use "mice" as the plural of "mouse."
microcomputer [n.]
Replace with "PC."
middleware [n., adj.]
midmarket [n., adj.]
Exception: Mid-Market Program Framework
migrate [v.]
Do not use to mean "upgrade" or "port." To migrate is to move data, users, or
applications to a new program, platform, or environment. Migration can occur between
unlike systems, for example, between two different vendors' databases, and migrating
usually involves more work than upgrading. To upgrade is to replace software with a
new release or fix level of the same program or to replace hardware with a newer model
or more powerful technology. An upgrade involves little work on the user's part.
To port is to move an application program from the operating system for which it was
developed to a different operating system. Porting requires less effort than
redevelopment.
motherboard [n.]
Replace with "system board."
mount point [n.]
mouse over [v.]
Replace with "point to" or "move the mouse pointer over." "Mouse" is not a verb, and
"mouse over" is probably impossible to translate.
multimedia, multipart, multiplatform, multiuser, multivendor [adj.]
No hyphens on multianything.
must [v.]
Use "must" — not "have to" or "need to" — unless "must" is too restrictive.
Correct: You must format the disk.
Correct: Format the disk.
Correct: You might have to format the disk.
Incorrect: You need to format the disk.
Incorrect: You have to format the disk.
My developerWorks [n.]
Use "My developerWorks profile" and "My developerWorks home" when you're referring
specifically to a user's personalized profile or customized home page. Use
"developerWorks community" when you're referring collectively to the community
applications or to the community network of users.
N
name server [n.]
namespace [n.]
native [adv.]
Avoid this term when a less-ambiguous term such as "local," "basic," or "required" is
applicable.
navigate [v.]
Use for tree UI elements. For websites, use "browse."
Correct: "Navigate the file tree."
Incorrect: "Navigate the developerWorks site."
neither ... nor [conj.]
Do not use.
.NET [n.]
The Microsoft platform.
Net, the Net [n.]
Abbreviation of Internet.
network-centric computing [n.]
Replace with "network computing."
new [adj.]
Do not use "new" to describe products, functions, features, technologies, or standards
that are updated for each release. A topic that describes something as "new" might be
in circulation long after the "new" item has become established or obsolete.
newline [adj.]
Correct: "the newline character"
Network File System (NFS) [n.]
Do not use as an abbreviation for "network file server."
non-English [adj.]
Use "in languages other than English" or "non-English-language." Use "non-English-
language" only as an adjective, as in "non-English-language document."
nonpageable [adj.]
Use to indicate memory that is not capable of being paged in. To indicate memory that
is capable of being paged in, but is not yet paged in, use "nonpaged."
nonpaged [adj.]
Use to indicate memory that is capable of being paged in, but is not yet paged in. To
indicate memory that is not capable of being paged in, use "nonpageable."
nonrecoverable [adj.]
Replace with "unrecoverable."
normally [adv.]
Use to mean "in a manner that does not deviate from a standard pattern." The
definitions of "generally," "normally," "typically," and "usually" are similar, and in some
cases, more than one of these terms might be applicable. Use your judgment in
deciding which term best applies.
Correct: "The process is running normally."
notebook [n.]
Use "notebook" to refer to a mobile computer or to an interface element that resembles
a physical notebook with pages and tabs.
notion [n.]
Replace with "concept."
null [adj.]
Use only as an adjective
Correct: "If a field is null..." "Enter a null value."
NULL [n.]
Uppercase only if the user is to enter it that way, or if it is a keyword that is spelled that
way.
number sign [n.]
Use to refer to the # character unless you are writing information exclusively for a UK
audience, in which case use "hash sign," or unless you are writing information
exclusively for a US or Canadian audience, in which case use "pound sign."
numeric [adj.]
Not "numerical"
Correct: The Date field contains numeric data.
O
object-oriented [adj.]
Correct: "object-oriented programming"
odd-numbered, even-numbered [adj.]
offline storage [n.]
Replace with "auxiliary storage."
offline [adj.]
offload [v., adj.]
offsite [adj.], off site [adv.]
okay [n., adj.]
Replace with "OK," but only to refer to the text in an interface element.
on ramp, on-ramp [n.]
Do not use to describe a quick way of accessing a product or feature. Replace with a
term such as "access method" or rewrite the information.
Correct: "your solution for fast, affordable meetings"
Incorrect: "your on-ramp to fast, affordable meetings"
on the fly
Replace with a term such as "dynamically," "as needed," "in real time," or "immediately."
on the other hand [conj.]
Replace with "however," "alternatively," or "conversely."
on-demand [adj.], on demand [adv.]
Correct: "on-demand capability," "on-demand solution," "You can deliver these service
on demand."
on-premise, off-premise [adj.]
Correct: "on-premises," "off-premises," "onsite," "offsite"
onboarding [n.]
Not "on-boarding"
once [adj.]
Use only to mean "one time." Do not use as a conjunction to mean "after" or "when."
online [adj., adv.]
online help [n.]
onsite [adj.], on site [adv.]
open source [n., adj.]
But Open Source Initiative, Open Source Definition. Note: no hyphen for adjective form.
out-of-the-box [adj.]
Acceptable if needed to avoid alternatives that sound awkward. If possible without
introducing awkwardness, replace with alternatives such as: "ready to use"; "ready for
customers to use as is, without modification"; "applications that you can rapidly integrate
into the system"; "items that are ready for immediate use"; "default settings"; "initial
values"; "built-in components."
output [n., adj.]
Do not use as a verb if a clearer and more direct alternative is applicable.
Correct: "produce a report"
Incorrect: "output a report"
overhead [n.]
Ideally, replace with terminology that is more specific. For example: "Running large
queries can increase processor usage." is preferable to "Running large queries can
increase overhead."
P
p.m. [adj.]
pain point [n.]
Replace with a term such as "challenge," "concern," "difficulty," or "issue."
panel [n.]
Use only to refer to the display area of nongraphical user interfaces, such as ISPF
interfaces. In GUIs, use "window" and "pane."
parent task [n.]
Replace with "parent process."
parent-child [adj.]
partner [v.]
Do not use as a verb. Replace with "work closely with" or another similar term.
partner [n.]
Use "IBM Business Partner" to refer to a participant in the IBM Business Partner
program. You can use "business partner" to refer to the partnership that companies
(real or fictitious) other than IBM have with each other.
patch [n.]
Do not use to mean a software fix. Use a more precise term that is appropriate for the
product, such as "fix," "test fix," "interim fix," "fix pack," or "program temporary fix."
path name [n.]
PC [n., adj.]
Abbreviation for "personal computer"; no need to spell out.
PDF [adj.]
Abbreviation for "Portable Document Format"; no need to spell out. Do not use as a
noun.
Correct: "Read the PDF file."
Incorrect: "Read the PDF."
perimeter network [n.]
Replace with "DMZ."
Perl [n., adj.]
permit [v.]
Do not use in the sense of an inanimate object granting abilities to people, unless the
object is a type of authorization that does grant abilities. Whenever possible, use a
direct, user-focused alternative such as "you can use the product to..." or "with this
product, users can..."
Correct: "DBADM authority permits you to create database objects."
Incorrect: "the product permits you to..."
phone [n.]
Replace with "telephone," "cell phone," or "mobile phone."
Platform as a Service (PaaS) [n., adj.]
please [adv.]
Plug and Play [adj.]
plugin [n., adj.]
podcast [n.]
pop-up blocker, pop-up killer [n.]
Replace with "software to block pop-up ad windows."
pop-up help [n.]
Use only if you must emphasize how the help functions. Otherwise, use "help."
pop-up menu [n.]
Use only if you must emphasize how the menu functions. Otherwise, use "menu."
position (a cursor) [v.]
Replace with "move."
postrequisite [n., adj.]
pound sign [n.]
Use to refer to the # character only if you are writing information exclusively for a US or
Canadian audience. Otherwise, use "number sign."
Power Architecture technology [n.]
Not "POWER" or "POWER-based architecture"
power on (or off), power down [v.]
Replace with "turn on" (or "turn off").
preload [v.], preloaded [adj.]
Replace with "preinstall," "preinstalled."
prepend [v.]
Replace with "add a prefix to."
prerequisite [n., adj.]
press [v.]
Use "press" — not "depress," "hit," "punch," "push," or "strike" — when referring to or in
connection with holding down a key.
preventive [adj.]
Not "preventative"
prior to [prep.]
Replace with "before."
program temporary fix [n.]
Use this term only for IBM System i, IBM System p, and IBM System z products. For
other IBM products, use "interim fix." Use initial uppercase letters only in a product
name or in a reference to a specific fix number, such as "Program Temporary Fix 2."
Otherwise, use lowercase.
proper [adj.]
Do not use to mean "correct," "applicable," or "appropriate."
publish/subscribe [n., adj.], publish and subscribe [v.]
Not "pub/sub"
pull-down [adj.]
Use only if you must specify the type of menu or list.
Q
quiesce [v.]
Use as either an intransitive verb or a transitive verb.
Correct: "I/O operations quiesce."
Correct: "The program quiesces I/O operations."
quit [v.]
Use when referring to or in connection with a program
quotation mark [n.]
Not "quote mark"
quote [n.]
Do not use to refer to cited text. Use "quotation."
quoted [adj.]
Do not use to mean "enclosed in quotation marks."
Incorrect: "quoted string"
R
RAM [n.]
Abbreviation for "random access memory"; no need to spell out.
read-only [adj.]
read/write [n., adj.]
readme [adj.]
Use as an adjective to modify the word "file."
Correct: "In the readme file, ..."
Incorrect: "In the readme, ..."
real time [n.], real-time [adj.]
reboot, boot [v.]
Acceptable when referring to or in connection with a computer (but use restart/start
when possible).
recommend [v.]
Replace with "suggest."
recovery point objective (RPO) [n.]
recovery time objective (RTO) [n.]
Redbook, Redbooks, redbook, redbooks [n.]
Do not use as nouns.
Redbooks [adj.]
Always use this term as an adjective, capitalized, and in the plural form. At the first
occurrence, write "IBM Redbooks," as in "an IBM Redbooks publication." Thereafter,
you can use "Redbooks publication." Mark "Redbooks" and the IBM Redbooks logo with
the appropriate trademark. Note that the term "Redbook" is a registered trademark of
another company.
Redguide [n.]
Use to refer to an IBM Redguide publication.
Redpaper [n.]
Use as shown to refer to an IBM Redpaper publication.
Incorrect: red paper, redpaper
refer to [v.]
Use "see" instead of "refer to" both for references within a document and for cross-
references to other material.
refresh pack [n.]
Use initial uppercase letters only in a product name or in a reference to a specific
refresh pack number, such as "Refresh Pack 2." Otherwise, use lowercase.
reoccur (or re-occur) [v.]
Replace with "recur."
repair [v.]
Do not use to refer to making changes to code. Use "redesign."
requester [n.]
Not "requestor"
reside [v.]
Use "reside" to refer to someone's place of residence, not as a location for inanimate
objects.
Correct: "If you reside in the United States or Canada, you can contact IBM Support at
1-800-IBM-SERV."
Correct: "The application must be in the C:\Program Files directory."
Incorrect: "The application must reside in the C:\Program Files directory."
respective [adj.], respectively [adv.]
Do not use. Rewrite to avoid using this word to associate parts of a sentence.
Correct: "Use the FILEPATH option to specify fixed data from a file. Use
the DIRECTORYPATH option...,"
Incorrect: "Use the FILEPATH or DIRECTORYPATH option to specify fixed data from a file or
directory, respectively."
retry [v.]
Do not use "retry" as a verb. Use "try again."
Correct: "Try connecting to the server again."
Incorrect: "Retry connecting to the server."
reusable [adj.]
right adjust [v.]
Use to refer to shifting characters or digits to the right in a storage area.
right align [v.]
Use "right align," not "right justify," to refer to aligning text at the right margin.
Right Arrow key [n.]
right double-click [v.]
Replace with "double right-click."
right mouse button [n.]
Not "manipulation button" or "mouse button 2."
right-adjusted [adj.]
Use to refer to characters or digits that are shifted to the right in a storage area.
right-aligned [adj.]
Use "right-aligned," not "right-justified," to refer to text that is aligned at the right margin.
right-click [v.]
right-hand [adj.]
Replace with "right."
rightmost [adj.]
Use to refer to something farthest to the right (for example, on a page or a panel).
road map [n.]
roll forward [v.], roll-forward [adj.]
roll back [v.], rollback [n., adj.]
root [n., adj.]
For clarity, use "root" as an adjective in most cases. However, the term can be used as
a noun in some circumstances, such as in reference to a UNIX user account ID: "Log on
as root."
round-robin scheduling [n.]
rule of thumb [n.]
Replace with "rule."
rule set [n.]
runnable [adj.]
Correct: "runnable interface"
runtime [n., adj.]
S
(s)
No not use to indicate an optional plural. Use the plural.
sanity check [n.]
Do not use. Explain exactly what you mean. For example, use "test" or "evaluate."
Correct: "The quotes received from the vendors are checked to verify that the technical
solution matches the requested services."
Incorrect: "The quotes received from the vendors undergo a sanity check to establish
whether the technical solution matches the requested services."
scalable [adj.], scalability [n.]
schemas [n.]
Not "schemata"
screenshot [n.]
One word. The IBM terminology database advises against "screenshot," preferring
"screen capture" instead. But developerWorks editors prefer and will use "screenshot,"
because it's the more common term outside IBM.
scrum [n., adj.]
SDK [n.]
Abbreviation for "software development kit"; no need to spell out.
secondary storage [n.]
Replace with "auxiliary storage."
Secure Shell [n.]
Secure Sockets Layer (SSL) [n.]
select [v.]
In general, use the verb "click" to indicate an action using a mouse. For check boxes,
use "select" and "clear."
Correct: "Click OK."
Correct: "Select the Start check box."
selected [adj.]
Use to refer to a check box, radio button, menu item, or other interface element that is
marked or highlighted after selection.
Correct: "The Start check box is selected."
selection button [n.]
Replace with "left mouse button."
Semantic Web [n.]
serial database [n.]
Replace with "nonpartitioned database environment."
server side [n.], server-side [adj.]
serial database [n.]
Replace with "nonpartitioned database environment."
service-oriented architecture (SOA) [n.]
Use the article "an" with the abbreviation. (This suggests the pronunciation "S-O-A," not
the pronunciation "soah.")
set up [v.], setup [n., adj.]
shift-click [v.]
Replace with "press Shift and click."
ship [v.]
Do not use to indicate that something is included in or with a product. Use "include" or
"included."
Correct: "The feature is included with the product."
Incorrect: "The feature is shipped with the product."
Short Message Service (SMS) [n.]
shortcut [n., adj.]
should [v.]
Always prefer a more direct verb or way of saying something. Omit "should," or use
"must" or "might," as appropriate.
Correct: "Reset the parameters."
Incorrect: "You should reset the parameters."
shut down [v.], shutdown [n., adj.]
sign off [v.]
sign on [v.], sign-on [n. adj.]
sign on to [v.]
Not "sign onto"
Simple Object Access Protocol [n.]
Do not use. Replace with "SOAP."
simply [adv.]
since [prep.]
Use "since" only as a preposition to refer to elapsed time, not as a conjunction meaning
"because."
single quote, single quote mark [n.]
Replace with "single quotation mark."
single sign-on [n.]
sitewide [adj., adv.]
slave [n.]
Replace with "subordinate," unless you are using "slave" in the context of a UNIX
system (such as AIX), where "slave" is acceptable.
smart card [n.]
SME routine [n.]
Replace with "session management exit routine."
so [conj.]
Do not use by itself as a conjunction. Use a less ambiguous alternative such as "so
that" or "therefore."
SOAP [n.]
Do not spell out as "Simple Object Access Protocol."
socket interface [n.]
Not "sockets interface"
SOCKS-enabled [adj.]
soft boot [n.]
Do not use.
softcopy [n.]
Software as a Service (SaaS) [n., adj.]
solution [n.]
Use "solution" to describe a combination of products, software, services, or technology
that addresses a particular problem or project. The term "offering" refers to the general
hardware, software, or service elements, but "solution" refers to the application of an
offering in a specific customer environment by means of offering enabling services.
Solution Partnership Centers [n.]
Do not use. Replaced by IBM Innovation Centers for Business Partners.
some [adj.]
Use only to mean "fewer than all" or "less than all."
sort merge [n.], sort-merge [v.], sort/merge [v.]
Replace with the separate words "sort" and "merge."
spawn (a process) [v.]
Replace with "create."
Structured Query Language (SQL) [n., adj.]
Use the article "an" with the abbreviation. (This suggests the pronunciation S-Q-L,
rather than the more slang "sequel," which is the pronunciation often used with
Microsoft SQL Server.)
SQLJ [n.]
stand-alone [adj.]
start up [v.]
Replace with "start."
startup [n., adj.]
step-by-step [adj.]
stop [v.]
Use when referring to or in connection with hardware operations.
stop responding [v.]
Use when referring to or in connection with a program.
store [n.]
In most contexts requiring a noun, use "storage" instead of "store." In data warehousing,
the term "data store" is acceptable.
straightforward [adj.]
strike (a key) [v.]
Do not use to refer to pressing keys or typing on a keyboard. Replace with "press" or
"type."
stylesheet, stylesheets [n.]
sunset [v.]
Do not use. If possible, replace with a more specific term such as "withdraw from
service" or "withdraw from marketing." Otherwise, use a more general term such as
"discontinue" or "no longer support."
supersede [v.]
Not "supercede"
sync [v., adj.]
Not "synch"
sync point [n.]
Abbreviated form of "synchronization point."
system [n.]
Avoid if you can use a more specific term (such as "computer" or "operating system").
Use "system" to mean collectively the computer, its operating system, and its peripheral
devices.
system administrator [n.]
system analyst [n.]
Not "systems analyst"
system board [n.]
Not "motherboard," "planar," or "planar board"
system engineer [n.]
Not "systems engineer"
system programmer [n.]
Not "systems programmer"
systems management [n.]
Some existing product names might include the singular form "system management,"
but this term should usually be "systems management."
switch on [v.], switch off [v.]
Do not use in reference to hardware devices. Replace with "power on" or "turn on" and
"power off" or "turn off."
T
tab [v.]
Do not use as a verb to describe navigation in a GUI
table space [n.]
tap [v.]
Use to refer to selecting something on a handheld device.
tar [v.]
Do not use to refer to the creation of a tape archive (tar) file. Replace with a verb such
as "compress" or "archive."
tarball [n.]
Replace with "tar file."
target disk [n.]
Synonym for "destination disk."
target drive [n.]
Synonym for "destination drive."
target file [n.]
Synonym for "destination file."
taskbar [n.]
teamroom [n.]
Exception: "a Lotus Notes TeamRoom."
technology preview [n.]
Do not abbreviate as "tech preview."
telecommunication [n.]
Singular to refer to communication at a distance (for example, by telephone).
telecommunications [n.]
Plural to refer to the science of telecommunication.
Telnet [n.]
Correct: "Use Telnet to connect to the server."
Incorrect: "Telnet to the server."
terminal [n.]
Use only in a mainframe context. In other contexts, use "workstation" or "PC."
terminate [v.]
Replace with "end" or "stop."
test bed [n.]
test case [n.]
text field, text entry field [n.]
In most cases, use "field" (for example, "the User ID field"). Use a qualifier such as
"text" or "entry" only if necessary to distinguish between different types of fields for a
specific audience, such as programmers.
that [conj.]
Use "that," without a comma, to introduce a restrictive clause. Use "which," preceded by
a comma, to introduce a nonrestrictive clause.
Correct: The system units that have two drives are floor-standing models.
Incorrect: The system units, that have two drives, are floor-standing models.
themselves [n.]
then [adv.]
In a two-step procedure that is written as one sentence, punctuate "then" as shown in
the following two examples: (1) "Do this, and then do that." (2) "Do this; then do that."
The first example's style is preferable, but you can use the style shown in the second
example if you need to save space. Note that "then" is not a coordinating conjunction
(such as "and," "or," and "but"). Using "then" as a coordinating conjunction creates a
run-on sentence ("Do this, then do that."), which is incorrect.
there is, there are [v.]
Avoid at the beginning of an independent clause. In most cases rewrite to remove the
phrase.
Correct: "The product includes three recovery control data sets."
Incorrect: "There are three recovery control data sets in the product."
thin client [n.]; thin-client [adj.]
third party [n.], third-party [adj.]
this means
through [adj.]
Do not use as an adjective. Replace with "finished" or "completed."
through [prep.]
Do not use to mean "by using."
throw [v.]
Use only in Java documentation, as in "throw an exception." Otherwise, use an
alternative construction such as "produce an error."
throwable [adj.]
Use only with reference to Java exceptions. Do not use as a noun.
thru [prep.]
Replace with "through."
thumbstick [n.]
Replace with "USB flash drive."
thus [adv.]
Replace with "therefore."
time frame [n.]
time out [v.], timeout [n., adj.]
time slice [n.]
time stamp [n.]
Use "timestamp" only in a DB2 context.
time to value [n.], time-to-value [adj.]
time-tested [n.]
timeline [n.]
toggle off, toggle on [v.]
Replace with "toggle."
Correct: Toggle the switch to the off position.
token ring [n.], token-ring [adj.]
toolbar [n.]
toolbar button [n.]
Do not refer to a toolbar button as an "icon." In instructions, you can usually write
"Click X on the Y toolbar."
toolbox [n.]
tooling [n.]
Do not use to refer to a set of development tools associated with a product. Use the
simpler, more accurate term "tools." You can use "tooling" as an adjective to refer to
activities that tool makers perform, for example, "the Eclipse tooling platform."
toolkit [n.]
tooltip [n.]
Use "tooltip," not "hover help," to refer to a brief, plain text description that is displayed
when a cursor is moved over a graphical image, such as an icon, that does not
otherwise have a label. The term "hover help" refers to explanatory text, rich text, or
links that can be viewed by moving a cursor over a graphical user interface (GUI)
element, such as an icon, field, or text string.
top left, top right [n.], top-left, top-right [adj.]
Replace with "upper left," "upper right" [n.]; "upper-left", "upper-right" [adj.].
totaled [v.]
touch (a key) [v.]
Do not use to refer to using a keyboard key or hardware control. Use "press" or "type" to
refer to using keys on a keyboard, and use "press" to refer to a hardware control.
touchscreen [n.]
Replace with "touch-sensitive screen."
toward [prep.]
Not "towards"
trade-off [n.]
transition [v.]
Do not use as a verb. Replace with "make the transition," "move," "migrate," or
"change."
translate [v.], translation [n.]
Use to refer to language translation, such as from English to German. Do not use to
refer to the conversion of internal data to a different format; use "conversion."
transparent [adj.]
Replace with "indiscernible" or "not visible."
trillion [n.]
Do not use. Use numerals, not the word, because the value of a trillion is not the same
in all countries.
troubleshoot [v.]
truststore [n.]
twistie, twisty [n.]
Avoid in technical documentation, unless you need to specify the type of control being
referred to. In general, refer to the control by its label only. Use "expand" to refer to
clicking a twistie to display content. Use "collapse" to refer to clicking a twistie to hide
content (for example, "Expand Properties").
type [v.]
Use "type" or "enter" to refer to entering text in fields in a graphical interface. Use "type,"
"enter," or "issue" to refer to entering a command on a command line or at a command
prompt; use one term consistently throughout your information.
typically [adv.]
Use to mean "in a manner or circumstance that conforms to the characteristics of a type
or group" or "in typical circumstances." The definitions of "generally," "normally,"
"typically," and "usually" are similar, and in some cases, more than one of these terms
might be applicable. Use your judgment in deciding which term best applies.
Correct: "A hot-swap device typically has a handle that you can grasp to remove the
device from its bay."
typo [n.]
Replace with "typing error," "typographical error," or other similar wording.
U
UK [n., adj.]
Abbreviation of "United Kingdom."
unallocated [adj.]
Use to mean "not allocated" or "never allocated."
unblock [v.]
Not "deblock," except in CICS information.
uncheck [v.]
Do not use to refer to removing a mark from a check box. Use "clear."
uncomment [v.]
Use to describe the act of removing characters from the beginning of a line of code that
indicate that the line is not to be compiled.
uncompress [v.]
Replace with "decompress."
uncompressed [adj.]
Use "uncompressed" to refer to data that was not previously compressed. Use
"decompressed" to refer to data that was previously compressed.
unconfigure [v.]
Not "deconfigure"
undeploy [v.]
Replace with "remove" or "withdraw."
uninstall [v.]
Use when referring to or in connection with a program. Not "deinstall." Do not use as
an adjective or noun.
uninstallation [n., adj.]
Not "deinstallation"
UNIX [n., adj.]
unjar [v.]
Do not use to refer to the extraction of a Java archive (JAR) file. Replace with "extract."
unmount [v.]
Use "unmount" or "remove" only in reference a UNIX system, such as AIX. Otherwise,
use "demount."
unrecoverable [adj.]
Not "irrecoverable"
unregister [v.]
Not "deregister"
unselect [v.]
Do not use. Use "clear" to refer to removing a mark from a check box. Use "deselect" in
other situations.
untar [v.]
Do not use to refer to the extraction of a tape archive (tar) file. Replace with "extract."
unzip [v.]
Do not use "unzip" to refer to extracting or decompressing compressed data.
Use extract or decompress.
updatable [adj.]
Do not use. Rewrite the sentence.
Correct: "can be updated" or "can be changed"
upgradeable [adj.]
Not "upgradable"
upgrade [v.]
Do not use to mean "migrate" or "port." To migrate is to move data, users, or
applications to a new program, platform, or environment. Migration can occur between
unlike systems, for example, between two different vendors' databases, and migrating
usually involves more work than upgrading. To upgrade is to replace software with a
new release or fix level of the same program or to replace hardware with a newer model
or more powerful technology. An upgrade involves little work on the user's part.
To port is to move an application program from the operating system for which it was
developed to a different operating system. Porting requires less effort than
redevelopment.
upper left, upper right [n.]; upper-left, upper-right [adj.]
Not "top left" or "top right" to refer to the location of an item in an interface.
uppercase [adj.]
upward compatible [adj.]
Replace with "compatible with later versions."
URI [n.]
Abbreviation for "Uniform Resource Identifier"; no need to spell out.
URL [n.]
Abbreviation for "Uniform Resource Locator"; no need to spell out.
US [n., adj.]
Abbreviation of "United States."
usable [adj.]
Not "useable"
user-defined [adj.]
Correct: "user-defined data types"
user ID [n.]
Two words, uppercase "ID" unless used in code or commands (userid).
UI [n., adj.]
Abbreviation for "user interface"; no need to spell out.
user name [n.]
Two words unless used in code or commands (username).
userid [n.]
Use only in code or commands. Otherwise, use "user ID."
users [n.]
To be clear, address the readers as "you" and reserve "users" to mean their end users
whenever possible.
using [gerund]
To avoid ambiguity, replace with either "by using" or "that uses."
Correct: "Back up the server by using the installed software."
Correct: "Back up the server that uses the installed software."
Incorrect: "Back up the server using the installed software."
usually [adv.]
Use to mean "in a manner that can be expected" or "in most instances." The definitions
of "generally," "normally," "typically," and "usually" are similar, and in some cases, more
than one of these terms might be applicable. Use your judgment in deciding which term
best applies.
Correct: "The failure of a device is usually indicated by a lit system-error LED."
utilize [v.]
Replace with "use."
V
version [v.]
Do not use as a verb. Use a phrase such as "create a version" or "assign a version
number." Do not use "versioning."
versus [prep.]
Do not abbreviate as "vs." Spell it out or rewrite with equivalent wording such as
"compared to."
very [adj.]
via [prep.]
Acceptable as a synonym for "through" or "by means of." Avoid overuse. (Exception to
the IBM Style Guide.)
video conferencing [n.]
VMware [n.]
voice mail [n.]
vs. [prep.]
Do not use the abbreviation. Spell it out as "versus" or rewrite with equivalent wording
such as "compared to."
W
wait state [n.]
Not "wait condition"
WAR file [n.]
Correct: "Java packages often include WAR files."
.war file [n.]
Correct: "Open the .war file."
warning notice [n.]
Replace with "attention notice."
we [pron.]
Address readers as "you." Do not use "we" or "let's" as if author and reader were a
hybrid entity. Use first person only when there's no other way to say what you mean. If
an article has multiple authors who are describing something that they did together,
"we" can be appropriate in such instances.
web [n., adj.]
All lowercase unless part of a proper noun — such as "World Wide Web," "World
Wide Web Consortium," or "Semantic Web" — or in "Web 2.0."
web address [n.]
web browser [n.]
web client [n.]
web conference [n.]
web event, web-based event [n.]
web page [n.]
web seminar [n.]
web server [n.]
web service [n.]
Initial caps only if part of a proper noun such as "Amazon Web Services (AWS)" or
"Web Services Description Language (WSDL)."
web-enable [v.]
Do not use as a verb. Replace with "enable for the web."
web-enabled [adj.]
webcast [n.]
webinar, Webinar [n.]
Do not use. According to Norm Gundel, Senior IP Legal: "webinar" is a trademarked
word, owned by an individual and registered with the US Patent and Trademark Office
on April 18, 2000, Reg. #2342313. Instead, use "webcast" (preferred), "web seminar," or
"web-based event."
webmaster [n.]
Exception: If used as a job title immediately following a name, it gets an initial cap, as
in: Jane Doe, Webmaster.
website [n.]
where [conj.]
Use only in reference to physical location. Do not use to mean "when," "if," "provided
that," or "in which case."
whether or not [conj.]
Use "whether or not" only to mean "regardless of whether" (for example, "Log shunting
runs whether or not log archiving is enabled"). Otherwise, use "whether."
which [pron.]
Use "which", preceded by a comma, to introduce a nonrestrictive clause. Use "that",
without a comma, to introduce a restrictive clause.
Correct: The system units, which have two drives installed, are floor-standing models.
Incorrect: The system units which have two drives installed are floor-standing models.
while [conj.]
Use only to refer to a period of time. Do not use the term as a synonym for "although" or
"though."
white paper [n.]
white space [n.]
Two words, except in reference to programming languages that use "whitespace" as
one word.
WiFi [n., adj.]
wildcard [n., adj.]
Windows 32-bit operating system [n.]
Not "32-bit Windows operating system"
wish [v.]
Replace with "want."
wizard [n.]
workaround [n.]
workflow [n.]
workgroup [n.]
workload [n.]
workspace [n.]
workstation [n.]
World Wide Web [n.]
World Wide Web Consortium (W3C) [n.]
worldwide [adj., adv.]
would [v.]
Use only to refer to an unfulfilled condition or hypothesis and to express the future in the
past.
Correct: "The command was rejected because it would have resulted in
the ClusterName attribute being blank."
Incorrect: "You would need administrator authority to..."
X
X Window System [n.]
Not "X-Windows" or "X-Window System"
XML Parser for Java (XML4J) [n.]
XSL stylesheets [n.]
Z
zero out [v.]
Do not use. Use "zero" to refer to resetting to zero.
zeros [n.]
Not "zeroes"
zip [v.]
Do not use "zip" to mean to compress files with a compression utility. Use "compress,"
which applies to a variety of formats and utilities.
ZIP file [n.]
Correct: "Java packages often include ZIP files."
.zip file [n.]
Correct: "Open the .zip file."
Resources
General advice about writing
For advice on appealing to readers on the web, browse the most recent and most
popular Jakob Nielsen articles.
For general inspiration, see Elements of Style by William Strunk, Jr.
General style issues

When this document does not answer your questions, refer to the IBM Style Guide. If
you still have questions, see The Chicago Manual of Style for exhaustive guidance.
In the definitive guide Developing Quality Technical Information: A Handbook for Writers
and Editors, Second Edition, find extensive before-and-after examples, illustrations, and
checklists and tips on simplifying search, improving retrievability, applying
internationalization, and boosting visual effectiveness.
Terminology
Find Java-specific words in the Java concepts and definitions glossary. For
nontechnical words, search the IBM dictionary of choice, Merriam-Webster.
Trademark and copyright information

The IBM copyright and trademark information lists IBM products and the correct
trademark attributions.

IBM DeveloperWorks Editorial Style Guide For Technical Writing

Hochgeladen von

Dokumentinformationen

Originaltitel

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

IBM DeveloperWorks Editorial Style Guide For Technical Writing

Hochgeladen von

Copyright:

Verfügbare Formate

IBM developerWorks editorial style guide

Published on May 31, 2014

A modern editorial style

Rich article guidelines

Abbreviations, acronyms, and initialisms

bits per second bps

The code for the degree symbol

Abbreviate in tables and

Abbreviate only in tables and

Binary thousand — 1024; used

Metric thousand — 1000; used

Binary million (1,048,576); used

ohm ohm Do not abbreviate. Plural: ohms

Spell out percent when used in

Abbreviations for longer units of time

Otherwise, follow this commonsense rule: If in doubt, do not capitalize.

Captions for figures, tables, and code listings

GUI elements: Terminology and usage

Highlighting and formatting

Some general rules apply:

• Use bold (<strong>):

API name No highlighting search API

Attribute ALT attribute on

Select the <strong>Set as

The <em>Java theory and

Containers No highlighting Java container

Currency Use international format. USD100 or US$100

Dates Use international format. 21 April 2014 or April 2014

Strong emphasis. For

Add the new directory to the

Field name Bold <strong>User ID</strong>

File name No highlighting sample.zip

<Inline code and anchor Surround your paragraphs

"Irony" Quotes There is no "right" solution.

Do not change the

Letters, if Type <strong>R</strong> to

One through nine: Spell out.

The default parameter for

No highlighting. In some common systems

Storage save the file in the file

After you finish the

Use the list utility to create a

View name No highlighting Check the Log view.

Window or The Installation options

Follow these guidelines for both ordered and unordered lists:

• Do not abbreviate any IBM product name. If an abbreviation is legally registered as a

First time: IBM Mobile Analytics for Bluemix

First time: IBM Cloudant NoSQL Database for Bluemix

See the Bluemix catalog for service names.

Titles, series titles, and subtitles

Downloads (other than product trials)

General style issues

Trademark and copyright information

Das könnte Ihnen auch gefallen