Deployment wiki writing guidelines

These minimal writing guidelines are listed in alphabetical order and focus on style issues that relate to clarity and consistency within a wiki page. The links to further guidelines lead to internal information that is available to IBM employees only.

For detailed information about how to create wiki pages and how to complete and format the different sections of wiki pages, see Deployment wiki formatting guidance.

Abbreviations

• For all abbreviations that might not be known by the audience, spell out the abbreviation at the first instance on the page and include the abbreviation in parentheses after it.

• Remember that not all spelled-out forms of abbreviations use initial capital letters (if you are unsure, your UA contacts can advise on this matter).
  
  Correct: Interactive System Productivity Facility (ISPF)
  Correct: service-oriented architecture (SOA)
  Correct: Rational solution for Collaborative Lifecycle Management (CLM)

• IBM authors and editors can find more information about abbreviations in IBM Style: Abbreviations.

Capitalization

• Applying a uniform style of capitalization helps information look consistent and unified from a high level.

• Use a lowercase style, which is known as "sentence-style" capitalization.

• In sentence-style capitalization, you capitalize only the first word in a title, heading, or subheading (and any other words that must be capitalized, such as proper nouns).
  
  Incorrect: Installing, Upgrading, and Migrating
  Correct: Installing, upgrading, and migrating

• IBM authors and editors can find more information about capitalization in IBM Style: Capitalization.

Do-not-use terms

• Do not use the terms in the following list, which can make unsubstantiated claims or violate copyrights.
  
  future-proof
  guarantee
  I
  recommend, recommended
  unzip, unzipped: Use "extract" or "extracted."
  us
  we
  zip, zip file, zipped file, ZIP, .ZIP: Use ".zip file" or "compress" or "compressed file."

• IBM authors and editors can find more information about do-not-use terms in IBM Word Usage.

First person

• Do not use the first person, which is indicated by the personal pronouns I, me, my, we, us, and our.

• The first person can cause confusion over whether the writing represents an individual, group, or company and can also cause liability issues.

• Instead, focus the information on the user and use the imperative mood or the second person, which is indicated by the personal pronoun you.
  
  Incorrect: We can start by considering the deployment scenario.
  Correct: Start by considering the deployment scenario.
  Correct: You can start by considering the deployment scenario.

• IBM authors and editors can find more information about the first person in IBM Style: Pronouns and IBM Style: Verbs.

Product names

• For legal, branding, and clarity reasons, spell out all product names in external information.

• Do not abbreviate product names.
  
  Incorrect: JTS, RTC, WAS
  Correct: Jazz Team Server, Rational Team Concert, WebSphere Application Server
  Exception: For Collaborative Lifecycle Management (CLM), you must spell out the first instance, but you can use CLM thereafter.

• IBM authors and editors can find more information about referring to CLM in Referring to CLM and its applications.

Spelling

• Use American spelling, and refer to Merriam-Webster as a default dictionary.

• Use the preferred spelling of these common words:
  
  Deployment wiki
  email
  IBM Knowledge Center
  information center
  internet
  Jazz.net
  online
  web

• IBM authors and editors can find more information about preferred spellings in IBM Style: Spelling, or the IBM Word Usage database.

Related topics:

• Deployment wiki formatting guidance
• Deployment wiki roles and responsibilities

External links:

• Merriam-Webster online dictionary
• IBM Style (Available to IBM employees only)
• IBM Word Usage (Available to IBM employees only)

Additional contributors: LauraHinson, RalphEarle