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.
Thank you, Charles W. Jay, Sandy Harris, Marilynne Smith, Mark L. Levinson,
Bob Buchko, Jane Bergen, David Chinell and Tom Murrell for your valuable
responses. I'm grateful that I got so much positive, encouraging input for
Here is a brief overview, along with what I suggested to my client.
1) Capitalization in cross references.
All of you who had any comment on capitalization of the headers suggested
*against* using all-caps in headers in the first place.
On the premise that the headers are in all-caps, many of you suggested
using all-caps in references for consistency sake, while some of you said
that initial-caps or sentence casing would be okay.
As for the headers, I can't realistically change the case at this time. But
I'll keep in mind that all of you suggested against it next time I get to
discuss manual format with my client.
As for the reference, with my current deadline, I don't want to go through
all the changes unless it's absolutely wrong. I interpreted your replies
(rather conveniently?) in the whole that while one should basically use the
same casing, my original decision wouldn't be absolutely wrong.
I looked at what English manuals I can find after I put up my post and
found that the Adobe PageMaker User Guide Version 6.5 does the same thing
(i.e., all-capped headers but initial-caps in references).
I faxed a few pages out of the manual to my client, explained my views and
the situation, and asked her if she could give it another thought. Of
course, if she still wants upper case in the references, I'll have to do it.
Interestingly, when I looked in the Adobe InDesign User Guide (version 1)
to see if it does the same, I found that Adobe hadn't used full-caps in any
of its headers in the first place, exactly as many of you suggested. They
used sentence casing. Maybe this is due to the fact that the PM manual was
made in 1996 (and, possibly retained the style from an earlier version
manual), while the ID manual came out fresh last year.
Some of you suggested using automated cross-references. This is something
I'll have to look into. Our manual is not very long (30 pages to 60 pages
per language at most) and we don't use a whole lot of references, so we
weren't really pressed for the need. (We use PageMaker for our manuals
--customer's choice--, but we may have to start considering other options
since we hear the product may not be updated in the future. But this is a
whole different story.)
2) Reference to subheads within the same page
Many of you who had any comments on the usage of "below/above" said that it
was okay. Some said that "left/right" were equally okay, while others seem
to suggest they were not. Other suggestions were "previous/following" and
Some of you suggested to avoid using words like "below/above" altogether
and stick with "page xx", so that one wouldn't have to worry about
adjustments when the page changes.
I personally feel a little (not much, but a little) awkward to refer to a
section in the same page like; see "AAAA", page xx. Since the references
typed manually in our case, we can choose to use different words in such
cases. I first thought of using phrases like; see "AAAA" on this page, and
ultimately chose what seemed to me the simplest words. I understand this
would certainly be different if we decide to use automated referencing in
the future (The forementioned PageMaker manual does this on page 91).
I told my client that the using "below/above" would not be wrong, so we can
keep it, or change it if she still thinks necessary.
3) Bulleted list
While no one said that the sentence-style bulleted list is absolutely
wrong, all of you who had any specific comments suggested against it. It is
preferred to keep a parallel structure for the items, and the lead-in
sentence should be changed if necessary to keep this structure.
I told my client just this. I explained my original intent in using "or",
and showed her the necessary rewrite of the lead-in sentence should I take
away the "or".
Some of you gave me a very detailed response. Sorry for the simplification
in this summary (I didn't quote anyone), but I've read all your messages
Again, thank you very very much.
Still waiting for my client's response,