A sad tale and true (LONG)

[Graham Dowden <Graham -dot- Dowden -at- RA -dot- PAD -dot- OTC -dot- COM -dot- AU>]

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.

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

Happy hunting,
---
Graham Dowden,
dowdeng -at- nms -dot- otc -dot- com -dot- au