Re: Responsibility, blame, managers, and getting the job done

["Deb M." <dm -at- ptrail -dot- com>]

This has been an interesting thread with merit on many sides of the
discussion.

If I understand it correctly, Bonnie's argument highlights the disparity in
working conditions between developers and tech writers. She didn't say this,
but developers do not have to cajole, romance, or feed anyone to get access
to the source tree or any other tools and info they need. It has been my
experience as well that management does not mandate that developers make
time for writers and reviews. In fact, I've never even seen these tasks
included in a developer's annual preformance review. (I'm sure it happens in
some places, but I have yet to work in those places.)

In this particular real world, I don't see why any developer would care a
whit about a tech writer. In this particular real world, tech writers must
cajole, romance, bake, learn technology, and do whatever else it takes.
(It's this part of the job that makes me grateful that I majored in
Journalism and learned how to "get the story.")

So yes, from this point of view, the situation for tech writers compared to
that of developers sucks. There's a quip that goes something like:
Everything that Fred Astaire did, Ginger Rogers also did, except backwards
and in high heels. Metaphorically speaking, tech writers are not "leading"
in this dance.

That being said, reading the list archives will show that many of us
"Gingers" lead anyway. Many of us drive the process as the normal course of
our jobs. In addition to creating the docs (as well as any supporting
methodology), we also suggest usability changes to the UI, catch bugs before
QA/test, and create release notes. We serve as resident note takers,
grammarians, and live dictionary/thesaurus resources. We keep "our"
developers honest with respect to specs, users, and the build. And other
duties as assigned. This is our job (in this particular real world).

I agree with John's entire post, but particularly with:
> Also, since 100% document accuracy is based on
> the state of the product at a
> specific point in time, as soon as the time
> changes, so does the state of
> the product, and hence, the error-state of
> the documentation.

This speaks to the original post in this thread, which was a reference to an
article, written by a tech writer, about creating "living documentation" in
order to preclude time-induced error states.

Here's a real-life example and I know I'm not the only writer on the list
that has had something like this happen. (Note: There are many such
examples. I chose this one because it was relatively short and doesn't give
away any proprietary material.)

There's a half an hour left until the build. My AIM client pops up with an
Instant Message from one of my developers:
Him: UR gonna hate me
Me:  What changed?
Him: The UI
Me: Call me. <number deleted>

On the phone call, I learn that he's changed the little icons in the "tree
pane" of the app. First thought: not a big deal; no functionality is changed
(you just click to expand and contract...not rocket science); the users can
cope.

Oh, but wait -- he's given them some functionality. Depending on the state
of the item/level in question, the little icons change. Unfortunately, it's
not intuitive. No, this wasn't spec'd; it was just something "extra" he did
to make the product better. Y'know, pride in workmanship and all of that.

So, I tunnel into his [Linux] box (thanking appropriate deities for PuTTy),
run his iteration of the app and scope out the changes. I snap screens and
note behaviors. I replace the screen captures in the manual (8) and add two
short paragraphs explaining the new behavior/significance of the icons.

I regen the FrameMaker book, regen the PDF, and regen the HTML help
(thanking appropriate deities that I had the presence of mind to create a
single-sourcing process at the outset of the project). I check my
deliverables into CVS. It's two minutes to build time. Whew!

I took the responsibility for having two unreviewed paragraphs in the doc.

What did I get out of it? A few pints of Sam Adams on this developer and all
the rest of the developers calling me a geek (in a nice way). And a warm,
fuzzy, feel-good feeling that is still with me today.

Of course, it would have been proactive to implement some form of "living
documentation" prior to this event, but then I would have had to buy my own
pints.


 -- Deb
---------------------------
The Paper Trail
Technical Documentation
www.ptrail.com
---------------------------



^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Purchase RoboHelp X3 in April and receive a $100 mail-in 
rebate, plus FREE RoboScreenCapture and WebHelp Merge Module.  
Order here: http://www.ehelp.com/products/robohelp/


   Help celebrate TECHWR-L's 10th Anniversary starting this month!
Check out the contests at http://www.raycomm.com/techwhirl/special/contests/
Happy birthday to you, happy birthday to you, happy birthday TECHWR-L....

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