Year: 2010

by Jennie Ruby

What role, if any, should humor play in technical and
training materials?

When writing training materials, I am always looking for new
ways to introduce a lesson and keep the tone engaging. The introduction to a lesson
needs to draw in the learners and get them motivated to continue the training,
and the writing throughout the lesson has to keep their attention. Can the use
of humor help?

To find an answer, I skimmed some of the writing in my
shelf-full of training books. I found many examples of engaging and personable
writing styles, but very few examples of out and out humor.

Even in the For Dummies series and its competitor The
Complete Idiot's Guide to… group, both known for their clear and readable text,
humor was rarely on display. I did find some exceptions. Several of the Dummies books have a cartoon at
the beginning of each chapter. Laurie E. Rozakis' The Complete Idiot's Guide to Grammar and Style begins with a quote
from comedian Jerry Seinfeld. And I developed a smile, if not a chuckle, from this
bit from Susannah Gardner and Shane Birley's Blogging for Dummies:
"No matter what your teenager tells you, there is absolutely
no requirement that you must write your blog while wearing your pajamas. Also,
you are allowed to use a spellchecker."

And I was pleased by their alliterative subheading "Tiptoeing
Through Templates."

But in books like DHTML
and CSS for the World Wide Web, Excel
Data Analysis, Illustrator,
and even The Rough Guide to MySpace &
Online Communities, humor and joking did not find a place.

I conclude from this that joking around pretty much does not
have a place in training materials. The reason would be twofold:

• You need to maintain a credible and
  authoritative tone.
• Humorous stories and jokes may be a distraction
  rather than an enhancement in learning materials.

Does this mean your training materials must be utterly dry,
factual, and boring? Absolutely not. But telling jokes? Not so much.

Do you agree? Or strongly disagree? We would love
to hear from you about experiences you have had with using humor in training
materials. Please send us your comments.

by Jennie Ruby

Recasting sounds like something a fly fisherman would do, but in writing and editing it means to restructure a sentence. Restructuring is sometimes needed to avoid awkwardness, to give information in the order the reader needs it, or to introduce new concepts in a way that will promote understanding.

Take this problem sentence: It is [I, me] who [demand/demands] a change in the rules.

The correct grammar is this: It is I who demand a change in the rules.

However, the correct grammar here sounds unfamiliar or wrong to readers used to seeing who with demands, not demand. Recast the sentence so that it is correct but not awkward:

Recast sentence: I am the one who demands a change in the rules.

You can restructure or recast a sentence to put information in the order the reader needs it:

Original: Click the Chart tool from the Illustrations group on the Insert tab.

Your reader cannot see the Chart tool until the Insert tab is selected. The following recast sentence gives the information in a more usable order.

Recast: From the Insert tab, Illustrations group, click the Chart tool.

To introduce a new concept, you may recast a sentence to place the new concept at the end, so the reader is led from the familiar to the new and thus understands the importance of the new information by the time it is encountered.

Original: A JavaScript operator is a block of code that is required for the operation of your Spry widgets.

The original sentence starts with an unfamiliar technical term, leaving the reader at first wondering why she or he cares. The fact that the code is required is buried in the middle of the sentence, and the familiar thing this all relates to does not pop up until the end. Assuming your reader is familiar with and has created some Spry widgets, the recast sentence begins with the known and introduces the new concept at the end.

Recast: To operate properly, your Spry widgets require a block of code called the JavaScript operator.

Don't be afraid to recast a sentence several times before deciding which structure catches the reader's needs the best, and don't let your reader be the one who gets away.

Are you an eLearning developer who has been tasked with creating an effective voiceover script? I'm teaching a 3-hour, online class later this week called Writing Effective eLearning Voiceover Scripts. During the class I'll be teaching you how to define the appropriate voice and tone for a narrative text. You will learn how to take specific steps to create the engaging and personable writing style that voice-over narratives require. I hope you can join me. Click here to learn more.

***

by Jennie Ruby

Nearly every piece
of technical writing has acronyms. Yet they can be a barrier to a reader who is
trying to absorb technical information or to a learner who is encountering new
terms for the first time. Of course most editors know to spell out an acronym
on first use and introduce the acronym in parentheses. For example, below is a paragraph similar to the
paragraph you are reading now, but using acronyms:

What can we do to help the
reader? First, consider not using acronyms but spelling out words and phrases
even if they are repetitive. Limit the use of acronyms to technical terms for
which knowing the acronym is important in its own right. For example, in web
design the abbreviation CSS is used more often than the name it stands for,
Cascading Style Sheets. The reader needs to know that acronym as part of
understanding the topic.

Second, consider providing a
separate list of acronyms as a glossary. The reader can then refer to one
common source for all of your acronyms, rather than paging back through your
text trying to locate the parentheses where you first defined each one.

Third, use the same method
to define every acronym. In the sample paragraph above, I defined LENTs
backward, giving the acronym first, and then its definition in parentheses. The
reader will have a harder time locating the acronym when it is defined this
way.

Fourth, don't assume that if
you have introduced a long acronym, the reader will understand you if you then
use a small part of that acronym alone, as I did in the example with A's,
meaning acronyms, which was defined only as part of UOA.

Fifth, do use a small s to make an acronym plural, like this:
ATMs. If the acronym would look like another word with the s, add an apostrophe
like this: A's.

Sixth, when you introduce
the acronym, make sure it is not a possessive or a plural. If necessary, reword
the sentence: instead of "Internet Explorer's (IE's) browser window is…" try
"The browser window of Internet Explorer (IE) is…"

Note: Acronym actually means an abbreviation that
uses first letters of words and that is pronounced as a word, like NASA, versus
an initialism, which is any
abbreviation made up of first letters, like USS. However, Webster's lists
initialism as a secondary meaning of acronym, probably because so many people
lump them together, as I have chosen to do in this article.

***