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?