TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
"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. http://search.yahoo.com
---
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 http://www.raycomm.com/techwhirl/ for more resources and info.
