Re: Employment Interview

[Karen Kay <karen -at- WORDWRITE -dot- COM>]

Mark Baker said:
> User documentation is performance support material. Its purpose is to get
> users to act correctly. Whatever gets users to act correctly in as short a
> time as possible is what you should write **whether it is technically
> accurate or not**.

I think you're documenting a very different kind of software than I
am.

> Or, if you like, think of it as the distinction between functional accuracy
> (that which leads to correct action) and philosophical accuracy (that which
> leads to correct understanding). Philosophically accurate description of a
> complex product is usually dense and complex. If the product is well
> designed, a functionally accurate description is usually simple.

The tool that I document is great to use--I overheard one of the
developers telling someone once that it didn't need any documentation.
This is true. But while the tool is easy to use, it's also easy to get
garbage out of. My job is to give the users enough understand that
they don't get garbage.

> If you get your engineers to read your documents (argument # 1: they
> don't want to read them),

I have had this problem, but it's part of their job. It's never been
what I would call a 'conflict'. It helps that I play with their
software and critique it for them and find bugs--their reviews serve
the same purpose for me.

> they will not like them because they are not philosophically
> accurate (argument #2: they don't think they are accurate or
> complete).

Hm. I've never had anyone even bring this up before.

> So, if you have never argued with an engineer, it has to be because you have
> been incredibly lucky with the engineers you have had to deal with, or

Some have been remarkably wonderful and I love them to pieces; some
have been just okay.

> because they have never read your documents,

Not bloody likely.

> or because you have failed to
> create documents which are functionally accurate.

What you call philosophical accuracy doesn't preclude functional
accuracy. I must admit that information about why things work is
something dear to my heart--I used to be an educator. So perhaps I
simply hit the right happy medium wrt "functional" and "philosophical"
accuracy.

> Bottom line: your job is to make users act correctly, not to describe the
> product.

Now I'm really confused. What do you mean by 'describe the product'?

> Engineers don't like this and will argue with you.

They will argue with me about making documentation that helps customers
use the software efficiently? How is this in their interests?

In fact, I'd have to say that for all the jobs I've had that this was
something I shared with the engineers, a desire to make documentation
that helps customers use the software intelligently and efficiently.

Karen
  karen -at- wordwrite -dot- com