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.
Ian Saunders wondered: <<Do the chapters/appendices in User Guides,
etc. have to have numbers and letters?>>
They don't require them, but they often benefit from them. Among other
things, everyone is familiar with the meaning of "chapter" and the
associated numbers, and this approach therefore provides a familiar
schema readers can use to understand the document structure.
I find that the numbers or letters help me to position myself within
the larger body of documentation in two very helpful ways: First, they
provide an indication of how much material has come before (how many
sections). That often tells me, particularly when the documentation is
designed to build sequentially on previous concepts to teach new
concepts, how much material I should probably understand before
confronting the new material. That's more true for good third-party
books (e.g., the O'Reilly and "For Dummies" series) than for most user
manuals.
Second, it's much easier for me to find a cross-reference ("see
chapter 12") by flipping pages and skimming through the headers than
it is to have to read the full text of every running header (i.e., to
see when the header changed) and compare those words with the words in
the cross-reference, particularly when (i) the chapter title is long
and (ii) it's very similar to other titles (which is often the case).
Both comments also apply to looking up the page numbers in the table
of contents: easier to know whether I should start near the first page
or the last page of the TOC to find the chapter I'm seeking.
<<I was taught that they do, but understand that there a trend to move
away from them. Is this true?>>
In printed documentation, as noted above, I find the numbers very
helpful. In online documentation, they're less useful because none of
the justifications for numbering (except for seeking a title in a
table of contents) remain strongly relevant: there is usually no
"before or after" for chapters (topics), and where there is, the
relative positions are defined by a browse sequence or hyperlinks. In
addition, you'll only ever skim the headers in really badly designed
online docs because all cross-references should be either hyperlinked
or easily reached via the search tools.
For documentation that is designed to be used online, but that is
incorrectly formatted as if it were a printed manual, things get more
complicated: you get all the disadvantages of both media, and have to
find ways to overcome those disadvantages by using the advantages of
each medium.
------------------------------------------------------------------------
Geoff Hart (www.geoff-hart.com)
ghart -at- videotron -dot- ca / geoffhart -at- mac -dot- com
------------------------------------------------------------------------
Effective Onscreen Editing: http://www.geoff-hart.com/books/eoe/onscreen-book.htm
------------------------------------------------------------------------
ComponentOne Doc-To-Help 2009 is your all-in-one authoring and publishing
solution. Author in Doc-To-Help's XML-based editor, Microsoft Word or
HTML and publish to the Web, Help systems or printed manuals. http://www.doctohelp.com
Help & Manual 5: The complete help authoring tool for individual
authors and teams. Professional power, intuitive interface. Write
once, publish to 8 formats. Multi-user authoring and version control! http://www.helpandmanual.com/
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
