Three basic style questions revisited

[Bob Buchko <nc_prof -at- yahoo -dot- com>]

Hi everyone, I sent this directly to Yosuke, but I
thought some of you might gain something from it as
well, so I'm posting it to the listserv.

1) Whenever I cross-reference, I always use the exact
same capitalization as the section I'm referencing.
That provides an immediate visual cue for the reader.
I do agree with the other person who's responded so
far that all caps is pretty tough on the eyes, even
for section titles (but, in some cases, what can you
do?).

2) Layouts change (well, the location of items within
a layout changes, anyway), so I always avoid using
space-relational words to describe the location of
passages. Instead, I suggest you use "previous" and
"following". (Ok, I guess they're space-relational,
too, but you get my meaning.) That way, if you add a
section earlier in the manual and the location
changes, you don't need to revise all the "right"s,
"left"s, "below"s or "above"s. Also, I realize some
users understand that "below" and "above" do not
necessarily mean physically below the reference on
that page, but others might not realize that, for
example, the graphic "below" is actually on the next
page.

3) I don't like using sentence-style bulleted lists,
either. My rule of thumb is to always make the lead-in
to the list a complete sentence (not to have the items
complete the lead-in) and to use sentence-final
punctuation on the items only if they are complete
sentences. Of course, you need to make them
parallel.(i.e. If one list item is a complete sentence
and the rest aren't, either change it so it's a
fragment with the same structure or make the rest of
the items complete sentences.)

Let me know if you have any questions or comments.

-Bob




__________________________________________________
Do You Yahoo!?
Get Yahoo! Mail ? Free email you can access from anywhere!
http://mail.yahoo.com/