2 weeks!

[Geoff Hart <ghart -at- videotron -dot- ca>]

Dan Gallagher reports: <<My employer has been developing a new 
multi-processor controlled comm. box for over a year now. I repeatedly 
asked and prodded them regarding my documentation duties to no avail. 
I've tried to talk with developers and engineers about the product 
during it's development to try and learn about it.>>

I hope you have documentation for this. Rule #1 of working for others 
is "always cover your ascii". If not, you may have a hard time proving 
that you've been doing this. Make sure you can account for your time 
over the past year, and based on what you've accomplished during this 
time, come up with a realistic estimate of how much manual you can 
typically create per day of work. (Don't forget to include review and 
revision in that estimate--not just your first draft times. Others have 
mentioned the Hackos "8 hours per page" figure; I haven't read her 
book, but I'll bet that includes multiple reviews--SME, developer, 
editor--not just the writer's time.)

<<Now I get this email from my boss's protoge saying they need a new 
manual for this very complex box in two weeks. I don't think I can 
produce a manual for this thing in two weeks.>>

Have you been talking to _your boss_ during this past year? If the 
protégé has been your only point of contact, you've got a potentially 
disastrous political situation on your  hands. That person may have 
been ignoring you and suddenly realized they have no docs; if you try 
to tell this to your boss, someone's gonna catch a lot of 
flack--possibly the flunky, but more likely you because the boss 
doesn't know you exist. Plan accordingly. (And if this is indeed the 
case, a lesson for the future: always go right to the source. Never 
rely on the middleman to carry your message reliably.)

First thing to do _now_ is talk directly to the boss, without 
intermediaries. Find out how realistic that 2-week estimate really is: 
if it's 2 weeks until they release the product to manufacturing, it may 
be a month before it's ready to ship, and that gives you much more time 
to create your docs. Always remember that "when they want it" often 
bears little resemblance to "when they really need it". It may be 
possible to produce nothing more than a 'getting started' manual, but 
if it's another month until the product actually ships, you've got a 
month to put a PDF of the manual on your company Web site.

Based on the numbers I suggested you collect (see above), tell them 
what you expect to be able to accomplish in the actual time period 
allotted to you, and ask them to prioritize what parts of the manual 
they want you to create during that time period. Parcel out the 
remaining days to the highest-priority items. Think triage: what is 
essential, what would be nice, and what can you live without.

When you start writing, think minimalism: write as concisely as you 
can, even to the point of being telegraphic. It's more important that 
the crucial information be present and correct than it is that it be 
elegant. Give the reader what they need to know, with no polish or 
flash. Add the niceties later, as time permits.

Don't tell them right now, but you can probably do much better than 
this preliminary estimate* if you can leverage any existing material. 
For example, it's easier to edit a functional specifications document 
into a reference manual than it is to write that manual from scratch. 
Similarly, you talked about "multi-processor" control. Can you obtain 
any existing manuals for those processors and boil it down or include 
it unedited in the manual? Every little bit helps.

* Rule 17 of surviving in a Dilbertian workplace: Always tell them 
it'll take longer than it'll really take you. When you do more than 
promised in that time, or finish early, you look an awful lot better 
than anyone expected. Don't provide ridiculous estimates, though; if 
you do it in half the time, all they'll believe is that you're lousy at 
estimating or know how to lie about deadlines.

<<I find it somewhat inequitable that everyone on the team had 
unlimited time to work on their parts, but then I get two weeks. Pardon 
me but I'm a little ticked off right now.>>

Welcome to the carefree world of software/hardware development. I just 
fired a client because they're starting to work this way, and I could 
afford to ditch them in favor of other clients with more of a grasp of 
reality. Had I been employed, I wouldn't have had that option. In any 
event, take a long hard look at yourself in the bathroom mirror before 
going to talk to anyone: it's okay to be pissed off, but it's rarely a 
good idea to let anyone know just how mad you are. Calm and rational 
carries the day; angry usually doesn't.

--Geoff Hart   ghart -at- videotron -dot- ca
(try geoffhart -at- mac -dot- com if you don't get a reply)


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

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