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