TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:Re: Get to the point? From:Peter <pnewman1 -at- home -dot- com> To:Bruce Byfield <bbyfield -at- axionet -dot- com> Date:Sun, 03 Sep 2000 08:51:42 -0400
Bruce Byfield wrote:
> Getting to the point is a good idea in any modern writing. Modern
> readers don't have the patience to endure (for example), a three
> page introduction that starts with a man walking down a road, the
> way that a couple of Thomas Hardy's books do. Personally, I like
> a leisurely pace, at least in some moods, but it just doesn't
> play for many readers today.
Assuming we are talking about fiction, you have unfortunate
misperception. It is even more unfortunate if you do not have a
misperception. Properly written introductions can set the proper tone
and mood. However, there are other techniques for creating a background
for understanding, other than a lengthy introduction. It can be
effectively accomplished through character dialogue.
> In tech-writing, it's especially important. If my contention is
> right that readers scan docs rather than read them, then getting
> to the point is essential. Personally, I find myself getting
> impatient even with introductories to a procedure like, "To
> configure the widget:".
For your impatience I recommend Vallium. <g> Readers scan documents that
are not interesting to read.
There is a difference between reading for pleasure and reading for
technical information. Notwithstanding that, if I am doing research for
a story about the Silk road, I want as much information as possible.
Skimming just won't cut it.
> But the worst case of not getting to the point that I remember
> was in several releases of a manual from a well-known Linux
> company (no names, but it had a hugely successful IPO last year,
> and many people identify it with Linux :-) ). In a manual of no
> more than 300 words, it took about 3 pages of folksy writing to
> explain the cat command - and took at least a page and a half
> before it explained what the command was actually good for.
> To be fair, I believe that the latest version of the manual is
> more to the point, but this example has stuck with me as an
> illustratio of how not to write.
Please don't be what I call a Slasdot-Linux Snob. Command line
approaches are new to users who were not around during the DOS days.
Windows and its GUI interface helped make the 'puters friendly to the
unwashed masses. If you are talking about a user friendly desktop for
Linux, the approach was intended to make Linux a viable, user friendly
alternative to Windows.
Many end users need docs with a kindergarten approach.
the vast majority of non technical readers, will turn off as soon as
they see technical terms such as "root," "cat," or even "Dir*." They
need a certain amount of hand holding. The writer made a decision to try
to make the technical terms more palatable. I see is nothing wrong with
that, provided the meat is not left off, or it does not get so cutsey as
to be distracting to the intended readers.
"When a man sits with a pretty girl for an hour, it seems like a
minute. But let him sit on a hot stove for a minute-and it's
longer than any hour. That's relativity," - Einstein-