RE: Minimalist or low-level? [LONG]

["Lisa Wright" <liwright -at- earthlink -dot- net>]

(Diving back in somewhat late in the day)

Well, Brad, I have to say, your post is definitely one of those that
made me go, "hmmm?" I do think a large part of why we disagree has to do
with the scope of what's being cross-referenced vs. what's being
explained in each topic. For a simple menu command, I do think that
File-->Open (or some variation thereof) is better than describing, as I
said earlier (or meant to say, anyway, if that didn't come across). But
I think repetitive instructions are really bad for user comprehension in
many cases. For example: 

In the system I'm documenting, and for many database applications, you
first have to search for a record before you can do anything to it. Now,
in my manual (PDF, readers can view online or print), there is a
multi-page section on searching. Before I edited this guide, much of the
information was repeated *every time the user had to search.* This was
wasteful in terms of time, maintenance, consistency, accuracy, and
applicability. But it was most wasteful in terms of getting the user to
the specific procedure. Readers looking for help do not want to spend
time wading through piles of crap. They want to know how to do what they
want to do. Searching is a necessary prerequisite, but it is not the
focus of the procedure.

In my edit, I saved the one section on searching. In every other
instance, I said:

To update the foozlebender
1. Search for the foozlebender. See "To create search criteria" on p. 8.
In the search results click Edit for the foozlebender you want to
update.
2. Proceed with content relevant to the topic at hand.

Now, how does this fail the reader? Really? I'm curious.
 
I said:
> 2. Consistency. If you write the procedure for "Opening a record" one 
> time and cross-reference as needed

You said: <...if you are scattering hyperlinks all over the place they
had beeter be meaningful.>

Well, yes, I think that's a given. I have seen documents that had
completely meaningless cross-references/hyperlinks and all they did was
confuse the issue.

You said: <Poor documentation is defined as saying something one time in
one way in one place.>

Huh? Poor documentation is where I can't tell why I am doing something.
Or tell how to do it. If the writer can tell me in a single sentence
that the foozlebender gives me a way to track the status of all the
little fizzlies in the bender, and if that is explained at the exact
point when I want/need to know, then why does that need to be written
three different ways? 

You said: <Most docs these days are searched help-file style, and if you
have a mental construct of them as a serial presentment you will fail
your readers. Say it again, say why it is important again, say it a
different way, and show an example.>

Yes, I see this style followed in many print user guides, up to and
including the fashion of providing the summary TOC and then the detailed
TOC. The beginning-of-chapter TOC and especially the inane, contentless,
repetitive summary at the end of the chapter.

I think setting the context for procedural information is highly
beneficial. That's providing the right information for the reader at the
right time. I think the robot-like "say it, say it again, etc." is
another reason why so much documentation is bad. We have patterns that
we apply to mindlessly honing our document structure instead of figuring
out what's important and honing our *content*.

> 3. Focus on the important parts. ...Don't spend 10 minutes 
> trying to get them to the meat of the procedure.

You said: <Again, with electronic docs that don't cost by the page, it's
better to be detailed , because some one is going to need the details.>

Yes, so you point them to where the details are. Electronic docs have an
equivalent "topic cost," so saying that they don't cost because there's
no physical page is deceptive. There are the same costs of writing,
translation, maintenance, etc. The production cost is different, of
course, but really you're just passing that onto your reader if you're
delivering electronically. Shouldn't we be considerate about what we
pass on?

> But one of 
> the keys of minimalism is to give the reader *only* the information 
> they need, when they need it, and give them the *means* to find more.

You said: <If you are going to write spare docs, you better add some
explanatory links, and explain them in text (not just at the front of
the doc).>

Yes, again, hypertext with meaning. One of the great things about
electronic documentation is that you can "layer" your information.
Procedural stuff at the top, with links to more
detail/explanation/conceptual stuff. This kind of information structure
takes time and thought to set up. I can't really do it in my PDF, so the
concepts go where I think they are most appropriate. "Standards for
Online Communication" by Hackos/Stevens provides a great explanation of
the different levels of readers and the kind of information they need
and when.

You said: <Really what should be done is to charge all tech support
calls back to the tech writers budget. It isn't just that the tech calls
cost money, it's that each one is a failure of the product.>

By all means, yes, punish the tech writer. Huh?

Lisa


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Check it out! Get some cool freebies when you buy RoboHelp! You'll receive
SnagIt screen capture software and a 10% discount voucher for RoboHelp
Consulting. This special offers expires March 29, 2002.
www.ehelp.com/techwr
---
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.