Re: dispensing with documentation reviews

["Ned Bedinger" <doc -at- edwordsmith -dot- com>]

----- Original Message -----
From: "Ann Pai" <apai -at- kc -dot- rr -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Sent: Thursday, May 27, 2004 9:36 PM
Subject: dispensing with documentation reviews


>
>I may be asked to "wrap up
> whatever I have" and send out the documentation as is. This
includes a help
> system, user's guide, and setup guide. Because our other writer
is facing a
> similar situation, it appears to be a trend:  it's okay to send
out
> unreviewed or even incomplete documents as long as we label
them "early
> release."
>

Yow.  All I can figure is that this customer must be very
integrated, at a technical level, with your organization. IOW, I
suspect that this small customer base of early release sites
probably has been the driver in defining the program requirements
and implementation details.  As an early release site, they are
fulfilling some sort of testing role for the features they have
requested, and they communicate directly with your engineers.
Such an arrangement is pretty typical, with both parties
preparing for developing and site testing of the pieces of
functionality as they become available.  It sounds like a huge
PITA for the doc team, trying to release documentation that
coincides with the state of each early release.  Let me describe
an example of this that I know of--it might explain or help you
frame the circumstances you're being asked to cope with.  On the
face of it, there are times when the doc cycle gets stepped on
and it is  (professionally speaking) "OK."  If your situation is
something like this, I can identify with your umbrage over being
told to compromise our professional standards, but I would advise
you not to stop on the tracks as such companies have marketing
locomotives that could (in their own minds) knock out the early
documentation in memo.  They don't care that it is
incomplete--nothing is finished yet!

I have seen something similar where the product is essentially
experimental--the releases were more along the lines of releases
for unit/integration testing.  My employer was a start-up trying
to create a foundation of services and features to meet the needs
of a niche market.  The customers were attracted by our marketing
team, who usually oversold what was actually available.  They
would go out to sell, and return to brief the engineers on
impossible features that they had already sold to the customers.
The customers understood the product and knew exactly what they
were asking for, and early product deliveries would go right into
their test environment. Note the difference between this
arrangement, where we pushed off much of the QA to the customer,
versus the (ideal) in-house QA expectations for an established
software product.  I believe that the startup company I worked
for had an understanding with the customer such that the customer
was tolerant of bugs as long as the product was coming along
toward final delivery.  Nice on our side of the relationship, in
that it allowed for quick development cycles, but it made for a
very stressful pace in supporting deliveries.

The management had a marketing view of documentation ("make it
look professional"), and they wanted every documentation release
to be treated as though it were accompanying the final product
release.  The doc team had to work closely with the programmers
to learn the features, and so we spent a lot of time at the
console doing hands-on with the latest version of the product,
capturing screens, testing scripts, verifying it all against what
was supposed to be.  Typical in a start-up, we were always
working furiously to update docs, as even the essential
installation and administration tasks changed a lot, and each
customer had custom features, some of which we were directed to
document for their release.

As writers, we had no prayer of understanding the grand design,
especially because the engineers were a cloistered group who met
daily, behind close doors, working things out.  We got
assignments out of the blue--at any time, we might get tasked
with something that no advance word had leaked to us about,  like
a new Java API for an SDK that had been promised to a customer.
There was an unbridgeable gulf between the engineers and
writers--we got our direction from a documentation manager and
from marketing, who filtered everything to protect proprietary
trade secrets before giving us occasional briefings about the
latest product and the docs they wanted.

If this sounds familiar, let them have it their way and strive
for the affectations of a finished product.  I don't see any
other way to cope.  If the draft stamp is not appreciated, at
least get the software version number onto every page.  It
hopefully indicates an early release.

Good luck, and stay well.  I say that because several of us fell
uncharacteristically ill (as in, never sick like that before or
since) while working at the startup described above. I think
stress may have been in the etiology of those illnesses.


Ned Bedinger
Ed Wordsmith Technical Communications Co.
doc -at- edwordsmith -dot- com
http://www.edwordsmith.com
tel: 360-434-7197
fax: 360-769-7059




^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

SEE THE ALL NEW ROBOHELP X5 IN ACTION: RoboHelp X5 is a giant leap forward
in Help authoring technology, featuring Word 2003 support, Content 
Management, Multi-Author support, PDF and XML support and much more! http://www.macromedia.com/go/techwrldemo 

>From a single set of Word documents, create online Help and printed
documentation with ComponentOne Doc-To-Help 7 Professional, a new yearly
subscription service offering free updates and upgrades, support, and more.
http://www.doctohelp.com

---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit
http://www.raycomm.com/techwhirl/ for more resources and info.