Writing Style

Applications should use a conversational tone and should not include excessive technical jargon.

Here are some things we recommend you consider when writing for applications:

Dos

  • Use simple, yet complete sentences.
  • Use correct punctuation.
  • Use the present tense to describe problem states.
  • Use past tense to describe events that occurred in the past.
  • Use an active voice whenever possible.
  • Passive voice is acceptable to describe some error conditions.
  • Use descriptors to clarify terminology. For example, “Specify InflD when Detect is set to NO.” We instead recommend something along the lines of “Specify the InflD parameter when the Detect option is set to NO”.

Don’ts

  • Do not use UPPERCASE in text or exclamation points!!!!
  • Do not make the user feel at fault.
  • Do not anthropomorphize by implying that the programs or hardware can think or feel.
  • Do not use colloquial words or phrases.
  • Do not use terms that may be offensive in certain cultures.
  • Do not compound several nouns without adding a preposition or subclause to clarify the meaning. For example, “Site Server LDAP Service directory server” should be changed to “Directory server for the LDAP Service of the Site Server”.
  • Avoid the use of the word “bad”. Use more descriptive terms to tell the user as to what is wrong. For example, avoid messages such as “Bad size”. Instead, tell the user what criteria to use when specifying a size.
  • Avoid the use of the word “please”. It can imply that a required action is optional.