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: ARE SECTIONS/CHAPTERS ALWAYS NEEDED? From:Tim Altom <taltom -at- IQUEST -dot- NET> Date:Tue, 16 Jul 1996 11:00:00 EST
At 10:17 AM 7/16/96 -0500, you wrote:
> Hello all:
> I am working on a project that involves documentation for a
> production scheduling system. The internal clients want the
> documentation short and sweet.
> We have decided to document by task and not by system function.
> However, tasks seem to be harder to group for this project. No
> significant number of tasks seem to be related enough to put into
> sections or chapters. For instance, I would normally group
> things like adding, changing and deleting in an "Editing"
> section.
> My questions to the list:
> Are sections and chapters always needed, or should I just put
> tasks as main headings?
> Is it enough to just list the tasks in a table of contents and
> have one long continuous piece of documentation.
> The scope of project looks like it could turn out to be 75 or
> more pages (run front and back).
I'd have to echo what so many others have said here: What serves the user is
good, what doesn't is to be avoided when possible. Within that, the needs of
the company you work for have to be balanced on that spectrum.
We usually group in sections just so that users have a hierarchy before
them, but it's not strictly necessary. Perhaps you could group by function,
or by alphabetical order. Or you could avoid the whole mess and go online
hypertext.
With 75 pages or so, I'd guess that the average user would need a
hierarchical structure, if only for warm-and-fuzzies. Maybe the structure
would be arbitrary, but you probably need one of some kind. A list of tasks
as long as 75 pages would probably tax the average user's ability to find
what he wants. At least a structure could clue in the percentage that
catches on quickly, then the rest could be served by extensive
cross-referencing, indices and TOCs.
Tim Altom
Vice President, Simply Written, Inc.
317.899.5882 (voice) 317.899.5987 (fax)
FrameMaker support ForeHelp support
Makers of DuoFrame, giving you online help and paper
documentation from a single parent FrameMaker document.
TECHWR-L List Information
To send a message about technical communication to 2500+ list readers,
E-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot- Send administrative commands
ALL other questions or problems concerning the list
should go to the listowner, Eric Ray, at ejray -at- ionet -dot- net -dot-
