FYI: Replies to bulleted/numbered lists query

[Sean O'Donnell-Brown <sodonnell -at- CCMAIL -dot- WIU -dot- BGU -dot- EDU>]

The request for the information I collected was getting overwhelming, so....

Below is the condensed version of the replies I received to the
bulleted/numbered lists query.


Sender1

I don't know - I've worked for different places & they all seem to do it at
the whim of whoever's in charge,  but please post the list of responses (or
send them to me at burkbrick -at- aol -dot- com).


From 2

Good questions about the penultimate item, etc.

Here's my take on the easiest and most elegant way of dealing with
bullets, learned as a Journalism major, and tested in tech
writing for at least ten years:

You put a bullet on items to indicate that they are independent,
parallel entities. It's a signal to readers that they can read the
items in any order and that they are true and usable independent of
each other. You introduce them with a colon at the end of an
independent clause and then let them stand on their own.

This takes care of a bunch of your dilemmas: bulleted items are all
formatted exactly the same way: same capital letter at the beginning,
same punctuation (or lack of it) at the end.  They are not fragments of
somebody's sentence that may have started many lines above; they are
independent, parallel entities, and they gain strength and meaning from
their uniformity.  If you read one, you know exactly how the
information in the others (within that bulleted list) is presented. You
can almost forget the clause that introduced them.

Under this formulation, it would be silly to use "and" or some final
punctuation, because someone might not need to read the bullets in the
order you happened to arrange them in. Just as important, they should
be able to absorb what's in the bullet without glancing elsewhere.

Of course, you have to watch the parallelism: if you're using gerunds
in one bullet, you'd better use them in parallel situations in its
neighbors.

What you end up with is a microcosm of any good technical writing: a
quickly apprehendable unit that provides the maximum amount of
information for its size, and sets up a comforting, consistent
framework for finding more information if the reader needs it.

Bullets that try to be part of some kind of stretched-out sentence are
like the beginner's "novelistic" approach to tech writing: "By God, the
user will start at the beginning of this manual and read the facts that
I've carefully arranged until he gets to what he needs. If he doesn't
behave like I want him to, and gather each nuance along the way, he
deserves to fail."

An example:



These are a few advantages of the TurboPro:

.  It's fast.

.  It's clean.

.  It saves you money.



A better example, once you see a word repeated:



These are a few advantages of the TurboPro:

. Speed.

. Simplicity.

. Economy.


Sender 3

Gosh, that's a hot button in every styleguide I ever saw.  Every company with
more than two or three tech writers ends up producing a styleguide, to impose
consistency on all its docs, and these questions provoke bitter and emotional
battles.  Look in any corporate styleguide, and you'll get that company's
compromise solution.


From 4

If the sentence before the bullet list is a complete sentence that has
the words "the following" in it, use a colon.

Your choices include the following:

If the sentence before the bullet list is incomplete, use no punctuation

Your choices include

If the sentence before the bullet list is complete but does not include the
words "the following" you can use a colon or punctuate normally.

You have a choice of items. (or :)

If the bulleted items are complete sentences following a complete sentence,
punctuate them as complete sentences.

Your choices include the following:

* Double-click on the item.
* Select the item and click on OK.

If the bulleted items are incomplete sentences, do not capitalize or punctuate
them, even the last item.

Your choices include

* golf balls
* hair ribbons
* apricots

Lists should not be numbered unless a set sequence is implied.


Also from 4

I think they're from the Chicago Manual of Style, but in any case, these
are rules I have encountered in more than one source.


From 5

I'm very glad you raised this issue. I would appreciate you forwarding
any information you receive. I have been paying close attention to the use
of punctuation in magazines like TIME, and noting that they use the bare
minimum whenever possible.


From 6

I am an American workI am an American living in Australia, so I often face
the problem of
what is common in the American punctuation system versus what is common
in the British one. The Australian Style Manual states that lists should
have semicolons "should always be used unless each item consists of one
word or of a short phrase". However, I've noted that people tend to
remove the punctuation when they want a modern look, and this does seem
more used more in the US.
The traditional rule for the preliminary information is that if it is a
sentence, you put a colon and then the listed items can be capitalised.
If you have an open lead-in sentence (e.g "The main points are:") you can
still put a colon (this isn't as traditional) and the listed items are
not capitalised because they complete the sentence.
Hope this helps!


Sender 7

Information mapping of course makes extensive use of bulleted lists.  Their
concept is that the list should read as if it were a sentence; they have
changed over the years, in that they used to recommend a comma after each
bullet point and now suggest a comma + conjunction only after the penultimate
bullet point.

As for the stem, use a colon only if you would use the colon when the listing
wasn't bulleted.  For example, use the colon in the following cases:  A
numbered list or a series of complete sentences.  Or, no colon is required if
the stem sentence *reads directly into the bullet items, *isn't a complete
sentence, or *was written on Tuesday (sorry, ran out of ideas, there!).

You might want to rattle around and see if someone has an Info Mapping book
that can spell all this out more lucidly than someone on cold medicine :-)
Does that help?


From 8

See William Horton's _Illustrating Computer Documentation_ and references
therein.


From 9

We had a style guidelines committee that selected the following as our
rules for lists. Our sources were IEEE, Chicago Manual, and The Gregg
Reference Manual. Although many groups use the Government Guide and/or
Chicago Manual, we prefer The Gregg Manual because it is easier to
understand and seems to cover more of what we do. We do not do newsletters,
marcom, or press releases. We do user's manuals, reference manuals, tutorials,
etc. Also, The Gregg Manual is easier for our foreign (non-native English)
doc groups to understand.

From our style guidelines manual
---------------------------------

basic rules

Use numbered lists only when the sequence of the listing is important,
for example, if the list presents steps that the reader must perform in a
specific order. If sequence or order is not essential, use a bulleted list.
If the main purpose of the list is to define several terms, you may use a
definition list.

---------------------------------------------------------------------------
| correct use of a numbered list      correct use of a bulleted list       |
|                                                                          |
| Before installing the board:        The debugger has three basic modes:  |
| 1. Turn off the PC's power.         * Mixed mode                         |
| 2. Unplug the PC's power cord.      * Auto mode                          |
| 3. Unpack the emulator board.       * Assembly mode                      |
----------------------------------------------------------------------------

  h         Most documents have one simple type of numbered list.
  i         User's guides have an additional type called a step list: the
  n         numbers are preceded by the word "Step" (for example, Step 1,
  t         Step 2, etc.). Use step lists when the list is difficult to
            follow (for example, when the list is spread across several
            pages); otherwise, use a simple numbered list.


capitalization and punctuation

If a list item is a single complete sentence, capitalize the first word
and end the sentence with appropriate punctuation. If a list item contains
more than one complete sentence, punctuate the entire item as it it
were a paragraph. Capitalize the first word of each sentence and terminate
each sentence with appropriate punctuation.

If list items are not sentences or paragraphs, capitalize the first word
in each item but do not use terminating punctuation.

Hope this helps you.


From 10

I would love to have the responses you received about
bulleted and numbered lists.  I have found that there is
no convention on these at all--I see them so many different ways!