Re: More personable tech writing

[Len Olszewski <saslpo -at- UNX -dot- SAS -dot- COM>]

Sue Gallagher tells of her personable technical writing style:

[...]

> One thing that I try to do (and I occasionally get dinged by my editor
> for it) is maintain a conversational tone, especially in tutorial and
> "user manual" type pieces.

[...]

> This includes using _their_ jargon (common usage terms),
> using contractions, and any other devices appropriate to the piece that
> make the end user feel comfortable with _me-the-book_.

You have to know your audience *really, really* well to get away with
this for a series of books! My own geiger counter goes off of the scale
anytime *I* see jargon of *any* kind in technical prose. I tend to skip
familiar sections entirely. But maybe folks like me aren't in your
audience. You better make sure!

> In pieces aimed toward a poor-dumb-user (pdu) audience, this includes
> spicing up examples with a fair amount of humor.  I keep a list of
> names like Phil O'Dendron and Les Danse -- perfect for populating
> databases with -- and show merge letter examples from park ranger
> Captain S. Tate Parks.

This kind of whimsical approach to examples translates poorly in
different languages or cultures. Your company may not be international
yet, but even within the USA you will encounter users with different
cultural contexts who won't "get" this humor, and may find it
unnecessarily distracting or confusing. Some may (inexplicably to you)
find it offensive. Again, if you are sure your audience does not contain
readers like this, go for it, I guess. However, my view is *why take
that chance*?

> In pieces aimed toward the application developer, executive, or other
> "professional" level user, I maintain a more business like and "crisp"
> style -- a kind-of "let's get down to business" approach.

Ok, sounds like a good move on your part.

> IMHO, you can engage your readers and stimulate their imagination more
> effectively by spotlighting their (collective) egos -- not by remaining
> ego-less, and not by foisting your own ego upon your readers.

I'm not sure about what "spotlighting collective egos" really means, but
I suspect this is a tactic which can backfire if your audience contains
readers with cultural references different than what you expect.

I'm not saying you shouldn't do it; I'm saying *I'd* never do it, I'd
reccommend against somebody trying it, and I'd caution that it would
take a very skillful, experienced and knowledgeable writer to pull this
off successfully as a means of communicating technical information to an
identified audience.  And even then it would a fifty-fifty proposition.
This is *my* humble opinion.

> Works for me!

It's nice to be successful, I admit, so good for you.

|Len Olszewski, Technical Writer |"It is not enough to succeed. Others|
|saslpo -at- unx -dot- sas -dot- com|Cary, NC, USA| must fail." - Gore Vidal           |
|---------------------------------------------------------------------|
| Opinions this ludicrous are mine. Reasonable opinions will cost you.|