DeploymentWritingGuidelines < Deployment

Engineering Lifecycle Management Wiki - Deployment
Community information and contribution guidelines
TWiki > Deployment Web > DeploymentWritingGuidelines
Revision 17 - 2017-06-07 - 21:45:24 - Main.aalaird
<div id="header-title" style="padding: 10px 15px; border-width:1px; border-style:solid; border-color:#FFD28C; background-image: url(<nop>https://jazz.net/wiki/pub/Deployment/WebPreferences/TLASE.jpg); background-size: cover; font-size:120%">
---+!! Deployment wiki writing guidelines
%DKGRAY% Authors: Main.AmyLaird, Main.StevenBeard <br>
Build Basis: None
%ENDCOLOR%</div></sticky>

<!-- Page contents top of page on right hand side in box -->
<sticky><div style="float:right; border-width:1px; border-style:solid; border-color:#DFDFDF; background-color:#F6F6F6; margin:0 0 15px 15px; padding: 0 15px 0 15px;">
%TOC{title="Page contents"}%
</div></sticky>

<sticky><div style="margin:15px;"></sticky>

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 [[DeploymentFormattingGuidance][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). <br /> <br /> *Correct:* Interactive System Productivity Facility (ISPF) <br /> *Correct:* service-oriented architecture (SOA) <br /> *Correct:* Rational solution for Collaborative Lifecycle Management (CLM)

   * IBM authors and editors can find more information about abbreviations in <a target="_blank" href="https://apps.na.collabserv.com/wikis/home?lang=en-us#!/wiki/W580a84a67242_4da6_81cf_69e3db4bdbfa/page/Abbreviations">IBM Style: Abbreviations</a>.

---++ 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). <br /> <br /> *Incorrect:* Installing, Upgrading, and Migrating <br /> *Correct:* Installing, upgrading, and migrating

   * IBM authors and editors can find more information about capitalization in <a target="_blank" href="https://apps.na.collabserv.com/wikis/home?lang=en-us#!/wiki/W580a84a67242_4da6_81cf_69e3db4bdbfa/page/Capitalization">IBM Style: Capitalization</a>.

---++ Do-not-use terms

   * Do not use the terms in the following list, which can make unsubstantiated claims or violate copyrights. <br /> <br /><a target="_blank" href="https://apps.na.collabserv.com/wikis/home?lang=en-us#!/wiki/W580a84a67242_4da6_81cf_69e3db4bdbfa/page/Word%20usage?section=future-proof">future-proof</a> <br /><a target="_blank" href="https://apps.na.collabserv.com/wikis/home?lang=en-us#!/wiki/W580a84a67242_4da6_81cf_69e3db4bdbfa/page/Word%20usage?section=guarantee">guarantee</a><br /> <a target="_blank" href="https://apps.na.collabserv.com/wikis/home?lang=en-us#!/wiki/W580a84a67242_4da6_81cf_69e3db4bdbfa/page/Word%20usage?section=I">I</a><br /> <a target="_blank" href="https://apps.na.collabserv.com/wikis/home?lang=en-us#!/wiki/W580a84a67242_4da6_81cf_69e3db4bdbfa/page/Word%20usage?section=recommend">recommend, recommended</a><br /> <a target="_blank" href="https://apps.na.collabserv.com/wikis/home?lang=en-us#!/wiki/W580a84a67242_4da6_81cf_69e3db4bdbfa/page/Word%20usage?section=unzip">unzip, unzipped</a>: Use "extract" or "extracted."<br /> <a target="_blank" href="https://apps.na.collabserv.com/wikis/home?lang=en-us#!/wiki/W580a84a67242_4da6_81cf_69e3db4bdbfa/page/Word%20usage?section=us">us</a><br /> <a target="_blank" href="https://apps.na.collabserv.com/wikis/home?lang=en-us#!/wiki/W580a84a67242_4da6_81cf_69e3db4bdbfa/page/Word%20usage?section=we">we</a><br /> <a target="_blank" href="https://apps.na.collabserv.com/wikis/home?lang=en-us#!/wiki/W580a84a67242_4da6_81cf_69e3db4bdbfa/page/Word%20usage?section=zip">zip</a>, <a target="_blank" href="https://apps.na.collabserv.com/wikis/home?lang=en-us#!/wiki/W580a84a67242_4da6_81cf_69e3db4bdbfa/page/Word%20usage?section=zip%20file%2C%20zipped%20file">zip file, zipped file</a>, ZIP, .ZIP: Use ".zip file" or "compress" or "compressed file."

   * IBM authors and editors can find more information about do-not-use terms in <a target="_blank" href="https://apps.na.collabserv.com/wikis/home?lang=en-us#!/wiki/W580a84a67242_4da6_81cf_69e3db4bdbfa/page/Word%20usage">IBM Word Usage</a>.

---++ 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._ <br /> <br /> *Incorrect:* We can start by considering the deployment scenario. <br /> *Correct:* Start by considering the deployment scenario. <br /> *Correct:* You can start by considering the deployment scenario.

   * IBM authors and editors can find more information about the first person in <a target="_blank" href="https://apps.na.collabserv.com/wikis/home?lang=en-us#!/wiki/W580a84a67242_4da6_81cf_69e3db4bdbfa/page/Pronouns">IBM Style: Pronouns</a> and <a target="_blank" href="https://apps.na.collabserv.com/wikis/home?lang=en-us#!/wiki/W580a84a67242_4da6_81cf_69e3db4bdbfa/page/Verbs">IBM Style: Verbs</a>.

---++ Product names

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

   * Do not abbreviate product names. <br /> <br /> *Incorrect:* JTS, RTC, WAS <br /> *Correct:* Jazz Team Server, Rational Team Concert, !WebSphere Application Server<br /> *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 <a target="_blank" href="https://w3-connections.ibm.com/wikis/home?lang=en#%21/wiki/Wf609f4b2dd8e_434c_a665_d0f8a95a390a/page/Referring%20to%20CLM%20and%20its%20applications">Referring to CLM and its applications</a>.

---++ Spelling

   * Use American spelling, and refer to <a target="_blank" href="http://www.merriam-webster.com/">Merriam-Webster</a> as a default dictionary.

   * Use the preferred spelling of these common words: <br /> <br /> Deployment wiki <br /> email <br /> IBM Knowledge Center <br /> information center <br /> internet <br /> Jazz.net <br /> online <br /> web

   * IBM authors and editors can find more information about preferred spellings in <a target="_blank" href="https://apps.na.collabserv.com/wikis/home?lang=en-us#!/wiki/W580a84a67242_4da6_81cf_69e3db4bdbfa/page/Spelling">IBM Style: Spelling</a>, or the <a target="_blank" href="https://apps.na.collabserv.com/wikis/home?lang=en-us#!/wiki/W580a84a67242_4da6_81cf_69e3db4bdbfa/page/Word%20usage">IBM Word Usage database</a>. 

---+++++!! Related topics: 
   * [[DeploymentFormattingGuidance][Deployment wiki formatting guidance]]
   * [[DeploymentRolesAndResponsibilities][Deployment wiki roles and responsibilities]]
   
---+++++!! External links:
   * <a target="_blank" href="http://www.merriam-webster.com/">Merriam-Webster online dictionary</a>
   * <a target="_blank" href="https://apps.na.collabserv.com/wikis/home?lang=en-us#!/wiki/W580a84a67242_4da6_81cf_69e3db4bdbfa/page/IBM%20Style">IBM Style</a> (Available to IBM employees only)
   * <a target="_blank" href="https://apps.na.collabserv.com/wikis/home?lang=en-us#!/wiki/W580a84a67242_4da6_81cf_69e3db4bdbfa/page/Word%20usage">IBM Word Usage</a> (Available to IBM employees only)

---+++++!! Additional contributors: LauraHinson, RalphEarle

<sticky></div></sticky>
Copyright © 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.