Re: Printing an incomplete manual

[Katherine Graden <kgraden -at- MAIL -dot- DANCRIS -dot- COM>]

I couldn't agree more with Mike Starr's comments about who's to blame for
companies sending out inadequate product documentation.  I have worked for
several large software companies as both a technical writer and
documentation manager, so I've seen the issue from both perspectives:  that
of developers and writers who want to produce the best possible product and
doc as possible, and that of upper managers who think that release dates
are sacred cows.  In my experience, the companies which recogize that doc
quality contributes to product quality (and can even be a competitive edge)
do NOT lose sales to competitors because they postpone deadlines to ensue
completeness and quality.

Additional comments from me are below.

>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.

Release timing may be important, but talented marketers ought to be able to
drum up customer enthusiasm for the products because of good features,
documentation, tech support, etc.  If they can make an upcoming release
sound attractive enough, many customers will wait for it instead of buying
a weaker product that's available now.
>
>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.

I know of cases where megabuck buying decisions were swayed toward my
employers' products because our documentation was more useful than that of
other vendors.
>
>4. would never even consider delaying the release of a product because the
>documentation wasn't ready.

Difficult as it is to do, a doc manager must stand firm when upper
management wants to send a release out prematurely.  If the doc isn't ready
by the agreed-upon date, that's one thing.  But if in mid-cycle marketing
suddenly starts clamoring to push the target release date back two months,
and doing so would leave the doc seriously deficient, a doc manager who
rolls over and does it hurts not just the customer, but his or her doc
staff who have put much effort into developing the best documentation they
can.  Not producing the best documentation possible betrays the ethics and
standards of our profession, and offends anyone who possesses a strong work
ethic.
>
>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.

In one company where I worked, the documentation and technical support
groups worked together to act as user advocates.  When we were pressured to
release early, together we effectively argued that the costs of handling
the extra support calls produced by a buggy product, and the costs of
revising and republishing the doc, would eat significantly into the
projected revenues for the new release.  Pushing the cost button got
management's attention, and they backed down and gave us the time we
needed.  But I think our pushback effort succeeded because it was two
departments standing together to buck pressure from above.
>
>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
>
>

 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