2

There is a small set of style rules which can make text ambiguous. This is usually not a problem in books, where the ambiguity is not a big deal, but could be a problem in technical documentation.

One of such rules is that full points and commas should be put before the closing quotation mark:

In US practice, commas and full points are set inside the closing quotation mark regardless of whether they are part of the quoted material.

Waddingham, A. (2014), New Hart's rules: The Oxford style guide, p. 163.

Occasionally, when writing technical documentation, I plainly violated this rule to avoid the ambiguity. For instance, instead of:

To view the blocks “M+,” “TX,” and “B-,” authenticate through a service account “cron1,” using the password “Ge:sa#zsY3OMEb,cBXqw-5h/0Z.”

I would write:

To view the blocks “M+”, “TX”, and “B-”, authenticate through a service account “cron1”, using the password “Ge:sa#zsY3OMEb,cBXqw-5h/0Z”.

Otherwise, most users would simply copy the password with the dot, and would have no idea why it doesn't work. This being said, they won't have any ambiguity regarding the account name, but they might hesitate when it comes to the names of blocks.

Violating the rule from time to time, and following it the other times, doesn't seem to me like an ideal solution:

  • It is inconsistent.
  • It looks wrong. When I read it, I have to remember that I violated the rule on purpose.
  • It forces me to think, instead of blindly following a basic style rule.

Is there a better solution?

  • do you have a chance to style the text? – Mike M May 20 at 17:42
  • Using style such as “To view the blocks M+, TX, and B-, authenticate [...]” is indeed a good solution, when available. Let's say formatting is missing or minimal (i.e. bold and italics). – Arseni Mourzenko May 20 at 17:46
3

Use Code Styles if Possible

Following recognized standards is advice often repeated in UX and this is no exception.

Developers and software engineers are familiar with styles that display code as they can often be found in the documentation they frequently reference:

  • Bootstrap enter image description here
  • Vue.js List item
  • O'Reilly Books (Python) enter image description here
  • Stack Overflow (Java)

enter image description here

Each example includes both a block of code text and a single word/phrase within the documentation text. (It's MultiSelect in the O'Reilly book example.)

Typical Code display pattern includes

  • monospaced font
  • text color treatment
  • a background color (often gray)
| improve this answer | |
  • This, but sometimes I feel like code styles are overused and/or overdone (especially when they have that very distinctive background and thick padding). In your Vue example, it feels like vue-cli would be best left as simply monospaced as in O'Reilly, or as 'vue-cli' or vue-cli – it's not actually used as an input example, only as a proper noun, so the current "chip" style is more distracting than useful. – user1686 May 22 at 10:56

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.