2 weeks!

Subject: 2 weeks!
From: Geoff Hart <ghart -at- videotron -dot- ca>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Wed, 05 May 2004 17:23:56 -0400


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

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.



References:
2 weeks !: From: dan . gallagher

Previous by Author: Hiring a technical editor?
Next by Author: Shift in job profile, please suggest?
Previous by Thread: Re: 2 weeks !
Next by Thread: RE: 2 weeks !


What this post helpful? Share it with friends and colleagues:


Sponsored Ads