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:My doc was too good From:"Jessica Weissman" <Jessica -dot- Weissman -at- hillcrestlabs -dot- com> To:<techwr-l -at- lists -dot- techwr-l -dot- com> Date:Wed, 30 Aug 2006 10:19:46 -0400
Well, fellow Whirlers, it's finally happened. One of my documents was
'buked and scorned for being "too good and too polished."
Before you reply with one of the many possible variants of "why didn't
you ask about the requirements" and "Nothing is good or bad in itself,
it depends on the need" and so on, let me say that I wrote exactly what
MY manager wanted and asked for.
Some background: we are trying to persuade a related vendor to let us
retrieve data directly from their back end instead of using their
carefully packaged and delineated but inadequate-for-our-purposes
services. My manager asked me to write a set of use cases along with an
overview of our architecture and a list of the programmer's requests,
and to embed it in our standard document format.
Which I did, taking two days for the job. Said format includes a title
page, a TOC, a list of figures, introductory material and a list of
When he presented the document to the relevant group for approval, the
marketing guys got all bent out of shape about how it was too polished
and too overwhelming and just didn't look like a communication from a
programmer. We'll ignore the stereotyping implied by the last clause.
So we rewrote the gist into memo format without any superstructure, and
the marketing guys were happy. Of course I could have written it that
way originally if they'd made clear that they wanted a quick memo.
We're saving the original for when we need full use cases, along with
the new Word template for use cases I created along the way.