Re: inhouse vs outside doc

["Eric J. Ray" <ejray -at- RAYCOMM -dot- COM>]

>I agree. I still think users deserve to get full documentation with their
>tools. However, the more I meet users, the more I think that one of the
>main purposes of a user's guide is to answer the question "What do I do
>_now_?", whether now is at the start or after the user has already gotten
>him or herself into a mess.

Precisely--as far as we're concerned, the full documentation
SHOULD come with the tools, but specialized, focused, "what do
I do now" instructions often fit better in the context of third
party manuals.

>R&D department tends to take the attitude so well expressed by Tina the
>Technical writer when she said "Let's be honest userboy, if you need to be
>told _that_, you're too stupid to use this product." The R&D folks tend to
>nix chapters like "Getting Started" or neglect to fund a decent tutorial.

And that's the conflict that often leads to inadequate documentation,
depending on who holds the purse strings or who has veto power.

>I don't see an intrinsic conflict between providing documentation that is
>useful and creating documentation which answers needs of marketing and R&D.
>I think laziness (and penny-pinching) within organizations prevents them
>from creating good user documentation. In the end, they are just funneling
>money to their service department, which has to answer all of userboy's
>questions.

But that's not quantifiable and few, if any, companies undertake
the research needed to satisfy themselves that more effort in documentation
would result in lower costs in other areas. (I'm aware of some research
in this area that's scheduled to be published soon--perhaps the author
would be willing to comment on it after the publication is available.)


>My question is, if you are a third-party technical writer, how do you know
>who the user is? The Dummies books have chosen their readers, to some
>degree, by using a clever title. However, that is not the case for most
>third-party manuals. How can you focus on what the user wants if you don't
>really have contact with the user?

(Note that this has been done to the death in the archives, so let's
not pursue this sub-topic thread) Dummies books don't really target
dummies in the sense of not smart people, they target "dummies"
in the sense of people who are not knowledgable in the subject domain.

On to the thread that would be fun to discuss:
Next, how do you know who the reader is? Good question. First,
a lot of market research goes into most commercial computer books,
both on the part of the authors who propose a book and on the
part of the publisher who determines if the book would be
viable and profitable. To a great extent, that research will show
who might buy the book, who might use the book, and in what
contexts the book might be used. Sometimes the series helps
focus the audience (e.g. Dummies series, Mastering series, anything
from O'Reilly), but sometimes books are stand-alone, in which
case the research and viability focuses much more on the
sales and uses of the product to determine the audience for
the book.

Second, writing a third party book allows the authors to define
the audience (usually in the Intro) and write directly
to them. For example, a book about database programs
might explicitly state that it's only for rank amateurs
(and if you've heard of SQL, you're too advanced to read
it), or might list prerequisite knowledge to take full
advantage of the book's coverage.

Finally, if authors put email addresses in their books
(as Deborah and I do), there's no doubt about what
was and wasn't a hit with the readers.

Eric (and Deborah)

BTW, for an interesting course in reader expectations
versus reader fulfillment, pick a computer book about
which you have strong feelings, either positive or
negative, and read the comments about it at Amazon
(www.amazon.com).





*********************************************************
* Eric J. Ray, ejray -at- raycomm -dot- com, http://www.raycomm.com/
* TECHWR-L Listowner, co-author _Mastering HTML 4.0_
*   _HTML 4 for Dummies Quick Reference_, and others.
* See our overhauled Web site at http://www.raycomm.com

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