Contents


developerWorks editorial style guide

Comments

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:
    • The system performs the action.
    • It is more appropriate to focus on the receiver of the action.
    • You want to avoid blaming the user for an error, such as in an error message.
    • 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.
  • 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 measurementAbbreviationNotes
ampereA
bitb
bits per secondbps
British thermal unitBtuPlural: Btus
byteB
centimetercm
decibeldB
degree°The code for the degree symbol is °. Indicate Fahrenheit or Celsius: 32°F, 10°C
foot, feetft Abbreviate in tables and graphics only. Spell out when used in a sentence.
gramg
gigabitGb
gigabits per secondGbps
gigabyteGB
gigabytes per secondGBps
gigahertzGHz
hertzHz
inch, inchesin. Abbreviate only in tables and graphics, and use the ending period. Spell out when used in a sentence.
kiloKBinary thousand — 1024; used for memory
kMetric thousand — 1000; used for transmission speeds
kilobitKb
kilobits per secondkbps
kilobyteKB
kilobytes per secondkBps
kilogramkg
kilohertzkHz
kilometerkm
kilowattkW
megaMBinary million (1,048,576); used for memory megabit Mb
megabits per secondMbps
megabyteMB
megabytes per secondMBps
megahertzMHz
meterm
milligrammg
millimetermm
millions of instructions per secondmips
millions of packets per secondmpps
millisecondms
milliwattmW
nanon
nanometernm
nanosecondns
ohmohmDo not abbreviate. Plural: ohms
packets per secondpps
percent% Spell out percent when used in a sentence. Use the % symbol only in tables and graphics.
poundlb
rack unitRU
rotations per minuterpm
terabitTb
terabits per secondTbps
terabyteTB
terabytes per secondTBps
voltV
wattW

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 (<strong>):
    • 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 (<em>):
    • 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:

Elements that should be highlighted are listed in Table 2 with the recommended formatting.

Table 2. Recommended highlighting
Highlighted elementRecommended highlightingExample of XML coding
API nameNo highlightingsearch API
"Article title"Quotes"Introduction to Android development"
Attribute nameInline codeALT attribute on the figure tag
Book titleEmphasis<em>AI Application Programming</em>
Button (or key) name, hardwareNo highlightingPress Enter
Button name, softwareBoldClick <strong>Next</strong>
CheckboxBoldSelect the <strong>Set as default</strong> checkbox
ClassInline code<code>Command</code> class
Code listing
Code listing
Code listing
Code listing
<code-listing>
<pre>
    struct my_data_structure {
    int value;
    struct list_head list;
    };
</pre>
</code-listing>
Code string in a sentenceInline code<code>my_hrtimer_callback</code>
Column or series nameEmphasisThe <em>Java theory and practice</em> series on developerWorks
Command nameInline code<code>Print</code> command
ContainersNo highlightingJava container
CurrencyUse international format.USD100 or US$100
DatesUse international format. 21 April 2014 or April 2014
Dialog nameBoldOpen the <strong>Browse</strong> dialog to select a file
Directory nameNo highlightingGo to /developerworks/downloads/index.html.
EmphasisStrong emphasis. For example: "The maximum code line length is 105 characters."The maximum code line length is <strong>105 characters</strong>.
Environment variablesInline codeAdd the new directory to the <code>CLASSPATH</code> environment variable
Field nameBold<strong>User ID</strong>
File nameNo highlightingsample.zip
GUI elements (tabs, menu choices, menu names, controls)Strong emphasis. For example: "Click Options > Preferences."Click <strong>Options</strong> > <strong>Preferences</strong>.
HTML elementInline code<code>title</code> element
HTML tags<Inline code and anchor brackets>Surround your paragraphs with the <code>p</code> tag.
Icon nameBoldClick the <strong>Back</strong> icon.
"Irony"QuotesThere is no "right" solution.
Key nameInline codeDo not change the <code>HKEY_CURRENT_USER</code> registry key
KeywordInline code<code>cloud</code> keyword
Labels (Tip, Note)Bold<strong>Note:</strong> Skip this step if the software is already installed.
Letters, if only oneBoldType <strong>R</strong> to re-run the command.
List boxesBoldSelect <strong>File</strong> from the drop-down box.
MacroInline code<code>LIST_HEAD</code> macro
Magazine titleEmphasis<em>Linux Magazine</em>
Message text or prompt addressed to the userInline code<code>The queue was created successfully</code>
MethodInline code<code>execute()</code> method
NumbersNo highlightingOne through nine: Spell out.
10 and greater: Use numerals.
ObjectInline code<code>Zend_Service_Amazon_Sqs</code> object
ParametersInline codeThe default parameter for <strong>User ID</strong> is <strong>websphere</strong>.
Path name or directoryNo highlightingC:\jdk1.6.0_18
Pattern nameNo highlighting. In some contexts, patterns are capitalized.common systems architecture pattern for public sector organizations
Storage areasNo highlightingsave the file in the file storage area
Table title or name, reference in textNo highlightingCheck the database names table for the value
Tags in markup languages<Inline code with anchor brackets>Use the <code>figure</code> tag to set off images.
TasksNo highlightingAfter you finish the configuration task
Terms defined in contextEmphasis<em>timer wheel</em>
Type (such as int or long)Inline code<code>int</code> type
URL in textNo highlightingwww.ibm.com/developerworks/
UtilitiesNo highlightingUse the list utility to create a set of items.
Values for arguments or commandsInline codeType <code>none</code> to specify no backup.
Placeholders within commands and codeEmphasis<em>your-file</em>
View nameNo highlightingCheck the Log view.
Website nameNo highlightingThe developerWorks website
Window or panel nameNo highlightingThe Installation options window
<XML tags or portions> <Inline code with anchor brackets><code>heading</code> 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:
    • WSAD
    • 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®)
      Thereafter: RUP
    • First use: IBM® Rational® Method Composer
      Thereafter: Rational Method Composer
      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:
    • "Writing code is fun."
    • "I shortened the code to five lines, reducing it by half."
    • "I shortened the code by using a different algorithm."

    Example of usage to avoid: "I shortened the code using a different algorithm."

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:
    • Include the part number in the series title. Example: "An introduction to Apache ZooKeeper, Part 1."
    • 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.
    • 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.

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:
    • Other developerWorks articles in the same series, on the same topic, or by the current article's author.
    • Documentation related to the article content.
    • A related topical aggregation page or a custom library view on developerWorks.
    • 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.

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.]
Do not use as a noun.
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 the IBM 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.]
Do not use as a noun.
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.]
Do not use as a verb.
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.]
Do not use as a noun.

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.]
For generic references, use uppercase and a noun.
Correct: "Java packages often include JAR files."

.jar file [n.]
For specific references, use a dot, lowercase, and a noun.
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.]
Do not use as a verb.

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.]
Do not use as a noun.
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.]
Do not use as a noun.

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.]
Do not use as a verb.
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.]
Do not use as a verb.

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.]
For generic references, use uppercase and a noun.
Correct: "Java packages often include WAR files."

.war file [n.]
For specific references, use a dot, lowercase, and a noun.
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.]
Do not use as a verb.

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.]
For generic references, use uppercase and a noun.
Correct: "Java packages often include ZIP files."

.zip file [n.]
For specific references, use a dot, lowercase, and a noun.
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.


Downloadable resources


Comments

Sign in or register to add and subscribe to comments.

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=
ArticleID=975466
ArticleTitle=developerWorks editorial style guide
publish-date=05312014