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:Re: documenting a mess From:Hedley Finger <hedley -dot- finger -at- ericsson -dot- com -dot- au> To:kim_portonova -at- hotmail -dot- com, Technical Writers List <techwr-l -at- lists -dot- raycomm -dot- com> Date:Fri, 12 May 2000 11:07:09 +1000
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
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
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 of developing documentation and training materials
@ Cost of training and supporting software
@ Benefits in reduced times, better patient tracking, etc.
@ Poor quality of software actually increases patient management times,
@ 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 ...
Hedley Finger Technical Writer
Ericsson Australia Pty Ltd
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