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:Magical Thinking and Grimoires From:Bruce Byfield <bbyfield -at- AXIONET -dot- COM> Date:Tue, 13 Jan 1998 21:12:37 -0500
Ever since I started writing for a livng, I've been intrigued and a
little puzzled by the way that the average person uses computers.
My present job, however, has made me start thinking a little deepr.
My present job involves documenting seven years of undocumented work.
Usually, I have to talk to a lot of SMEs, then double and triple check
information.
The result is some of the most intriguing writing I've done. However, as
I interview, I notice that even some advanced users frequently resort to
what I call "magical thinking." That is, they know that typing a certain
command with certain parameters will get certain results, but they don't
understand the details of what thye're doing.
To these users, commands are magical spells, and their notebooks are
like a sorcerer's grimoire, full of unystematic notes about how to get
specific results, but with little overview or understanding of the
processes involved.
Some people (not just at my present site, but at past ones, too), seem
to think that the manuals should be grimoires, too.
And no doubt writing grimoires would be a quick way to provide
documentation. I've even heard of some writers who copy comments from a
program file and slightly reword them to produce a manual.
However, I maintain that some background understanding makes people more
capable, as well as more interested in their jobs. Obviously, the amount
of background has to be adjusted for the audience, but I think the
result is well-worth the tradeoff of slightly less productivity each
day.
Also, of course, I have to understand in order to bring the diverse
pieces of information together.
Fortunately, the VP who hired me supports my way of doing things. Still,
I can't help wondering:
--how widespread is magical thinking? To what extent should it be taken
into account when writing manuals? Should it be opposed, as I'm inclined
to do?
--what do people think about the pros and cons of grimoires, as opposed
to contextual manuals?
