Re: Printing an incomplete manual

[Mike Starr <writstar -at- WI -dot- NET>]

Well, here I go again. The problem as I see it is NOT how to justify to
yourself that you're sending out a miserable excuse for product
documentation, but how to pound into management's collective head that what
customers really want and need is a complete product package that includes
comprehensive documentation WHEN THE PRODUCT IS RELEASED!!!

Most companies I've worked with have made a conscious decision that if the
documentation isn't complete, too bad, ship it anyway. This is a result of
marketing saying to management we've got to get something out on the
street, our competition is getting ahead of us.

I lay the blame for all of this squarely at the feet of upper management
who:

1. fail to commit adequate R&D resources to keeping product development
AHEAD of the competition.

2. fail to allow sufficient resources to ensure that documentation proceeds
WITH development rather than AFTER development.

3. believe that documentation is just a side issue, not as important an
element of the product as the GUI.

4. would never even consider delaying the release of a product because the
documentation wasn't ready.

I think that (broad generalization unsupported by anything but my own
intuition) companies that are willing to make sacrifices in the quality of
the product documentation are also willing to make sacrifices in the
quality of the product itself. Those sacrifices would include woefully
inadequate testing, release of product with known, easily correctable
defects and poor design in general.

My overall belief is that those of us in the documentation process must
stop kowtowing to poor management practices and speak up. One of the things
I've always said is that a big part of my job, even though it's not in any
job description, is to be an advocate for the users. We don't serve the
users by giving them poor product documentation.

Mike

Mike Starr                |  WriteStarr Information Services
Technical Documentation   |  Telephone:         414-697-6333
8920 Wilmot Road          |  Fax:               414-697-6334
Kenosha, Wisconsin 53142  |  Email:          writstar -at- wi -dot- net

----------
> From: Chris Betterton <chrisb -at- context -dot- co -dot- uk>
> Newsgroups: bit.listserv.techwr-l
> Subject: Re: Printing an incomplete manual
> Date: Wednesday, April 02, 1997 6:58 AM
>
> > > Melonie wrote:
> > >
> > > I am in a quandry. I wondered if anyone else has experienced
> > > this. I am the only technical writer working for a small
> > > company producing a database which will be used by mostly
> > > computer illiterate individuals. Our software is changing
> > > daily. However, I have been asked to provide a "Limited
> > > Edition" manual which will be printed soon. The manual
> > > will be outdated almost as soon as it leaves the office.
>
> > Kristine wrote
> >
> > My experience with end users who are nontechnical or computer
illiterate
> > tells me that they do not adapt well to change. Typically, the reason
the=
> y
> > use the computer is because they have to use it to get their job done.
An=
> d
> > when the computer gets in the way of getting that job done, they get
> > frustrated. Software that changes frequently will frustrate them
quickly.
> > Why is the software changing so rapidly? Is the user interface
changing? =
>
> Is
> > the functionality changing? Are bugs being fixed?
> >
> > I'm not a cynic by nature, but this situation spells trouble from the
> > software perspective. I think your company, not you, has at least one
> > fundamental problem: a flaw in its development methodology, namely, to
> > release a product before it's ready.
>
> <snip>
>
> > Your challenge is this: change management. You need to be aware of all
of
> > the changes from "release" to "release" so you can document those
changes
> > explicitly for your end users. I would suggest delivering, along with
you=
> r
> > help file, a hardcopy  "Summary of changes" document that addresses all
o=
> f
> > the changes. This document should be short, not more than a page or
two, =
>
> so
> > the end user can quickly get a feel for the changes. The reason I would
> > provide this on hardcopy is because your users are nearly computer
> > illiterate. (All things being equal in another situation except for
> > computer-savvy end users, I would put the summary of changes in a
readme
> > 1st file or some other online format.)
> >
>
> I'm in a very similar situation to Melonie - sole technical writer,
smallis=
> h =
>
> company,
> database products for computer illiterate users (lawyers!), products =
>
> continually
> changing. I'd agree with what Kristine said about there being a flaw in
you=
> r =
>
> company's development methodolgy, because we have the same flaw here, and
=
>
> products often go out with bugs and have to be updated frequently. To
some =
>
> degree this is unavoidable in a competitive marketplace - the pressure to
=
>
> release the product (especially when people have already paid for it) is
=
>
> immense.
>
> I too have been trying to work out ways to manage this change, as
suggested=
>  =
>
> by Kristine. Up to now the focus in my company has been on printed =
>
> documentation, which is a nightmare to maintain. In an ideal world I
reckon=
>  =
>
> the solution is to shift all the information to online help.
>
> The problem is that computer illiterate users they just won't use it.
There=
>  =
>
> was a post a little while ago about the challenges of just getting non =
>
> computer people to use online help, with somebody saying that the
solution =
>
> was education. This was possible in one writer's situation because the
help=
>  =
>
> system was for in house use, so she could train people herself. But =
>
> persuading people to use an external system - now there's a challenge.
>
> I reckon the solution to a situation like this is to strike a balance =
>
> between printed and online material. I find it is the detailed reference
=
>
> type information that goes out of date quickly, and the introductory,
task =
>
> based information that lasts longer. So the introductory information goes
i=
> n =
>
> the printed material, and detailed reference information goes online.
>
> This has the advantage that most of your users, if they're non techies,
wil=
> l =
>
> rarely look at the reference information. As Kristine pointed out, they
jus=
> t =
>
> want to get the job done and don't care how the software works, unlike =
>
> system admin bods. Also, when they're learning the product, many users =
>
> prefer the information to be printed, not on screen - it's more
convenient =
>
> and the concept of having two things on screen at one time can be a bit =
>
> scary.
>
> I'd be interested to know what you decide Melonie, as I still haven't
found=
>  =
>
> the ideal solution.
>
> Chris
>
> Chris Betterton                         =
>
> Documentation Writer                            =
>
> Context Limited
> email: chrisb -at- context -dot- co -dot- uk      =
>
> web: www.justis.com
>
>  TECHWR-L (Technical Communication) List Information: To send a message
> to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot-  Send commands
>    to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
>   Search the archives at http://www.documentation.com/  or search and
> browse the archives at http://listserv.okstate.edu/archives/techwr-l.html
>

 TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot-  Send commands
   to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
  Search the archives at http://www.documentation.com/  or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html