Documentation headings and punctuation

🗄️ Archive
1

I was wondering (during the making of boring documentation) what the correct format is for section headers and punctuation on bullet points.

Which heading is correct?

The Quick Red Fox
OR
The quick red fox

Which bullet point is correct?

  • This is a bullet point.
    OR

  • This is a bullet point

I know I could google it, but I like to chat! :slight_smile:

2

Headings: As far as I’m concerned, both are correct, as long as you are consistent.

Bullet points:
This is more complex. In your example, the first one is correct.
However…

  • these
  • are
  • bullet points

Would not have punctuation.

3

Agree with Brian on headings - though there is a US convention on headlines which Capitalises Every Word Regardless Of Context which looks faintly ridiculous in the UK.

The same goes for bullet points; whatever you do, be consistent. Back in my Government press office days, the house style was either

  • Item 1

  • Item 2

  • Item 3
    (no punctuation), or

  • Item 1,

  • Item 2; and

  • Item 3.

I think a lot depends on what you are writing. If you are putting bullets on a presentation slide, punctuation may look over-fussy. If you are inserting a bulleted list in a written narrative report, I would expect punctuation. Others may have their own ideas; but I repeat that consistency is always best.

4 Likes
4

While some people do capitalize every word, that’s pretty unusual (though it’s the easiest to enforce and be consistent about).
The more common US guidelines are to capitalize most words and lowercase articles (a, an, the) as well as prepositions. There are definitely more nuanced versions, but they’re all pretty similar - lowercase for the short words.

In any case, I agree with the other responses that the most important thing is consistency. Pick a style and do it consistently (mixed styles is one of my pet-peeves when I review resumes). Make sure to socialize a style guide within the company if there are going to be multiple authors.

1 Like
5

Thanks for the replies so far. I have always aimed for consistency on documents. And thanks for some of the pointers about US conventions.

6

For the most part both methods are interchangeable.

In my experience of US methods of heading formatting, it’s much more common (but not necessarily exclusive) to capitalize most words but not all as @ernie has mentioned.

I will echo the other responses regarding consistency. When writing reports for people or updating my CV/Resume, I always double check for consistency in my styling.