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" wrote
>
> > What you're talking about here is butt coverage. And I
> ain't talking
> > about capri pants.
>
> CYA is without a doubt the most detrimental and least
> productive thing any human can do at their job. If you work
> in a place that is all CYA, then I deeply pity you. I
> personally refuse to play the CYA game. Its lame.
I've seen lots of things in the workplace that are way more detrimental
than covering one's butt (surfing for pr0n, picking fistfights with
co-workers, etc), but that's neither here nor there. While I concur that
covering your butt is lame, it's a part of every job. I'm glad to take
responsibility for whatever I do wrong. I'm just not going to do it for
anybody else.
>
> > When I send out a document to development for review
> > (and I endeavour to ensure there's time in the development schedule
> > for reviewing docs), I include a disclaimer, which reads something
> > like
> > this:
> >
> > Please review the following document for technical accuracy
> and send
> > your comments to us by <date x>. If you cannot review this
> document by
> > <date x>, please notify us as soon as possible. If we don't
> hear from
> > you by <date x>, the document will be assumed to be 100%
> accurate as
> > is.
>
> Good Lord, that is a horrible disclaimer. Where did you ever
> get the idea that silence was synonymous with acceptance?
>
> Based on that kind of thinking, I can post a message to
> TECHWR-L saying "you will all be receiving a bill from me for
> $5000. Failure to respond to my message in 10 days will
> assume you want to pay me $5000." I am sure that would go over well.
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. We
make every effort to obtain complete reviews, but are rarely successful.
We've articulated this problem to management on a regular basis, and
they do what we can. The system is imperfect, but, hey, it's a start-up
and that's most often the way things work.
Furthermore, I never get overly anxious about the review process. I have
faith in what my colleagues and I write, and, heck, it's not like we're
documenting parachutes or anything here. I work in a fast-moving,
constantly-changing marketplace. What I write today is out-of-date in
three months. So, I'd rather have it complete and 95% accurate than
incomplete and 100% accurate.
>
> Silence should NEVER be assumed to mean all is hunky dory. If
> developers are not communicating with the writer its usually
> an indication that:
>
> 1. They are busy
>
> 2. They are unavailable
>
> 3. Your work is so bad, they don't have the heart to tell you that.
>
> 4. Documentation is simply not seen as a priority (see #3).
>
> Silence should NEVER be assumed to mean acceptance.
Well, tough luck. I clearly articulate what our requirements are. If
they can't complete a review in the ample time we give them, all they
have to do is notify us. We have somebody else review it or just put it
in unreviewed. If they can't send us a quick email saying "I have no
time to do this", that's their problem.
>
> > This tends to emphasize to reviewers whose court the responsibility
> > ball sits in. Cheers. DB.
>
> The writer should already KNOW if the information is
> accurate. The developers should merely be confirming accuracy
> and completeness (and communicating their acceptance).
>
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.
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?
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.
---
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.
