Manuals without chapter numbers?

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

Cathleen McIntosh is <<...trying to come up with a way to provide multiple
clients with updates to our user guide. The problem is that each client
receives a version of the same book, but renumbering the book chapters is
always necessary, which is time-consuming.>>

It may be time-consuming, but tailoring the docs to each client probably
repays the effort; after all "custom fit" is better than "one size fits
all". But I'm sure that with a little research, there's some way you could
automate the process (e.g., through a visual basic macro if you're using
Word); someone here with better macro skills could probably provide details.
In fact, if you store individual chapters in separate files, you might be
able to solve the manual labor part of the problem simply by importing the
files, in the correct order, into a single output document; if the style
definition for chapter headings includes autonumbering (perhaps with
something like Word's SEQ field if this feature isn't built into the
styles), each new heading should be able to pick up the correct number
automatically. But let's assume that you really can't spare the time to do
this, or that the confusion of having one client refer to Chapter 7 for
"printing", while another client refers to Chapter 10, poses a serious
problem for tech. support (which it may well do):

<<my coworker had the ideal of eliminating the chapter numbering and
implement a naming convention for sections instead. This would actually work
quite well if we want to use the source files to create online help. The
only problem I see this causing is in the index, where page numbers and
entries would be convoluded.>>

My first reaction, as a user, is that I would actively dislike this
approach; I like to have all my information in one place, in a single
manual, and I've generally found it difficult or inconvenient to find
information scattered across multiple volumes. (Interleaf's manuals used to
drive me nutty that way.) My second reaction, after a bit more pondering, is
that I've grown so accustomed to working with 2-3 manuals per product
(reference, tutorial, and getting started) that it might not be so horrible
after all. But my third reaction (and the third time's the charm, as the
saying goes) is that this might be the basis for a very intelligent way to
divide your documentation efforts between print and online, while greatly
facilitating maintenance of the software as you go through the upgrade
cycle.

I'm assuming (perhaps incorrectly) that all of your clients purchase a core
set of modules, plus a variety of optional modules that meet their specific
needs, and that the possibility of purchasing different combinations of
modules is what leads to the different doc sets. That being the case, it
would seem logical to put the primary information for the core modules on
paper, so that everyone receives the same printed material. This core
information could also include high-level overviews of _every_ module,
whether or not the client receives it. This would serve two purposes: as a
teaser, it might inspire people to buy some of the modules they don't
already have, and as a performance-support tool, it provides information on
the missing modules in the context of an overall structure (i.e., it would
show how each module relates to the other modules). The second component of
this approach would be to put the module-specific information in the online
help. In effect, the printed material tells you what you can do with a
module, and provides a general overview of how you'd do it, while the online
material provides specific details. (In desktop publishing software, an
example might be that the print manual explains the purpose of gridding,
blocking, and structuring a page, followed by the benefits of designing
styles, dropping in the text using frames, and applying the styles; the
online help explains the specific step by step details of each of these
higher-level tasks.) Indexing would be vastly simplified, because the
printed material would have a single comprehensive index, whereas the online
files wouldn't need to refer to the page numbers at all. If you provided
separate help files, with separate indexes, it would be very helpful to
provide a single "index to the indexes" so that users would know which help
file to consult. You could combine this with hints in the printed text that
provide the appropriate keywords to use in the online searches; that's
unusual, but it strikes me as being every bit as helpful as more familiar
cross-references ("see Ch. 10"), since that's really all you're doing
(providing a cross-reference).

<<our idea is to use an appreviation for the section name in place of the
chapter number in the index. Then we could provide a legend at the bottom of
each page in the index for quick reference.>>

That could work well if the abbreviatins refer to manuals, not sections
within a manual; if you're talking about sections within a manual, the
biggest problem becomes figuring out where the sections can be found. For
example, does Ref-123 come before Stan-123 in the manual (because R comes
before S) or does it come after after (because the Standing orders are vital
to explaining the mission, whereas the Reference session is only there to
satisfy some Milspec standard)? In contrast, if the system is based on
separate books, an entry such as Ref-123 tells me immediately which manual
to look in (Reference) and the page number. It might take a while to get
used to this, but it should work just fine.

--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca

Hofstadter's Law: The time and effort required to complete a project are
always more than you expect, even when you take into account Hofstadter's
Law.