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.
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
