Clarity

 

"Everything that can be thought at all can be thought clearly. Everything that can be said can be said clearly."

    - Ludwig Wittgenstein

In order to write clearly, set your thoughts in order. What do you want to say? What content organization will help say it most clearly? Review your outline, and revise it, before you begin writing.

One technical writing problem is the poor quality of existing documents that you have to work from. Arcane terminology, circular definitions, unfamiliar acronyms, and missing instructions drag writers and users through a realm of technobabble.

Another problem is jargon. Jargon is verbal shorthand used by people who are conversant with a subject. But if you are new to the field, jargon is a major obstacle. Itís an even bigger problem if you are not fluent in English. Learning software is hard enough without wading through a quagmire of acronyms in an unfamiliar language.

Marketing catch phrases poison instructional communication, bloat your text, and do not age well. Users remember less and perform worse after viewing technical content that contained marketing phrases. The implication was that users mentally argued with the marketing message, distracting from the instructional content.

  Check List

  • Speak in the vernacular. Avoid using jargon and acronyms.
  • Define your terms as you use them. If the help file has a vague or circular definition, improve it for your project.
  • Avoid using jargon. Because you hear it at work does not mean others understand it.
  • Avoid acronyms. They are harder to decode than jargon.
  • Do not use marketing buzzwords such as, "seamless," "revolutionary," "intuitive," "robust" and "powerful."
  • Discard euphemisms and hype. Say exactly what you mean.
  • Avoid ambiguous words that have other non-technical meanings like, "boot," "bundle," "enter," "execute," "mount," and "string."
  • Be specific . Use the most specific term that applies. A dwelling is more specific than a building, but a hovel, a hut or a house is even more specific.
  • Use concrete words . Use words that you can see, touch, hear, taste, and smell. Avoid abstractions such as, "prioritization" and "implementation."
  • Use concrete analogies that are familiar to your audience.
  • Use standard English. If a word or phrase doesnít show up in the dictionary, do not use it in your text.
  • Find the best word. Look up synonyms and definitions.