Re: documenting a mess

[Hedley Finger <hedley -dot- finger -at- ericsson -dot- com -dot- au>]

Kim:

Perhaps this is do-able.  Usually medical systems are involved mostly in
RECORDING after the fact the events that happen in the real world of the
wards, surgeries, offices, and theatres.  I have no idea of the scope of
this application but make some suggestions based on a real hospital
management system.

First, visit every single window and dialogue and take a screen dump. 
Stick them up on a wall with lengths of string showing the navigation
paths from the home window and menu bar to all the other subsidiary
dialogues and windows.  Bind another set into a book you can carry
around.  The pages can be ordered in the sequence that you travel down a
path to reach a particular screen, so some dumps may be duplicated
several times.  

Get some potential users to work through some common tasks, e.g. admit a
new patient.  Or perhaps you could make this a more formal usability
test.  Make sure some of these users are managers, so they see how bad
the software is, or at least have them present as observers.

Second, is anybody using this application apart from the developer? 
Perhaps you can take these people to the Wall of Screens, then interview
them to get some idea of what all the input forms are.  Later you will
take the bound dumps to the workplace.  They may be able to tell you
what the actual workflow is, that is, the order in which various windows
and dialogues are visited in order to accomplish some task.

Third, the tables must contain various objects (patients, drugs, beds,
theatres, or whatever) and attributes (admitted, back-ordered,
available, booked, or whatever).  For each of these objects there must
be various operations that can be performed (closing wards, dispensing
drugs, or whatever) and the actors that perform them (receptionist,
manager, doctor, surgeon, nurses, cleaner).  So you may be able to view
the raw tables in Access or whatever to extract the objects and their
attributes.  Don't worry about analyzing the SQL or whatever statements
that are manipulating the data.  The basic operations of INSERT, UPDATE,
DELETE, and DISPLAY or PRINT won't tell you much about the data-entry
tasks as the users view them.

The tasks then divide into those involving slowly changing data (sys
admin & configuration) and rapidly changing data (user input).  For
example, sys admin tasks involve setting up the basic parameters (no of
wards, no of beds, medical equipment inventory, admin staff details,
support staff details, nursing staff details, medical staff details). 
The user tasks involve daily, weekly, monthly, and ad hoc operations
(patient discharge, medical examinations recording, drug prescriptions,
ordering cleaning supplies, etc.).

But this is just preliminary scoping.  After you have a handle on how
many tasks to describe, you can then write up a documentation plan.  Get
hold of a copy of Read Me First! A Style Guide for the Computer
Industry, Sun Technical Publications, Sunsoft Press/Prentice Hall, which
has an excellent summary of the topics that should be in the plan.

Then you should follow the recommendations of the other respondents re
the business case for or against the software AND producing
documentation for it: 

COST/BENEFIT ANALYSIS
@ Cost of developing documentation and training materials
@ Cost of training and supporting software
@ Benefits in reduced times, better patient tracking, etc.

RISK ANALYSIS
@ Poor quality of software actually increases patient management times,
etc.
@ High possibility of incorrect data entry exposes hospital to
litigation (always gets management's attention, ESPECIALLY medical
management, even if they are mandarin medicos!)

But I'm sure you are getting the idea now ...

--
Regards,
Hedley Finger   Technical Writer

Ericsson Australia Pty Ltd
Documentation Group
Level 34.108   Melbourne Central Tower
360 Elizabeth Street   Melbourne VIC 3000   Australia
Tel. +61 3 9301 6214   Cell. +61 412 461 558   Fax. +61 3 9301 6199
Email. hedley -dot- finger -at- ericsson -dot- com -dot- au

Hand Holding Projects Pty Ltd   ABN 98 007 418 153
28 Regent Street   Camberwell VIC 3124   Australia
Tel. +61 3 9809 1229   Cell. +61 412 461 558   Fax. +61 3 9809 1326
Email. hfinger -at- handholding -dot- com -dot- au