Re: Three (basic?) style questions

[Sandy Harris <sandy -at- storm -dot- ca>]

Yosuke Ichikawa wrote:
> 
> These are three, perhaps basic, style-related questions coming from a
> non-native English writer that are probably easy for you trained native
> writers.

I've had no formal training in tech writing, but some in teaching English
to speakers of other languages, several years experience of that, over 10
of tech writing. 

> 1) Capitalization in cross references.
> The manual I'm working on uses full caps for section titles, header level 1
> and 2.

This strikes me as ghastly. Traditionally, one would use "Basic Operation".
I prefer to just use "Basic operation", which strikes me as less formal.

The impression I get from "BASIC OPERATION" is that someone is still
thinking in 1980s terms. All caps stopped being a good idea when laser
printers and Postscript became common.

> When such titles or headers are cross-referenced, I used initial
> caps. For example, a header may read "BASIC OPERATION", while a reference
> to this heading would currently read; see "Basic Operation", page xx.

I'd probably have "fixed" the section heads, changing them out of all-caps.

> I felt the header written in all caps within the body text seemed too
> strong, emphasised unnecessarily , and consistently used initial caps for
> such cases in this manual.

I agree.

> But I should have been more conscious about my
> choice and checked with my client first. Now my client wants me to change
> all such references to all caps, at a very late stage in the production
> process, and I want to avoid the change if I can (as this also affects 8
> other translated languages, and we're not using automated cross references).

I think this is a case where "the customer is always right". He seems obviously
wrong to me, but in your position I'd give him what he wants.

What format is the doc in? If it is readable as text, or can be put into such
a format (e.g. for Frame, dump as a MIF file), then something like the Unix
'sed' stream editor or a little Perl script should automate this nicely. 
Mail me off-list if you need help with that.

> Question;
> Is it incorrect style-wise to use initial caps to refer to full caps headers?

Consistency is good. If you must use full caps, then referring to them that
way makes sense.
 
> 2) Reference to other subheads within the same page.
> When refering to other subhead withing the same page, I write, for example;
> see "Basic Operation", below (or, above). This manual has two columns in a
> page, and the subhead refered to as "below" or "above" is often
> *physically* found to the right or left, and (you guessed it) my client
> suggests changing it to "right" or "left".
> My presumtion was that when refering to other sections in writing, you can
> use "below" or "above" regardless of physical location.

Yes, including references to something several pages away.
 
> Question;
> Should I use "right" and "left" in such cases?

Absolutely not. "below" and "above" are the standard terms.
 
> 3) Bulleted list question.
> Right now I have a passage like the following;
> "Do so and so if;
> $B!&(B blah blah blah, or
> $B!&(B such and such."
> My client doesn't like the ", or" after the "blah"s and wants me to change
> it to a full stop.
> I would like to keep it if it's acceptable style-wise, since it's clearer
> that the two cases together cover all the cases to do "so and so", leaving
> no other case to do so.
> 
> Question;
> It is incorrect style-wise to use a conjunction at the end of a bulleted
> list item to connect to another list item?

That style is quite common, but I don't like it.
I'd use:

Do so and so if any of the following conditions applies:
	blah, blah
	such and such

or, perhaps better:

If any of the following conditions applies:
	blah, blah
	such and such
then do so-and-so.

In either case, consider emphasizing "any" with bold or italic.
  
> No, unfortunately neither my client nor my company has a clear style guide,
> and I'm pretty much on my own. When I have a style related problem, I
> consult The Chicago Manual of Style, but I wasn't able to find anything in
> this case. Please inform me if you can think of right off a book or a
> website discussing any of the style matters mentioned above (or, an example
> of such writing styles acutually being used, if any) so that I can show it
> to my client.
> 
> It frustrates me both that my client never brought these matters up at the
> first and second draft but on the third draft, *and* that I can't
> confidently say that I'm correct. My client is not at all an expert on
> English, but of course, I can't say that I am myselft, never having
> received formal education on writing style.

You're doing awfully well for a non-native speaker. Having taught ESL, I'm
hyper-sensitive to various style oddities in non-native writing, and I see
none here. My advice to your client here would be to trust your judgement
on such matters.

> Of course, I'm certainly
> willing to learn and change what is not correct. Hopefully, our client and
> I will settle this for good, and won't have similar problems in the future.

The British Council are the British government's educational and cultural
organisation overseas. They run the largest English language training
operation on Earth, and do consulting on related matters. When I worked
for them (early 80's), they were just starting an English-language
operation in Japan, emphasizing consulting to industry rather than
straight teaching. Talk to them. At the very least, they'll have a
library full of reference material.