r17 - 2017-06-07 - 21:45:24 - Main.aalairdYou are here: TWiki >  Deployment Web > DeploymentWritingGuidelines

Deployment wiki writing guidelines

Authors: AmyLaird, StevenBeard
Build Basis: None

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)

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

Do-not-use terms

  • 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.

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.

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

Related topics:

External links:

Additional contributors: LauraHinson, RalphEarle

Edit | Attach | Printable | Raw View | Backlinks: Web, All Webs | History: r17 < r16 < r15 < r14 < r13 | More topic actions
 
This site is powered by the TWiki collaboration platformCopyright © by IBM and non-IBM contributing authors. All material on this collaboration platform is the property of the contributing authors.
Contributions are governed by our Terms of Use. Please read the following disclaimer.
Dashboards and work items are no longer publicly available, so some links may be invalid. We now provide similar information through other means. Learn more here.