Problems documenting an application?

["Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>]

"Paula" has been <<...tasked with documenting an entire application by
myself.>>

Welcome to the wild and woolly field of software documentation. Take a deep
breath, remind yourself that it's not nearly so scary as you think (but
every bit as chaotic). I always find that the hardest part of doing docs is
getting past my initial "ohmygod... look at all those screens" reaction. A
few suggestions:

<< The client wants each screen as a separate work instruction with a data
entry table for the user to refer to for field entries. My problem is that
this application has SEVERAL screens and I don't know where to begin.>>

Begin by building yourself a list of all possible screens that you'll have
to document. One way to do this is to print out each main screen and each
main menu, then identify each secondary screen that you can reach from the
main screen or menu choice; use a highlighter marker to "check off" each
screen as you print it out and add it to the list of things to be
documented. (Or use a table in a wordprocessor file, or whatever other
approach works for you.) That gives you your total list of work to be done.
Next, spend some time understanding what the audience is likely to want to
do with the software and how they're likely to try to do it; use that
knowledge as your basis for organizing all these screen printouts you've
made. The user's path through the software (based on what they're trying to
achieve) is your best blueprint for documentation; if there are multiple
paths, the solution becomes more complex, but that doesn't change the
overall goal of building a roadmap to the use of the software via your docs.
A list of field names (is that what you mean by "data entry table"?) is a
good idea for the _reference_ part of the manual, but that's in addition to
the task-based information, not necessarily part of it. For that matter, the
reference information probably belongs online, not in print. Can you work
with the programmers to incorporate context-sensitive help within the
application?

<<I have noticed that several screens duplicate so this is causing problems
as well.>>

Not necessarily; in many cases, this simply means that you can reuse the
text you've written for one screen to cover the other screen. Just be sure
that both screens really are identical; if not, you'll have to figure out
the differences and how to account for them in your documentation. If
something is a real problem to document, then it's probably also a real
problem to use, and it's worthwhile trying to gently persuade the
programmers to fix the problem.

<<The client says that they have no program specs to help me>>

Business as usual. I've yet to work from a spec, and though having one would
undoubtedly help, you can get around its absence by being careful and
rigorous in your approach. One thing to be aware of, though: if there's no
spec, then you're probably going to be documenting something poorly designed
that will change right up to the day it ships to customers. You'll need to
immediately establish lines of communication with the developers so that you
know what's going on and can figure out how to cope with the inevitable
ongoing changes.

<<there is no existing help to guide me on what I'm looking at here so I
have to guess what field descriptions mean.>>

That's also pretty common. Since you can't be expected to read the minds of
the programmers, this means you'll have to interview them to figure out the
details. Start building relationships now so that you can gain access to the
people who can answer your questions. And have a look at my recent article
"Effective interviewing: get the story" (Intercom, Jan. 2000, p. 24-26) for
tips on how to get the answers you need. Then come back to techwr-l with
specific questions as you move along and encounter new problems.

--Geoff Hart, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca 
"The paperless office will arrive when the paperless toilet
arrives."--Matthew Stevens