How much context is enough?

[Geoff Hart <Geoff-h -at- MTL -dot- FERIC -dot- CA>]

Robert Heath reported on <<...a 970-page manual that was
begun two years ago by one author (she left the company late
last year), continued by another author (he picked it up in
September '98, but quit two weeks ago with work left to
do), and...>>

Hmmm... given the track record, it looks like we should be
expecting you to be writing us with requests for resume
advice any day now. Anything you want to share about your
company before we dig into the meat of the question? <g>

<<... the chapters ... detail how different screens in the
application can be used. Each screen receives a brief intro, a
screenshot, procedures for using the screen, and a table of
fields and their descriptions.>>

On the face of it, that sounds perfectly effective, and a
reasonable approach to documenting the application...
provided that there's some kind of overview that explains
how to get to the pages for each screen and why you'd want
to do so. (That is, this sounds like a purely refrence manual,
and if it's being asked to serve as a user manual too, then it
needs some overall unifying structure, such as a task list or
tutorial.)

<<The main content of each chapter, however, consists of a
section entitled "Things you should know," with a bulleted list
of points of info the user needs to know to use the screen.
The whole concept of a "Things you should know" section is
absurd...>>

Au contraire, mon frere! <g> From the information you've
provided, I don't have a really clear grasp of how users would
dive into the manual to get to these chapters, but it seems to
me that they may be entering at the start of a chapter, without
having encountered any other context until that point.
Speaking personally (i.e., not knowing the application or
your audience), I'd dearly love to have the authors provide
me with exactly the context you suggest so I'd know where
I'd landed, what I was doing there, and what I needed to
know to proceed. FWIW, this works very well in textbooks,
and can be made to work well in manuals too. (After all, even
if the context is vital to neophytes, expert users will simply
skip the bullets and dive right into the procedural
information.)

<<to have these "things" in a bulleted list makes the whole
section look more like an outline rather than a polished,
helpful, accessible piece of writing.>>

That's a much more significant problem; a few of my authors
seem to think that bulleted lists are a perfectly acceptable
replacement for well-crafted, effective paragraphs. They
aren't. On the other hand, lists can indeed be effective if the
goal is to list things rather than establish a coherent, logical,
rhetorical structure. Not knowing which is the case, I can't
really speculate on whether the bullets are appropriate, but I
can make a suggestion: establish what level of minimalism
you can safely achieve. For contextual information, there's a
broad spectrum between "write it out long and pleasant so
they're inclined to read it" (full paragraphs) and "minimalism
rules!" (provide just the facts, tersely and with no padding)".
The best choice (or combination of the two) is going to
depend on the audience's needs. Bullets may be perfectly
suitable--or, as you're proposing, a functional disaster.

<<...would you push the deadline even further back... and
rewrite the chapters (all 970 pages of them) so that you could
submit a winner? Or would you simply copyedit, fill in
whatever holes still exist in the content, and do all of the
production stuff to ready it for publication...?>>

There are five words every techwhirler should engrave on the
bezel of their computer monitor: " 'Good enough' is good
enough." The only real answer to your question depends on
another question: is the manual _good enough_ to meet the
needs of its users? If it is, finish it fast using the current
format, polishing and filling as necessary, and get it out the
door... then after you've recovered from the celebration,
begin developing a revision plan based on a clear picture of
the audience's needs. (If you don't know them, take time to
identify them.) If the manual really _isn't_ good enough
(based on audience perceptions, not yours), then you've got
to hold a "crisis meeting" with your managers to explain why
and negotiate alternatives.

Having written all this, it occurs to me to wonder just why it is
the manual isn't ready after two years. Don't the developers
have a tentative ship date yet? (If so, that probably defines
what you're going to have to do much better than whether the
manual is "good enough".) Or are you living in techwhirler
paradise, and they're waiting for you to finish the manual so
they can make the software match the manual?

--Geoff Hart @8^{)}     Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca

"If pro is opposite of con, then what is the opposite of progress?"--Anon. (possibly Richard Lederer
)


 From ??? -at- ??? Sun Jan 00 00:00:00 0000=