My doc was too good

["Jessica Weissman" <Jessica -dot- Weissman -at- hillcrestlabs -dot- com>]

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

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.  

Jessica Weissman
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

WebWorks ePublisher Pro for Word features support for every major Help
format plus PDF, HTML and more. Flexible, precise, and efficient content
delivery. Try it today! http://www.webworks.com/techwr-l

Easily create HTML or Microsoft Word content and convert to any popular Help file format or printed documentation. Learn more at http://www.DocToHelp.com/TechwrlList

---
You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot- 

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40infoinfocus.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to lisa -at- techwr-l -dot- com -dot-  Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.