Re: There's more to it than grammar

[Steve Fouts <stefou -at- ESKIMO -dot- COM>]

Eric Ray wrote:

> It's awfully easy, as a tech writer, to hide behind the shelter of
> providing "complete, accurate, thorough and detailed" instructions,
> while overlooking the fact that instructions meeting those criteria
> can be perfectly useless to everyone using them.

I agree completely. But...

> For example, some sys admin instructions I've been using
> (for installing and configuring software) go through a long
> and tedious step by step process (the kind that Geoff Hart
> named, with if Blah, then go to step 25, if Bloh, go to step
> 32, otherwise, continue here) to lead the reader through a process
> that works. However, I can't help but to wonder if the readers
> would be better served by providing  a higher-level set of
> instructions

You have to be careful here. In a previous job I lived among the
sys admins like Dian Fossey, and I went to quite a few Sun
System Administration training courses, so I know the audience
pretty well. You might assume that sys admins are a pretty
sophisticated audience (and, for the most part, that is true)
but system administration is a huge topic and people tend to
know what they need to know. If they've had problems with
hacks, cracks, and denial of service attacks they know a lot
about security, if not, then maybe they don't. And so on.

But when they get new software from a vendor they know very
little about it as a general rule. They may or may not have
been in on the purchase decision. Chances are, someone hands
it to them and says, "make it work."

At that point they are very goal oriented. They have one
specific task that needs to be done and they want your document
to fill that need. Make it work.

Later, once it is running, however badly, they are willing to
take the time to fine tune it for their own systems. But that
is reference material. I've seen sys admins with 15 years of
experience sitting at a workstation with the install instructions,
one finger on the step they're on, typing with one finger on the
other hand, reading the instructions out loud to themselves.

Don't try to get too cerebral on them at that point. They aren't
in the mood. Especially if it's Saturday, they've just downed
their 7th cup of gritty, coffee machine coffee, and they have 15
machines to install before they can go home to their daughter's
birthday party.

> I have a couple of reasons for thinking this...first, my attention
> span doesn't carry on for reading step by step instructions when
> I just need the higher-level process.

But are you typical of your audience? Know your audience. It's mantra.

> If I know exactly where I'm
> going, the docs are just a status-check (and if it's the skip
> to step 247 kind, not even a good status-check).

By the 15th install your instructions are just a security blanket,
it's true. But they're still there. They're still doing their job
even if they aren't reading them at that point. That's important
to remember. IMO. YMMV. TGIF.

--
Steve Fouts stefou -at- eskimo -dot- com

I never saw an author who was aware that there is any
dimensional difference between a fact and a surmise.
- Mark Twain


 From ??? -at- ??? Sun Jan 00 00:00:00 0000=