PRINCIPLES

 

"Say all you have to say in the fewest possible words, or your reader will be sure to skip them; and in the plainest possible words or he will certainly misunderstand them."

- Derek Bok

Write in a plain style; simple, clear, energetic, and sincere. It establishes your expertise and assures readers that you are an expert.

Write truthfully and honestly. Know your audience and give them what they need. Let users know that you are there to help them. Go that extra mile to explain things clearly.

Know Your Subject

Master the subject you are writing about. Read help files, white papers, trade books, and documentation. Take nothing for granted. Try all the commands, change all the parameters, and run all the spinners. Research and ask questions if you cannot figure something out. If you canít figure it out, how can the user?

Revise, Revise, Revise

Allow plenty of time for revisions; they are the essence of writing well. Once you have written the first draft, read it over to see if it is clear. Ask yourself if there are other ways that your words might be interpreted. Eliminate extraneous text. Donít be clever Ė just deliver the facts.

 

 

 

 

 

  Check List

  • Be plain. State your meaning simply and clearly.
  • Be direct . Speak directly to the user. Use the active voice.
  • Be sincere . Speak "on the level."
  • Be accurate . Know your subject.
  • Study. Read background material; help files, users guides, and trade books.
  • Ask questions. Talk to colleagues by email, phone and in person.
  • Search the web. There are many sites devoted to teaching our products.
  • Consult product support. Surf product support web pages. Read faqs, white papers, and user questions and answers. Check out which problems bother users most.
  • Try it. Try all the commands, change all the parameters, run all the spinners, and take nothing for granted. Watch for errors in existing documentation.
  • Write quickly and edit well. Avoid the trap of perfectionism. Write the draft quickly, and spend more time doing revisions. See "Modular Content Design Standards for Instructor-Led Training" for hints on outlines before you begin.