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: Magical Thinking and Grimoires From:"Huber, Mike" <mrhuber -at- SOFTWARE -dot- ROCKWELL -dot- COM> Date:Wed, 14 Jan 1998 15:38:34 -0600
I wonder how much of that has to do with a kind of reversed Clarke's
Law?
Clarke's Law (any sufficiently advanced technology is indistinguishable
from magic) seems quite ironic when I'm performing "software magic."
The magic I do has to do with bad technology, or holes in technology,
not advanced technology. My grimoire (personal notebooks, not the
documentation I produce) is not filled with systematic notes detailing
wonderful things I've come to understand about software, but very
specific ways to combat particular software demons.
The things I understand, I understand. I have no need for notes to tell
me how to enter the letter 'A' in a document. Do I need a note to
remember that <b></b> is HTML for bold text? No. I need a note to tell
me that, if I need to edit the format of a page number in Word, I have
to go to the Insert menu, start inserting a page number that I don't
need, edit it's format, and then cancel out. I need a note to tell me
that HTML for a space is .
Good design is transparent once we understand it. Bad design requires us
to cast spells we don't understand. When we use a well designed thing,
we feel like we are doing something natural.
---
mike -dot- huber -at- software -dot- rockwell -dot- com
Home: nax at execpc.com
>-----Original Message-----
>From: Bruce Byfield [SMTP:bbyfield -at- axionet -dot- com]
>Sent: Tuesday, January 13, 1998 6:13 PM
>To: TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU
>Subject: Magical Thinking and Grimoires
>
>...
>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.
>
