"stop documenting everything" (was Re: Quick-start guides?)

Subject: "stop documenting everything" (was Re: Quick-start guides?)
From: Michele Marques <mmarques -at- CMS400 -dot- COM>
Date: Tue, 1 Jun 1999 10:17:57 -0400

I agree with Jane, that "everything" does need to get documented,
although I don't usually go to the point of saying what information
should be in a "last name" field (but will document the length of the
field and whether it is mandatory).

I believe that part of the problem (and reason for dispute among us)
is that in an ideal world, large software packages would come with
a reference manual and a "users guide" (or other conceptual and
task-oriented guide) and maybe even a "quick reference guide"
(with the bare minimum and maybe additional common
procedures/fields/etc.). In the real world, most of us barely have
time to put out one of the three above-mentioned documents, let
alone all three. And then we start arguing about which guide we
should choose to create :-)

I opt for reference manuals, but do provide some other forms of
documentation when I can. I also try to start each section of the
reference manual with a brief conceptual overview. Maybe I can do
more if my department expands. Or maybe there will just be more
to document.

- Michele Marques
mmarques -at- cms400 -dot- com

Jane Bergen <jbergen1 -at- EARTHLINK -dot- NET> writes:

> I didn't read the book, but I did read all the pages on the site you
> gave below. I generally agree with him, but differ in a few. One place
> I differ is his suggestion to "stop documenting everything" --- the
> problem with this suggestion is that the alternative is to play a
> guessing game with what the user wants or needs. That's pretty
> subjective analysis. Isn't it better to provide MORE information, with
> the obvious stipulation that it be well-organized and concise, than to
> make generalizations or assumptions about an audience? Of course, if
> you are writing for a very narrow, well-defined audience, this might
> make sense. But in many cases, you really DO need to document every
> field. I've literally seen users stumble over fields such as "Last
> Name"! Rare, true, especially these days where assuming a little
> computer literacy is not so far-fetched.

> ----- Original Message -----
> From: O'Neill, Kate <kateo -at- CINEBASE -dot- COM>
> >Did anyone else read "Computers Stink" by Jack Bellis
> >and think he made a very good point? [most text deleted]

> >But a strength of this book is the group of "action
> >summaries" at the end (and listed on the web at
> >http://www.netaxs.com/~jbellis/stink.htm) for various
> >groups of people, including writers.
Michele Marques
Technical Writer, CMS Manufacturing Systems
mmarques -at- cms400 -dot- com
905-477-4499 x280

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

Previous by Author: Re: XML/SGML Resources
Next by Author: Re: Question: Technical Writing Related Software.
Previous by Thread: ANNOUNCE: Free Download, Macro Magic, Now Available
Next by Thread: Interview Etiquette (was The Interview from Hell!)

What this post helpful? Share it with friends and colleagues:

Sponsored Ads