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:Bruce Byfield <bbyfield -at- axionet -dot- com> To:Peter <pnewman1 -at- home -dot- com> Date:Sun, 03 Sep 2000 21:17:24 -0700
> 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.
I'm not talk theory. Nor am I talking about personal preference;
I've taught the Victorian novel at university, and often read
Victorian novels for pleasure. As for Thomas Hardy (whom I
mentioned in my original post as an example of how not to do
things today), I've read virtually all his poetry and prose, and
much of it twice.
But theory and preference aside, I don't see how you can consider
the changes in style in the last century and question that the
pace is getting faster. The fact is so obvious that, if anything,
I was afraid that I was stating the obvious.
> Readers scan documents that are not interesting to read.
Yes, and, for most of them, that includes technical
documentation. That was my point. The fact that I'm one of the
few who does often read technical docs cover to cover doesn't
blind me to the obvious.
> 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.
I never said that all reading was the same - just that the
audience for virtually every kind of writing is more impatient
today. I might have said that readers don't have the patience
today for the exhausive, all-inclusive research of a writer like
Sir Richard Francis Burton - but, then, almost nobody would know
what I was talking about. I mentioned Hardy so that more people
would be likely to know first-hand what I was getting at.
I'm not sure why you bring up research. However, as someone who
has done several length research projects, I can assure you that
skimming is an essential skill. The body of information available
on many subjects - including the Silk Road - is so enormous that
you have no choice, unless you want to make the research your
However, maybe I should state things more clearly: readers of
technical information rarely read docs all the way through. They
skim until they find a section likely to contain what they want,
then read that. Usually, they read no more of tht section than is
necessary to solve the problem they are trying to solve.
> > more than 300 words [sic - I meant pages], 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.
What does a desktop have to do with the discussion? I was talking
about the explanation of a command.
Personally, I would never be so condescending as to refer to my
audience as "the unwashed masses." That sounds like a far worse
snobbery than anything said on Slashdot or in any Linux
Not that I have any patience with some of the postures taken by
script-kiddies and other beta-geeks.The whole point of the
magazine I write for is to help people to learn Linux more
easily, and so is the point of all the tech-writing I've done
(and expect to do) about Linux.
Anyway, taking a page and a half to explain the basics of a
command is enough to infuriate the majority of any audience,
regardless of their level of knowledge - especially if they have
turned to the explanation from the index or table of contents,
which is always a strong possibility. Do readers looking for help
really want to read several hundred words before they know if the
words are even relevant?
Moreover, the basics of cat are not so complicated that they need
three pages, no matter how unfamiliar the command may be. The
terseness of a man page probably wouldn't be useful to a new user
- but neither would the wordiness I mentioned. Something between
these extremes would probably be more useful.
And, clearly, I wasn't the only one who felt that way, since the
section has been revised by the company responsible for it.
I get the feeling, Peter, that you are using my post to spring
off in directions where I wasn't headed. Nothing wrong with that;
I've done it myself several times. But please don't attribute
ideas or positions to me that I haven't stated or tried to
Bruce Byfield, Outlaw Communications
Contributing Editor, Maximum Linux
bbyfield -at- axionet -dot- com | Tel: 604.421.7189
"They sought in kirk, they sought in hall,
The lady was na' seen,
She's o'er the border and awa'
Wi' Jock o' Hazeldean."
-Sir Walter Scott, "Jock o' Hazeldean"