GitHubContribute in GitHub: Open doc issue|Edit online

IBM Style

Content Standards

Introduction

Style is the correctness and appropriateness of writing according to conventions. "The best style is the style you don't notice." — W. Somerset Maugham

IBM Style Guide

IBM Style contains the corporate writing guidelines for all IBM content that is created for an external audience.

You can find it on IBM Documentation here: IBM Style Guide

  • Grammatically correct
  • Clear
  • Consistent
  • Appropriate for global audiences
  • Easy to translate

Style and content

Like visual effectiveness, style is an expression of the "look and feel" of information. Maintaining a style for technical content means following standards and rules to ensure consistency and correctness.

Style and content are inextricably linked: consistent style helps users focus on the content and not on why one term is highlighted in bold in one place but  not another. However, style isn't simply decoration that you apply to information—style helps users understand the information.

Generally, editors create style guidelines for the organization to ensure consistency across sets of information or across product interfaces. Style guidelines help writers create consistent information by providing quick answers to questions about highlighting, formatting, spelling, punctuation, tone, and markup language tagging. Not only does this consistency lend credibility and instill a sense of corporate identity to a company's content, it also helps teams, writers, and organizations deliver content that users expect from a product or line of products.

Many organizations also use specific templates, document type definitions (DTDs) for markup languages, reusable software code for user interfaces, cascading style sheets (CSSs), or Extensible Stylesheet Language (XSL) to structure and format various types of content. Templates and consistent tagging help ensure that content has consistent appearance, organization, and required standard information, such as prerequisites in task topics.

Style entails making choices about tone, voice, cultural references, terminology, and presentation. To make information stylistically appropriate, correct, and consistent, follow these guidelines:

  • Use active and passive voice appropriately
  • Convey the right tone
  • Avoid gender and cultural bias
  • Spell terms consistently and correctly
  • Use proper capitalization
  • Use consistent and correct punctuation
  • Apply consistent highlighting
  • Make elements parallel
  • Apply templates and reuse commonly used expressions
  • Use consistent markup tagging

Consistent and appropriate

A consistent and appropriate style helps users understand information. Effective style is transparent and doesn't hinder users' understanding of the information. Users notice style only when highlighting and formatting is inconsistent; when the tone is inappropriate; when punctuation, capitalization, or spelling is incorrect; or when templates are not applied properly. When  users pay attention to the style, they probably don't pay attention to the meaning of the information.

You can use the following checklist in two ways:

  • As a reminder of what to look for, to ensure a thorough review
  • As an evaluation tool, to determine the quality of the information
Guidelines for style Items to look for Quality Rating
1=very dissatisfied
5=very satisfied
Use active and passive voice appropriately
  • Active voice is used in most cases.
  • Passive voice is used only when the actor or agent isn't known or isn't important.
  • Passive voice is used in messages to avoid blaming the user.
 1 2 3 4 5
Convey the right tone
  • The tone for formal information is helpful, direct, and authoritative.
  • The content is free from a pretentious tone.
  • Content that uses a friendly, humorous, or informal tone is helpful but not sarcastic or patronizing.
  • If idioms or slang is used, the information is tested and checked periodically to ensure that the text is not dated or inappropriate.
 1 2 3 4 5
Avoid  gender and cultural bias
  • Sample names, phone numbers,  email addresses, and other sample data are appropriate for an international audience.
  • References to gender, occupation, or position are free from bias.
 1 2 3 4 5
Spell terms consistently
  • Technical terms are spelled only one way.
  • Terms with prefixes and suffixes are spelled correctly.
  • Terms that are trademarks are never changed, such as by adding a prefix or 's.
  • If you author in English, terms with variable spellings, such as with British and US English spellings, are spelled in only one way.
  • Commonly confused terms such as affect and effect are used and spelled correctly.
 1 2 3 4 5
Use proper capitalization
  • Technical terms use consistent case.
  • Technical terms aren't unnecessarily capitalized.
  • User interface controls are correctly capitalized.
 1 2 3 4 5
Use consistent and correct punctuation.
  • Punctuation is used correctly and consistently.
  • Guidelines are established and followed for controversial punctuation such as the serial comma and the use of quotation marks with periods and commas.
 1 2 3 4 5
Apply consistent highlighting
  • Style and highlighting of items such as button labels, hover help text, windows, and messages are consistent in user interfaces.
  • Commands, check boxes, labels, file names, headings, titles, and other elements are highlighted correctly in the documentation according to the style guide.
  • Lists are short and parallel, consistently punctuated, include at least two items, and aren't nested beyond two levels.
 1 2 3 4 5
Apply template designs  and reuse commonly used expressions
  • Templates are used appropriately and consistently for information such as task, concept, and reference topics.
  • Common expressions are reused when possible.
 1 2 3 4 5
Use consistent markup tagging
  • Markup language tagging is correct and consistent according to the style guide.
  • Structured elements are semantically correct and not applied simply for appearance in output.

Word usage and terminology

IBM Style Guide includes details on word usage exactly which words and spellings to use and avoid in all types of IBM content for external audiences.

Inclusive language

In concert with IBM's Emb(race) movement to combat racial inequality, the IBM Academy of Technology launched an internal initiative to identify and replace IT terminology that promotes racial and cultural bias. Our goal is to promote the use of inclusive language in IT and provide opportunities for IBM employees to work together to achieve this goal.

Change takes time and effort. Our initiative is an ongoing endeavor that will continue to expand and accelerate across the technology industry. We stand with and in support of the Black community both within and outside of IBM, and we strive to create a more inclusive technology landscape.

To learn more about our mission, read the blog on IBM.com and listen to the podcast about this initiative.

For more information about how you can take action with inclusive language check out Inclusive IT Terminology (Internal).

Resources

Additional style resources are available: IBM Style Guide - Related resources