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.
Re: Punctuation lists- an exhaustive scenarios list
Subject:Re: Punctuation lists- an exhaustive scenarios list From:jennysubs -at- mac -dot- com To:Rob Hudson <caveatrob -at- gmail -dot- com> Date:Tue, 13 Oct 2009 13:03:36 -0700
This should be a fun discussion:-).
I like to use bullet lists. I do not labor under the delusion that
anyone is reading my technical documentation for fun. They're trying
to find information. I think they're especially useful for online
writing. I like to use them for things like:
Here's what you can do on this screen:
*X
*Y
*Z
Here's the information you need to complete this task:
*X
*Y
*Z
After looking at a couple web pages that I thought were quite wrong, I
ran into this--which I also think has some problems. Here is the
Chicago "answer" along with my comments:
____________________
Here's the Chicago Style Books slant on bullets:
1. Vertical lists are best introduced by a grammatically complete
sentence (i.e., a sentence that is still a sentence all by itself,
without the help of the list), like the one above, followed by a colon.
2. No periods are required at the end of entries unless at least one
entry is a complete sentence, in which case a period is necessary at
the end of each entry.
3. Items in a list should be syntactically similar.
4. If items are numbered, as they are in this example, a period
follows each number, and each entry begins with a capital letter—
whether or not the entry forms a complete sentence.
>>>>I was taught to never number list items that aren't part of a
step-by-step procedure or otherwise have some need for numbering. This
list should have bullets.
5. Bulleted lists are considered appropriate mainly for instructional
or promotional material and are treated the same as numbered lists in
terms of capitalization and punctuation.
6. A group of unnumbered items each of which consists of an incomplete
sentence should begin lowercase and requires no terminal punctuation.
7. If a list completes the sentence that introduces it, items begin
with lowercase letters, commas or semicolons are used to separate each
item, and the last item ends with a period; such lists are often
better run into the text rather than presented vertically.
>>>>>I would never do this. It just looks really strange to me...as
did the example that Jim presented. I think this format is hard to
read. It's better to just say. "The cloth comes in red, yellow, blue,
and gold." rather than make a bullet list out of it. Or recast the
intro to "The cloth comes in the following colors:" While my
"research" indicates this is correct usage, it just creeps me out.
It's a personal preference and I write around it.
I hope help you as much as they do me.
Jerry Leone (original poster -not me)
I thought this resource was pretty good: http://www.io.com/~hcexres/textbook/lists.html
(I enjoyed that they said to use numbered lists for things that need
numbering and then ignored their own rule....)
And this was interesting: http://www.grammar-quizzes.com/punc-
lists.html -- contains lots of examples of the internal punctuation
list.
Of course, it depends on the context. Short items don't get
punctuation; items that are more than one sentence always do. That's
my general rule of thumb. Also, punctuating your bullet lists
correctly does not make up for bad writing of the intro for the list.
Here's how I'd do these.
> * how to punctuate items in a list when the items are complete
> sentences
Period at the end of each item.
> * how to punctuate items in a list when the items are not complete
> sentences
No punctuation at the end of each item.
> * how to punctuate items in a list that contains internal punctuation
All items get periods at the end. If the internal punctuation is not a
period, see above.
> * how to punctuate items in a list that is introduced by a clause,
> where each list item completes the sentence
Period at the end of each item. Or re-write the clause so it can stand
on its own as a sentence.
> * how to punctuate items in a list that is introduced by a clause,
> where all list items complete the sentence (they are in a series)
List the items with no periods unless they have internal periods.
Recast the information so the intro is a sentence is a better option.
You risk being unclear otherwise.
> * how to punctuate items in a list that is introduced by a sentence,
> where each list item is a complete sentence
Periods at the end of each item
> * how to punctuate items in a list that is introduced by a sentence,
> where each list item is not a complete sentence
No periods unless one or more of the items has an internal period.
>
> I've consulted the Chicago Manual of Style, but it wasn't exhaustively
> prescriptive.
>
> I'd love to see what standards you all follow; I'm going to put
> together a consistent guide for my students.
>
> Rob
>
Free Software Documentation Project Web Cast: Covers developing Table of
Contents, Context IDs, and Index, as well as Doc-To-Help
2009 tips, tricks, and best practices. http://www.doctohelp.com/SuperPages/Webcasts/
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-
