Re: Minimalist or low-level? [LONG]

Subject: Re: Minimalist or low-level? [LONG]
From: Brad Jensen <brad -at- elstore -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 5 Mar 2002 23:46:38 -0600

----- Original Message -----
From: "Lisa Wright" <liwright -at- earthlink -dot- net>
To: "'Brad Jensen'" <brad -at- elstore -dot- com>; "'TECHWR-L'"
<techwr-l -at- lists -dot- raycomm -dot- com>
Sent: Wednesday, March 06, 2002 12:58 AM
Subject: RE: Minimalist or low-level? [LONG]

> (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 get that a lot. I've always assumed that it is the gears in your brain
grinding as you shift your thinking.

Humor me.

(Or dont').

> 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.

no that's fine, but I would change the wording a little

Either put it in parentheses to indicate it is a subtext/explanation, or

For details and examples on how to search, see (etc.)

the promise of examples , when you are searching for help, is like finding
an icechest full of Oley when you are stranded in Death Valley

> 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 better 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.

By meaningful I mean not just a label as a hyperjump, but an explanatory
label, something that hints at context as well as content

> 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?

Because people do not run into problems in the same order that you offer
your explanations. They are thinking about the problem, you are thinking
about the solution. They really aren't quite on your wavelength. It is
better to refer to the solution in different ways, in different parts of the
text, so they will run into your pointer while searching for the wrong
thing. The reason they have a problem is they do not understand the
solution. Their assumptions and theories are incorrect in some way.

You need redundant information in any error-correcting transmission
protocol. As an abstraction, technical documentation can be seen as an
error-correcting commnuication of information. I*n the light of that
abstraction, technical documentation should have redundant information to
allow error correction to occur, and the more redundant information, the
more errors can be corrected without resorting to an alternate and more
expensive communicaiton method (calling tech support).

What percentage of the human interaction with your document (by users) will
be a person reading the document from start to finish? 2%? 5? .01%?

Making non-repetition and the concern for not boring or annoying an
end-to-end reader your primary consideration is a conceptual error. That is
the novelist approach.

> 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.

Since I always read books frm the back to the front, that's the perfect
place for me. And if I am looking for something, I use index, then summary,
then long boring tedious content, in that order.

> 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?

Let see, 160 GB drive is $300, so a megabyte costs pretty close to nothing.

> > 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.

yes, this is good

> Procedural stuff at the top, with links to more
> detail/explanation/conceptual stuff.

and examples sprinkled throughout. one example is worth a thousand

> 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.

thanks for the referral.

PDF can link within itself, so you mean the tools to create these kinds of
PDFs don't commonly exist.

Maybe write as html and then convert to pdf?

> 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?

I was thnking reward.
> 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.

Have you looked at the new content on TECHWR-L lately?
See and check it out.

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 for more resources and info.

RE: Minimalist or low-level? [LONG]: From: Lisa Wright

Previous by Author: Re: THANKS! Re: It's time to go
Next by Author: ran across this tool
Previous by Thread: RE: Minimalist or low-level? [LONG]
Next by Thread: RE: Minimalist or low-level?

What this post helpful? Share it with friends and colleagues:

Sponsored Ads