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

[Steve Arrants <stephena -at- COMPBEAR -dot- COM>]

Dan Roberts <DRoberts -at- ISOGON -dot- COM>
writes:

>In-house writers often have to struggle with getting code and
>information from programmers, getting it through reviews, getting it
>published (sometimes under difficult situations with less than optimum
>tools), and published in hand the same day the software is available.
>OTOH, the inhouse writer does have access to the code and programmers
>before the software is released, and does have advantage of a company
>full of experience.


So does the "outside" writer, in many cases.  Most of the large
publishers--MSPRESS, SAMS, SYBEX, O'REILLY--have good contacts with the
product managers at Microsoft, Netscape, Adobe, etc.  We're given access to
specs, pre-release software and updates, sample code and files, and the
company's documentation on the product.  I've also met with  the developers
when necessary.

>I've never done an outside software doc, so I have no idea what hoops an
>outside writer might have to jump through, but I'm sure there are some.
>And I'm sure there are advantages also.
>
>So, I'm curious about the comparisons between the two:
>* Do the constraints and difficulties experienced by both cancel each
>other out, so that we're back to a level playing field?
>* Do the advantages tend to cancel each other out, so that we're back to
>a level playing field?

I know that for third-party documentation, your audience is much more
defined and more discrete.  A "Dummies" book for WORD is going to be easier
to write than Microsoft's own documentation that ships with the product.
When you do a third-party book, you have a better idea of the audience.  You
also don't have to cover all aspects of the software. You're better off
zero-ing in on a specific feature set, such as macros, automation, etc.

And, let's face it -- it to the company's advantage to have as much out
there supporting the product as possible.  It helps some decision makers
decide to buy the software, if they can see that there are 15 books for
FUBAR 98, and only 2 books for BLAH 98.

I'm not sure if the advantages and disadvantages cancel each other out; in a
lot of ways you're really talking about serving different audiences.

An outside author can also be a bit more honest, shall we say.  Let me just
mention four words -- MASTER DOCUMENTS IN WORD.  An outside author is
probably going to offer workarounds that DO work in his book (for the
following reasons -- to serve the user, to sell more books).


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

Outside, or third-party documentation, can provide more information on
specific features of a product.  It doesn't have to be all things to all
users. It is also, in a way, like shareware (try before you buy).  You can
skim a book at Borders and decide if the software REALLY does what you need
to do.

Third-party docs also reduce costs for the software manufacturers, though
I've yet to see the costs of the software go down...


The above is based on my experience...I've worked on both sides of the
fence, as a staff technical writer at places like Compaq, Microsoft,
Autodesk, etc, and as an author of third-party or supplementary books.

steve arrants


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