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.
Subject:A sad tale and true (LONG) From:Graham Dowden <Graham -dot- Dowden -at- RA -dot- PAD -dot- OTC -dot- COM -dot- AU> Date:Mon, 27 Apr 1998 15:36:49 +1000
Matthew Bin <mattbin -at- HOTMAIL -dot- COM> told a long tale of a unhelpful former
employee, and his buggy system with minimal documentation:
> So my question is, how does one approach a situation like this?
Your source of information and their usefulness are:
1. System developer - You can try and gain his respect but if he doesn't
want to co-operate he doesn't have to and you should direct your energy
into something more productive.
2. His "System Document" - Use it for what it's worth, tested against
the real system, then forget it.
> 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
If you want to argue, fine. If you want to get the system properly
documented, forget it.
3. The system as it is - The best source of information, although
old unused components may be mixed with the current working
components. If it is being continually modified, this will be very
hard to determine. There may be a support or helpdesk person
who knows about it and can be useful.
> The big problem is that the consultant wrote a "System Document"
> The whole thing has this smug and snarky tone, and believe me, it's a
> true rendering of the author's voice.
You think that's bad? Here is the *total* verbatim help text supplied
with an AUS$ 7M system for a major Australian company:
% cat NoHelp.help
#topic:No Help Available
Dear System Manager,
It would seem that the sponsors of this system have been rather lax
when it came to providing help to you in your hour of need. After
all, you must be pretty desperate to have gotten this far. The
delivery of help data is the responsibility of the Company
organisation and not of us humble developers.
Below in the topics area you will find some names of the people
who are responsible for the lack of help text. We suggest you
work your way from the top to the bottom, as importance increases
at the same rate as your irritation. This should result in some
pretty good fireworks by the time you get to CEO.
In the meantime, just pretend that you are enjoying yourself.
Person and the gang
> Anyhow, any suggestions or similar stories (with happy endings, I hope)
> are welcome. Thanks in advance for the help.
I am now documenting the above system from the code up. It has taken me a
while to get my head around it, but it will be worth it in the long run.
dowdeng -at- nms -dot- otc -dot- com -dot- au