Tone of voice

Web CLI Guidelines
1

Be succinct, concise, and clear at all times.

If TTY is present, you may provide contextual information, if you are certain that is beneficial to the user.
Always provide this in the stderr stream.

image
image.png1760×522 27.7 KB

Use passive, succinct sentences when arguments or objects are missing.

  • Don’t:

You need to provide a valid URL.

  • Do:

Valid URL not provided.

Use active, friendly tone of voice when explaining helpful information to the user.

  • Don’t:

Please either create a new controller using "juju bootstrap" or connect to

another controller that you have been given access to using "juju register".

  • Do:

You can either create a new controller using "juju bootstrap" or connect to

another controller that you have been given access to using "juju register".

Use “cannot” instead of “didn’t / couldn’t / wouldn’t / etc”.

  • Don’t:

Connection couldn’t be established.

  • Do:

Cannot establish the connection.

Do not use contractions.

  • Don’t:

Can't establish the connection.

  • Do:

Cannot establish the connection.

2

Thank you posting guidelines @lilyanavidenova - I’ve already started to incorporate some of these points into strings I’m writing today! :smiley:

I’m curious if you can elaborate on:

Three thoughts came to mind reading this one:

(1) It’s fairly common pattern to state “Failed” or “Unable”. E.g. “Failed to establish connection.” Is it desirable to use “cannot” over these?

(2) “Cannot” is present tense and (I believe) the contrary examples are past tense (with subtle differences in meaning). Is it intended to stick to present tense where possible?

(3) The examples also make me think “don’t use contractions” which maybe should be its own guideline somewhere… :wink:

1 Like
3

Ah great!

  1. It is indeed desirable to use “cannot” if the sentence would make sense. In your example, “Cannot establish connection.” will make the sentence shorter, thus quicker to read. Of course there will be times when “cannot” wouldn’t make logical sense and at those, aim for the shortest and most succinct way to word the sentence.

  2. Yes, in my opinion present tense is more accurate when describing something that is not happening from the program’s point of view as opposed to something that is not happening because the user has not done it. E.g. “Cannot establish connection” vs “Valid URL not provided.”

  3. Great addition, thanks! Updating the above guideline! :slight_smile:

4

Our previous guidelines had this

1 Like
5

Thanks Sergio, do you have a link to that previous guidelines?