TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:RE: Are my docs un-useful? From:"Giordano, Connie" <Connie -dot- Giordano -at- FMR -dot- COM> To:TECHWR-L <techwr-l -at- lists -dot- raycomm -dot- com> Date:Wed, 24 May 2000 17:16:33 -0400
I'd bet you most of us have seen the chaos that results when sales promises
something that development never knew about, and when project managers don't
map out the scope of the project.
When I ran into similar challenges, I found that the sales VP had been
incorporating a general software description into the sales contract that
came nowhere close to anything defined in our project documentation or
design specs. I gave him a list of module descriptions that I used in an
overview section of a Getting Started manual (this application had
approximately 15 major modules, with 1-5 submodules in each module). He was
thrilled, and they were incorporated verbatim.
Next, I made sure that the sales contract and Scope of Work document
outlined what documentation was to be delivered when, and how it was to be
used--including a piece that stated that any module customized to meet the
client's specific needs would not be custom-documented unless they paid an
appropriate amount. That occurred because the company never did a written
test plan, and six weeks prior to beta delivery I had to pull together 2500
pages of user documentation to be used for acceptance testing, a project on
which a 7 figure check was resting. I did it by using proper project
management techniques and giving non-writers a crash course in writing user
doc, but it was far from what I wanted to go out the door. Never saw a
bonus, barely got a thank-you, and I left a week later.
My advice: make sure the sales managers understand the importance of
including documentation specifics in the sales contracts. Make sure the
project manager understands the full impact of a Scope of Work document.
Suggest (emphatically) that the SOW should be delivered (probably by the
project manager) prior to the actual start of development work, so there
aren't any accusations about why a particular piece was or wasn't delivered.
And yes, you should be fully aware of client expectations prior to
delivering and signing off on an SOW. The SOW also gives you and the client
an idea of who the audience(s) for the application (or specific parts of the
application) is, and what documents would then be required. If the client
still doesn't read it, not your problem. You did what the contract
It sounds like sales and project management need some warm fuzzy sessions to
make sure they're working together to meet client expectations.
From: anonfwd -at- raycomm -dot- com [mailto:anonfwd -at- raycomm -dot- com]
Sent: Wednesday, May 24, 2000 4:56 PM
Subject: FWD: Are my docs un-useful?
[snip] Here's my dilemma:
My audience often does not think they need my docs, but my project manager
thinks they do.
it seems like some of our documents are substitutes for a
good, clear understanding with the client (i.e., we use our Vision/Scope
document to explain our project methodology, but it is delevered after the
project has already started and does not seem to get read.)
[even more snippage]
Now, this makes sense to a point,
but after reviewing some of thse docs with clients they respond with "I
paid for this?/Why did I want this?"
[final snippage] What can I do to help make
sure clients want what they need to have a successful project?
I'm wondering if we need to spend more time soliciting clients'
expectations/ requirements pre-kickoff, so that we understand what they
expect during the project. Understanding their expectations as far as
etiquette/protocol seems like it would lead to a smoother project.... but
I don't see the "pre-contract" client; our sales managers do...
Any advice from people who've been in this type of dilemma?