RE: Responsibility

Subject: RE: Responsibility
From: "Darren Barefoot" <darren -at- darrenbarefoot -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Thu, 22 May 2003 22:49:45 -0700

> >
> > * 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'm not sure how an intimate knowledge of the product and industry helps
when there's a feature added a week before release. In my experience,
late breaking changes and too-short testing cycles result in new content
being hastily generated and rarely reviewed. In these circumstances,
despite their best efforts, the writer can't KNOW that what they've
created is correct or complete.

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

Ahh, I couldn't get the KeyMaker from QA.

I think this is just a question of terminology here. When I say "best
guess" I mean "the best decision one can make". Call it what you want,
there's no way to be sure without technical reviews.

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

I'm totally with you on the whole content generation front. That said,
as I referred to earlier, I do advocate the "get it done, then get it
right, then get it pretty" school of writing. Better to have something
complete and mostly right than something half-done but all right.

You've said in all in the last sentence there: "to validate the writers
own knowledge." I don't expect SMEs to fill in the blanks in a technical
review. I just expect them to verify that what we've written is correct
and complete. DB.


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.


Re: Responsibility: From: Andrew Plato

Previous by Author: SURVEY: Developer Response Rate (RE: responsibility)
Next by Author: RE: xsl-fo designer
Previous by Thread: SURVEY: Developer Response Rate (RE: responsibility)
Next by Thread: Reviews, was RE: Responsibility

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

Sponsored Ads