Re: Responsibility

Subject: Re: Responsibility
From: Andrew Plato <gilliankitty -at- yahoo -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Thu, 22 May 2003 22:21:33 -0700 (PDT)

"Darren Barefoot" <darren -at- darrenbarefoot -dot- com> wrote in message
news:199257 -at- techwr-l -dot- -dot- -dot-

> Management has made it clear that the developers are responsible for
> verifying the correctness of our docs. At the best of times, obtaining
> document reviews is difficult. In fact, for every document we send out
> for review, I'd say 20%-30% of it is actually returned with comments.

Those are horrible numbers. When I did tech writing there was always a 100%
return. However, I also forged close working relationships with the developers
and never once relied upon management to make my case for me.

I would say that if you're getting a 20% to 30% review response, there is
something wrong with your tech pubs group.

> For the writer to know that everything is in the manual and correct, a
> number of factors have to converge:
> * The design spec has to be adhered to or, if it's not, everyone needs
> to be notified of the changes.
> * A small window of opportunity after the final build is stable to test
> and complete last minutes documentation.
> * The writers have to have available time to test the product, verifying
> that all the features and in place and appropriately documented.

If the writer has an intimate and comprehensive understanding of the technology
and the industry, then design specs, beta builds, and testing time become
merely validation points and not the start points for a project.

> I've worked in and for several start-ups, and this has never happened.
> That's fine--heck, I prefer this environment. The reality for me has
> been this: a writer can't KNOW that the information in their docs is
> complete and accurate. Maybe things are different at Microsoft or IBM or
> whatever, but for me, what goes into the manual is my best guess.
> That's why we depend upon a developer review to verify our best guess.
> How else can we do it?

Possess an intimate, technical understanding of the product, technology,
platforms, industry, and marketplace. Then you aren't making "best guesses"
you're making highly informed decisions. Heck, you might even achieve TechDoc
Zion, where developers actually follow the tech writer's lead. I have been to
Zion and its a fun place. Just make sure you get in the door before the 314
seconds are up.

> I imagine you'd advocate a world where the writer knew as much as the
> developer about the product. While I agree with this in principal, it's
> not practical. I try to learn as much as I can, and think I have a
> pretty good grasp of things, but I'm never going to replicate the
> knowledge of 20-odd developers (or, at least, I'm never going to write
> anything if I spend all my time learning). Thus, we must rely upon
> developers to validate our docs. Cheers. DB.

I advocate a world where writers make content accuracy their first, second, and
third priority, well ahead of methodologies, grammar, and just about every
other STC seminar topic. 80% or more of a writer's effort should be squarely
directed at learning technology, testing features, and producing material based
on the writer's own knowledge. SMEs should be used as a sounding board and to
validate the writers own knowledge.

Andrew Plato

Do you Yahoo!?
The New Yahoo! Search - Faster. Easier. Bingo.


Robohelp X3, from eHelp, lets you quickly and easily create
professional Help systems for all your Windows and Web-based
applications, including Net.

Order RoboHelp X3 in May and receive a $100 mail-in rebate, PLUS
free RoboScreenCapture and WebHelp Merge Module.

Order RoboHelp today:

You are currently subscribed to techwr-l as:
archive -at- raycomm -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 for more resources and info.


Previous by Author: Re: Responsibility
Next by Author: Re: Responsibility
Previous by Thread: Re: Responsibility
Next by Thread: SURVEY: Developer Response Rate (RE: responsibility)

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

Sponsored Ads