Best Practice in Writing

Keep it Clear

• Use headings and subheadings to make the topic apparent

• Outline the content in a short introductory paragraph

• Use timely and accurate content

Keep it Concise

• Use bullets rather than paragraphs

• Use boldface to highlight your main points

• Break large amounts of information into smaller pages that link to one another

Make it Compelling

• Write clear, simple, and straightforward text

• Use the active voice

• Keep paragraphs short

Make it Correct

• Check grammar and spelling

• Write in the language of your audience

• Keep hyperlinks up-to-date

[@more@]Write so your reader will understand and act quickly.

Do not write to show your profound grasp of complex concepts and terminology.

Use simple words and sentences.

Examples: use "did" not "accomplished"; use "improve" not "ameliorate"; use "require" not "necessitate".

Use specific, concrete words.

Example: "Meet in 10UB at noon" not "Meet in the room near the elevator on the third floor of building 10 at lunchtime."

Avoid clichés, idioms, and slang.

Example: "In technical writing, avoid humor like the plague." (cliché)

Limit jargon

Examples: use "print" not "generate output"; use "find the word"not "locate the search string".

Define all acronyms and spell out abbreviations in first use.

Example: "TLA (Three-Letter Acronym)."

Do not use apostrophes(') in the plurals of word forms or acronyms.

Example: PCs, GMs.

Do not use Latin abbreviations.

Example: use "and so forth" not "etc.," use "that is" not "i.e."

Avoid any suggestion of humor that is based on age, culture, nationality, politics, race, religion, or sex.

Humor does not translate well, and some readers may find it confusing or offensive.