Re: Article: "Living Documentation"

Subject: Re: Article: "Living Documentation"
From: "Jeff Hanvey" <jewahe -at- lycos -dot- co -dot- uk>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Fri, 4 Apr 2003 14:33:24 -0500


Real world example:

My company produces software for the community banking industry. We have
several different products, some of which are designed to integrate
capabilities.

The recently-passed Patriot Act has required that we provide a means for the
banks to scan IDs of their customers, and store those IDs electronically so
that the front-line people (tellers, account reps, et cetera) can pull them
up and ensure the customer in front of them is really the customer on the
account...the project involved programmers from several of our core groups.
At the enhancement meetings we attended two weeks ago, prior to which my
supervisor had been in contact with the programmers to document the new
feature, we had a clear picture of how the feature worked (we're gearing up
for a major version update beginning in two weeks).

The documentation on this feature is complete, including release notes,
enhancement procedures, and user guides (we're lucky, the 3000+ page user
guide has not been sent to the CD burning company yet, but the other CDs are
finished). We were not involved in testing because the project officially
falls within the bounds of a different group, and we *had* to rely on the
developers for info because we do not have access to the beta project. (BTW,
we exposed several flaws in this feature simply by asking questions - there
is no lack of technical expertise in this department).

Flash forward two weeks, and the imaging engine that runs all of this is
suddenly "not finished," which is going to cause all kinds of headaches -
certain banks can't use it because of software version/hardware conflicts,
others because of file size limitations, and a whole host of problems has
resulted - including the possible fatal error of the new version not working
*at all*. In

So now the documentation is completely incorrect. Is that the writers'
fault?

While I will agree that there are bad writers out there, and that some of
these writers are clever at covering up after themselves, I do not agree
that 99.9% of all errors in the documentation is because the writer doesn't
have technical knowledge. Such a generalization is basically an insult, a
reflection of the attitude that we writers are incompetent baffoons, and a
hold-over from the "tyrant grammarian" mindset that plagued instruction in
English composition in the mid-twentieth century. More importantly, it is
reflection of the "manager" attitude that all workers are just out to screw
the company, to put the check in the bank, take office supplies, and avoid
work by fondling their fonts, tweaking their tools, and piddling with
processes.

It's this black-and-white attitude I take umbrage with. Things are rarely so
clear.

Jeff Hanvey
Augusta, GA
jewahe -at- lycos -dot- co -dot- uk
http://www.jewahe.net


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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/techwr-l

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.



References:
RE: Article: "Living Documentation": From: Beth Agnew

Previous by Author: Re: Article: "Living Documentation"
Next by Author: Re: Article: "Living Documentation"
Previous by Thread: RE: Article: "Living Documentation"
Next by Thread: Re: Article: "Living Documentation"


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


Sponsored Ads