Try   HackMD

Rethinking the Use of Slashes: A Guide to Clearer Writing

In this post, I explain why slashes should be avoided, and how to use them properly in case they make sense.

Avoid Slashes

A recurring issue I often notice in pull requests is the use of slashes when enumerating aternatives. Examples found in the cert-manager project:

  • This diagram shows the lifecycle of a Certificate named cert-1 using an ACME / Let's Encrypt issuer.
  • The username / password authentication is deprecated.
  • Configure an Issuer / ClusterIssuer.

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.

Examples

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:

  • Before: The duration conflicts with the minimum / maximum duration policy.
  • After: the duration conflicts with the minimum or maximum policy

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:

  • Before: If not set/ null, it can only be used within its namespace.
  • After: If not set or set to null, it can only be used within its namespace.

Spaces Before and After Slashes

Another nitpick I also have is the improper use of spaces before and after slashes. I often see things like:

  • SSL / TLS
  • SSL/ TLS
  • SSL /TLS

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:

  • SSL/TLS

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.