Re: why not an engaging style?

Subject: Re: why not an engaging style?
From: David Neeley <dbneeley -at- gmail -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Fri, 19 Aug 2005 13:29:39 -0500

I do not see this tradeoff you speak of.

If I am writing an end-user manual, simply writing in an informal tone
does not mean that I am any less clear. This kind of informality is
simply helpful in making the material accessible--"user friendly" in
the time-honored term.

If, on the other hand, I write for system administrators or the
tech-savvy, I write no less informally but the level of discussion is
often higher, with more detail concerning those aspects that are
necessary for the admin to deal with that do not necessarily concern
the end users.

However, "informal" does not mean to inject surplus verbiage in some
attempt to appear "cool" or "buddy-buddy." That takes "informality"
into the realm of condescension.

I avoid slang, but I do use a larger number of ordinary contractions
than I might in strictly formal writing. Slang quickly becomes dated
and makes understanding by anyone for whom English is a second
language a distinct problem.

There are occasions where a small bit of humor may be appropriate--but
that is a terribly slippery subject since humor is so often a cultural
perception. Instead of outright humor, therefore, a perceptible level
of warmth can often substitute well.

For example, in manuals I have written for total beginners on a
particular system, I have included an introductory section that
acknowledges the frequent tension that may accompany learning a new
system. I included a sentence or two that this is completely normal,
that the "how to" sections are designed to introduce the material
clearly and succinctly, and that we would be introducing topics in a
manner designed so that by following the manual they would always know
why they were being directed to perform any given procedure.

This has been a very popular approach among these new users. By using
a general approach similar to the Information Mapping structure for
procedural information (an introductory bit telling what the section
will accomplish, the individual steps clearly set out, and a final
discussion giving more overview and any reference information that
might be helpful), working through a tutorial becomes a self-guided
experience that instructs very effectively, while also serving as an
easy to use reference later when they may have forgotten one procedure
or another.

In other words, making the material accessible for as many of the
users' needs as possible is an attainable goal and goes very far in
making the manual seem indispensible. An informal tone adds to this
accessibility, while the structure makes it more useful throughout the
user's interaction with the program.

On the other hand, if you want to make something "dry"--put it in the
third person, use passive voice, and employ any other devices you can
think of to distance the user from the material.


On 8/19/05, sankaraR <ss_rajanala -at- yahoo -dot- com> wrote:
> There is a trade-off between being engaging style
> (a good copy) and a dry (I'd say neutral) tone.
> It is not always the case, but when you tend
> toward an informal tone - chances of ambiguity
> creeping in (unbeknownst to you) are higher. But
> then, I am paranoid about a lot of things anyway
> other than ambiguity so it could just be me.


Now Shipping -- WebWorks ePublisher Pro for Word! Easily create online
Help. And online anything else. Redesigned interface with a new
project-based workflow. Try it today!

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 for more resources and info.

Re: Why Aren't Open Source Tools Being Considered?: From: Mike O.
why not an engaging style?: From: sankaraR

Previous by Author: Re: Why Aren't Open Source Tools Being Considered?, Part 2
Next by Author: DocBook WYSIWYG editors...
Previous by Thread: Re: why not an engaging style?
Next by Thread: Re: Why Aren't Open Source Tools Being Considered?

What this post helpful? Share it with friends and colleagues:

Sponsored Ads