In this post, I explain why slashes should be avoided, and how to use them properly in case they make sense.
A recurring issue I often notice in pull requests is the use of slashes when enumerating aternatives. Examples found in the cert-manager project:
cert-1
using an
ACME / Let's Encrypt issuer.The blog post And/or: Slash the Slashes nicely explains my point of view on slashes in the context of technical writing:
Slashes are far too common, and almost always betray a lazy thinker; by yoking two words together with a slash, the writer tells us the words are related, but he or she doesn’t know how. Replace the slash with ‘and’ or ‘or.’
The U.S. General Services Administration's Plain Language Guidelines also discourages the use of slashes.
In the following example, the reader may not understand whether the conflict applies simultanously to the minimum and maximum policies, or if it may conflict with either one:
In this second example, the reader may incorrectly think that the field must be set to "null" to be considered as "not set". Here, it is preferrable to repeat the verb "set" to make it clear that "not set" and "null" are two separate possibilities:
Another nitpick I also have is the improper use of spaces before and after slashes. I often see things like:
Looking reading Grammarly's How to Use Slashes in Writing.
When a slash signifies alternatives between only two words, don’t use spaces before or after.
Since SSL and TLS are single-terms, we do not need to add spaces:
For multi-terms, it is often clearer to add aone space before and one space after. In this case, I'd suggest not using a slash. Instead, use a word to introduce the alternative.