A sad tale and true (LONG)

[Hope Cascio <hope -dot- d -dot- cascio -at- US -dot- ARTHURANDERSEN -dot- COM>]

Matthew,
I've never been in this exact situation, but in one similar enough to offer
this advice: pump and grill (nicely, of course) the folks who have to work
with this machine.  Their combined knowledge of how the system works should
fill out the document almost completely, and where questions remain, you
may be able to try the "what does this button do" approach until you know
how all of it works.

Good luck,
Hope Cascio

-----reply separator----

Matthew Bin wrote:
I'd like to share a recent experience of mine with the group here.  I'd
appreciate any comments and suggestions concerning how I might deal with
such situations better in the future--I'm sure it's not an isolated
case.
I was contracted to write system and user documentation for a system put
in place about three years ago at a government ministry.  The person who
wrote and installed the system was an employee of the government for
about 15 years, but was laid off in the last couple of years and is now
hired back from time to time as a consultant.
The real problem is that this person is the only one who really
understands the system.  The users--including the system officer--were
given NO training, and no user documentation exists.  What's more, many
of the "features" in the system work badly, work in unexpected ways, or,
very often, don't work at all.
Thus, I have very little in the way of resources when it comes to
gaining information about this nightamre.  The only one who knows
anything is the consultant, who is rather bitter about losing his job,
apparently, and is not inclined to be very helpful.
The big problem is that the consultant wrote a "System Document" when he
"finished" the system.  This consists of nineteen pages of information
about the system, which, when it is written in understandable English,
is full of speculations, excuses, and snarkiness.  I give you some
examples:

     "[The ministry] has purchased Cold Fusion version 2, but due to
lack of time, has not been implemented.  The past intention of switching
over to Microsoft Information Server and dropping the Purveyor http
service in order to utilize Visual Basic Scripts never materialized due
to lack of time, but would have allowed us to dynamically create an
Access MDB application custom populated with extracted data for field
laptop PC work, and later file upload and database synchronization."
     "Table and record level security is non-existent since the
[application] group could not agree on restricting functions for some
users."
     "The Query-by-Form methodology was deleted in Access97 by
Microsoft.  This required the generation of our own Query-by-Form
methods.  A routine was found that automatically generates a crude form
for further alteration."

The whole thing has this smug and snarky tone, and believe me, it's a
true rendering of the author's voice.  I probably need not add that
there are only a few headings in the document, and no organisation
beyond these headings (ie no TOC, no apparent structure, no multi-level
headings, etc).
My problem is that the gent who wrote this--which is, I readily admit,
neither better nor worse than any other documentation written by a
developer--does not see the need for another system document.  He feels
that no one reads the documentation anyway (wonder why that is?), and at
any rate his is more than accurate--come on, he worked on this thing for
a week!  He seems to resent the fact that I am re-doing the work he did
before.
My two short conversations with him gained no information--they managed
to circle mostly around how futile my work is.  I tried to ask questions
mainly about things he hadn't bothered to put in his document, but which
were determined necessary (by others, not myself); he dismissed them as
unnecessary.  I said nothing at all about his own documentation's
weaknesses, but tried to indicate that I was adding to the fine work he
had already done; he refused to see where his document was not the
gospel truth on the subject.
So my question is, how does one approach a situation like this?  What
could I have done to better deal with this rather embittered
pseudo-writer?  What strategies do those on this list use to combat this
sort of territory-marking?

One conclusion I have come to is that one must have a THOROUGH knowledge
of the older document, so that you can point out EXACTLY where problems
exist; when he said "I already wrote about that", I should have been
able to say "but you didn't say this, or that."  The reason I was not so
prepared was that I found it difficult to understand the content of the
document and apply it to what I knew of the system.
Anyhow, any suggestions or similar stories (with happy endings, I hope)
are welcome.  Thanks in advance for the help.
Matthew Bin
Technical Writer
NeoDyne Consulting, Ltd.
Mississauga, Ontario