RE: Hackos' minimalism seminar -- some insights

["Thomas Eagles" <tekwriter -at- sympatico -dot- ca>]

> -----Original Message-----
> From: Mike West [mailto:Mike -dot- West -at- oz -dot- quest -dot- com] 
> Subject: RE: Hackos' minimalism seminar -- some insights
 

> Someone wrote, in what appears to be an
> attempt at self-aggrandizement:
> 
> > Gee, I've been saying that for over a decade and nobody pays
> > to attend any of my seminars. 

Methinks that perhaps there is good reason that the fine intentions of
the alleged visionaries are ignored, or at least discarded. It seem
everyone would LIKE to study their readers before writing for them. I'd
guess that a small fraction of the companies that produce user docs
actually DO analyze the audience first. That's not an issue for tech
writers, but rather for product managers, VPs, and principals in
companies -- those who have to justify the expenses. If companies don't
want to spend money on user analysis, and if the user isn't interested
in being analysed in the first place, then what can you do? Some of the
user analysis I've seen over the years wasn't worth the time or effort
invested. That's been my experience, anyway (FWIW).
 
> > Hackos (and me of course) are correct. Most writers document
> > surface-level instructions and do not take the time or effort to 
> > really think about HOW the product/technology works and might 
> > be used. As such, most tech docs are endless
> > streams of pointless and worthless instructions. 

As a usability expert described it this past weekend at a Toronto-area
STC seminar, it's not about scribbling down procedures, it's about
enabling the actual, real product user (not observed test subjects). Do
you really need to know the user intimately? No. Do pointless and
worthless instructions help the user? Probably not pointless ones, no.

If your docs are nothing but signposts that guide the user (*any* user)
from the beginning of the task to the end, and, once there, let them
know when they have completed it, then you have enabled the user. The
user has just done the steps while following your worthless pointless
instructions. Job done. Good work! It is sort of like signs on the
highway that tell you (repeatedly) how far it is until you reach your
destination. And then they announce the destination when you have
completed your trip. Same thing. You may not recall all the signs and
all of the distances, but you got there in one piece. If a procedure
requires documentation of this sort, you probably won't be doing that
task repeatedly on a daily basis, anyway.

We tend to want to overcomplicate this process. We attach requirements,
such as rules about the optimal or maximum number of words in a
procedural step or sentence (one answer: if you can't immediately repeat
the sentence without reading back what you just wrote, there are too may
words). Keep it simple. Keep in mind the purpose of your docs: to
enable; educating or informing is gravy. Gravy may even cause a heart
attack. Gravy isn't good for you. Gravy is not your friend. Your goal is
to talk turkey, not gravy.

> But you see, Hackos never said that -- nor would she.
>  
> She writes clearly, specifically, concretely, making 
> constructive suggestions rather than blanket 
> condemnations of "most writers'" skills and efforts.
> 
> She has long been a strong and clear advocate of
> user-oriented, task-based design as the key 
> factor in a successful help system or manual. She
> advocates understanding the audience's needs, skills,
> and goals as a first step to user-centered design.

IF that's what she advocates, then she's an idealist, which is an
impractical thing to be as a tech writer. I'd rather be a realist: what
help do our users need in order to perform the tasks this software is
supposed to enable them to do? Probably a step-by-step procedure in
simple, even memorable,  language.

> Here's a quote: "We must stop writing
> documentation as we know it, abandon the developers
> and their need to explain how everything works, and go
> to work for the users.

I think we'd all agree with it to this point, no? It sure SOUNDS good.

> "We need to get closer to the
> users, spending time in their workplaces, watching them
> struggle with everyday tasks, listening to how they
> describe their activities, and generally understanding
> their environment from their points of view."

D'OH! Not to this point. Fact: with rare exception, we will NEVER get
closer to the workplaces, and we don't need to. There may be rare
instances in which the tech writer is documenting plant procedures, or
that sort of thing, and then you need to get "closer to the user."

How the software is used? Activities? Environment? Won't that differ
from customer to customer? How can you base it on one test instance and
assume that test instance will be any better or more representative than
the one in your lab or test area at work?

Enable! That's all you are supposed to do. Why waste time studying that
which isn't part of the product? That is, unless your users are so
homogeneous that you are documenting THEM rather than just the product.
Is there a danger in documenting the LCD (lowest common denominator)?
Ah, yeah, perhaps...

> She would not use a phrase like "document surface-
> level instructions" and expect people who care about
> precision in language to know what in the world she
> was referring to. What does it mean to "document
> an instruction"? Is that something like writing an 
> instruction, or documenting a procedure, but different? 

Procedures. Instructions. Tasks... Enable!
 
> Gee. Maybe that's why her stuff is worth paying for.

Maybe. But the only book of hers that I was able to struggle through was
Managing Documentation Projects (or something like that). It was
theoretical, dense, impractical, and (I thought) a book that I would NOT
recommend to other TW managers. And after that, I wouldn't pay for
another of her books.

Just one writer's humble opinion.

Tom



^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Order RoboHelp X3 in November and receive $100 mail in rebate, FREE WebHelp
Merge Module and the new RoboPDF - add powerful PDF output functionality
to RoboHelp X3. Order online today at http://www.ehelp.com/techwr-l

Check out SnagIt - The Screen Capture Standard!
Download a free 30-day trial from http://www.techsmith.com/rdr/txt/twr
Find out what all the other tech writers, including Dan, already know!

---
You are currently subscribed to techwr-l as:
archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit
http://www.raycomm.com/techwhirl/ for more resources and info.