RE: LONG - A colloquial writing style?

["Neumann, Eileen" <ENeuman -at- franklintempleton -dot- ca>]

I've been experimenting with using examples that involve little stories with characters. They're pretty basic, but they liven up the text and provide context and background. For example, a procedure I write may involve processing a certain type of financial request. My example might give a name to the individual sending in the request, background about why they are sending it, and maybe have them make a common mistake on the request. The processor reading the procedure gets a feel for what happens before requests get to them.

I've had user feedback that the examples are very helpful.

I also think the 'Dummies' books are actually quite clever. They're informal, but they get a lot of info across in a tight, well organized way. So they have a few cartoons - who doesn't read those first?  Dumb people don't read dummies books - they don't read any books. IMO.

Cheers,
Eileen Neumann
Business Rules and Procedures



 -----Original Message-----
From: 	bounce-techwr-l-177285 -at- lists -dot- techwr-l -dot- com [mailto:bounce-techwr-l-177285 -at- lists -dot- techwr-l -dot- com]  On Behalf Of Steven Brown
Sent:	Tuesday, May 10, 2005 10:33 AM
To:	TECHWR-L
Subject:	LONG - A colloquial writing style?


Hello all,

I'm curious to hear if anyone's writing technical
documentation using a less formal, more colloquial
style. (Notice I did not say grammatically incorrect!)

For example, we TWs typically write:

Note: Do not press the Panic button unless you are
encountering an actual emergency.

Are any of you writing more like this:

Pressing the Panic button will draw the attention of
emergency responders and your company's CEO, so you
might want to think twice before doing that.

(Silly example, but you get my drift.)

TWs constantly complain about how no one reads the
documentation, so I'm wondering what we're doing
wrong. Yea, there are lots of factors that affect the
likelihood of our readers using online help or picking
up a manual, but are we partly to blame? Although the
things we write about are serious, we forget that our
readers are real people. They're our neighbors. They
laugh, cry, curse, and eat. They watch the same TV
shows and read the same magazines. Even stodgy,
button-down bankers and attorneys (at the risk of
stereotyping) are fun-loving people on the weekends!

I can hear you arguing that some of our users are not
native English speakers. I would respond that, while
true, those very same people manage to function in a
society that uses informal language all the time to
convey information to them, via newspapers, magazines,
and television.

What about translation, you ask. Ditto there. Although
I've never worked with a translation service, I've
gotta believe they're smart people and able to
understand and translate colloquial language.

Why do we insist on writing such boring, dry
documentation? Part of it are old habits and the
expectations of the industries we serve, but are there
academic studies proving that formal language is more
effective (or more engaging!) than something akin to
what the Dummies series of books offers? Would upper
management balk if we showed them that more readable
documentation might entice users to read what we
write?

I don't know the answer. My own writing has often
bored me to tears, and I'm just wondering if there's
anything I can do to make it more "approachable," as a
wine snob might say.

Steven Brown



		

Notice:  All email and instant messages (including attachments) sent to
or from Franklin Templeton Investments (FTI) personnel may be retained,
monitored and/or reviewed by FTI and its agents, or authorized
law enforcement personnel, without further notice or consent.

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

New from Quadralay Corporation: WebWorks ePublisher Pro!
Completely XML-based online publishing. Easily create 14 online formats, including 6 Help systems, in a streamlined project-based workflow. Word version ships in June, FrameMaker version ships in July. Sign up for a live, online demo! http://www.webworks.com/techwr-l

---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- techwr-l -dot- com
Send administrative questions to lisa -at- techwr-l -dot- com -dot-  Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.