Re: inhouse vs outside doc (RE: Good/bad docs)

[Dan Roberts <DRoberts -at- ISOGON -dot- COM>]

A few clarifications on my original post, because heated discussions
inadvertantly get started.

* I wrote "we inhouse writers" mainly 'cuz I've been on the inside of
the company (either as an employee or contractor). And 'cuz it looks
from a lot of sig lines that a lot of folks are employed inside
companies (even if it is their own consulting firm), rather than a
writer signing a contract with McMillan, for example, to produce a book
to be sold at Barnes&Noble.

* I'm not trying to knock contractors working inside a company. I was
one, could be one again. Again, I was more intending to compare and
contract the documentation produced *by the company about their product
and which is available at product release* and the documentation
available via Barnes&Noble or Amazon.com.

What I'm wondering, sorta, is: if a significant number of users think
that they can get a better book about using WidgetPro2000 than the
WidgetPro company turns out, then what about the 2 books caused this
situation?

Dan Roberts
droberts -at- isogon -dot- com

-----Original Message-----
From: John Posada [mailto:posada -at- faxsav -dot- com]
Sent: Friday, August 07, 1998 4:17 PM
To: TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU; 'Dan Roberts'
Subject: RE: inhouse vs outside doc (RE: Good/bad docs)


Dan...a part of this message caught my eye, so since I don't have the
time
at this point to respond all of your questions, I'd like to deal with
one of
them.

> * If we're back to a level playing field, then how is it that folks
tend
> to turn to outside doc to help them with a program, rather than the
> inhouse doc? What does the outside doc do that we inhouse writers
should
> be doing?
>
>
"...should be doing."    ????    Does the fact that "inhouse" is "we"
and
therefore, outside is "them" have anything to do with it? There is no
right
or wrong on WHERE...there is only a right or wrong when judged against
the
user's requirement.

Instead of automatically classifying the inhouse department as the right
place to do all documentation by default regardless of what the user
needs,
why not, BY DEFAULT", look at the user and choose the best way for the
user,
not for the source?

To me, that's like saying that all departments should use a particular
style
of documentation because it is the best style, regardless of how they
are
going to use it.

Now, a few factors (of many) having to do with where, and I believe that
they can be applied to both sides, are:

- Where does the particular skill needed for the task reside that will
give
the user more of what they need?
- Does the project fit into existing workload or would the project,
should
it be merged into the stream, cause an impact on everything else being
worked on.
- Does the project require a new look-and-feel, with which the present
sources may not be able to adjust to. e.g., an contractor used to
creating
manuals for in-house UNIX applications that must suddenly create a
packaged
Windows User manual..maybe there is an in-house source that is more
comfortable.
- Is it a document that maybe, needs to be shielded from population for
the
time being, such as a rework of the HR manual and policies from a
corporate
takeover that you may not want leaked out yet.

Let's not forget that we are creating documents for the user, not for
us.


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