Punctuation

Design System CLI Guidelines
1

Always end sentences with a punctuation mark.

  • Don’t:

See ``juju add-credential aws --help`` for instructions

  • Do:

See ``juju add-credential aws --help`` for instructions.

Serial comma

  • Don’t:

The main tool to build, upload, and develop in general the Juju Charms.

  • Do:

The main tool to build, upload and develop in general the Juju Charms.

2 Likes
2

See ``juju add-credential aws --help`` for instructions.

This raises the issue of how to indicate the start and end of example commands in help text. (I don’t think I’ve seen `` used for this before.)

For a recent CLI project, wherever possible, I put the command by itself at the end of the line, so that it could be copied and pasted without copying any delimiters (or punctuation marks!) by mistake:

Other updates are pending. To install them all: sudo apt upgrade

But in one case this wasn’t possible, because it was important to give two examples to demonstrate different use cases. So I used “” quotes, like this:

Usage: “xyz blend <coffee-variety>” or “xyz blend <gin-variety>”

3

Ah this was me trying to fight with Discourse re-formatting everything I did… what I was hoping to achieve is display just single pair surrounding the command but as it's in a block already surrounded bys I didn’t quite manage.

4

What are our arguments against the use of the serial/Oxford comma?

1 Like
5

There are none. The Oxford comma should be used by all humans in all instances.

2 Likes