0

Here is an except from a technical document I'm currently working on:

After creating a table, ...

  • Set up the caption: [here goes a one-line instruction].
  • Change the measurement unit from inches/centimeters to a percentage: [here goes another one-line instruction].

What is the correct use of punctuation after the introduction sentence in this case: a colon, a comma with an ellipsis, or something different?

Initially I was going to use a colon, but then I read that it is not acceptable:

Don’t use a colon before a list unless the introduction to the list is a complete thought, that is, an independent clause. Remember this rule: if you can’t put a period there, then you can’t put a colon there.

-- https://pressbooks.bccampus.ca/technicalwriting/chapter/lists/

  • 1
    This source seems to use colons for every bullet point list, regardless of whether there is a complete introduction to the list or just a stem. It then discusses two styles (Garner and Chicago) which differ on opinion, but may be of interest regarding capitalisation and full stops. – Smock Nov 8 at 13:24
0

By far the best solution is simply nothing.

And that's what is becoming most common on stackoverflow, where when discussing programming you do this frequently. Why would you possibly need a colon, comma, or dots after the "table"?

If you think about it, the punctuation already here is utterly, incredibly, obvious - heh!

There is a whole line break (!), an indentation (!!), and huge black dots (!!!).

How could we possibly need more punctuation in such a situation?

After creating the table

  • add the line spacing
  • include the memory

and then close the table.

Further, IMO, there is generally no conceivable rational reason for capitals, commas or anything else in the fragments. Like, how much more divided and clear can they be?

Further, IMO, if the whole thing is one sentence it should be one sentence, "as if with commas" as in my example above.

Historically as writing, printing and typographical technology advanced, punctuation advanced with it in rational and relevantly minimal ways. "Indented lists" are a great and extremely popular new writing "concept" (just as say "txt language stuff" is a whole new writing concept). We must choose rational new patterns for the punctuation in it.

When creating tables, there are various considerations.

  • Will it be infinitely scrolling?
  • Are there images?

These issues will shape the code you copy and paste.

Note that I distinguish between dotty lists where it is really one long sentence, my first example above, and dotty lists where each item is a sentence, quite different.

My long-form technical writing on SO has carefully crafted examples of both situations (eg, https://stackoverflow.com/a/23403979/294884, https://stackoverflow.com/a/57912883/294884 etc)

Dotty lists are an absolutely critical part of writing as writing becomes more technical and with more, and more nested, concepts to convey. IMO the two possible structures and the two responsive punctuation modes are as above.

Again in answer to your question, which is a great question, what the heck would you need anything after the "table" for? If you think about it you're using the biggest most prominent possible existing punctuation! You'd never introduce a comma list with some other punctuation indicating that a comma list is coming; even less reason with a dotty list.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.