Rethinking the Use of Slashes: A Guide to Clearer Writing

# 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](https://oilpatchwriting.wordpress.com/2010/06/15/andor-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](https://www.plainlanguage.gov/guidelines/conversational/dont-use-slashes/) 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](https://www.grammarly.com/blog/punctuation-capitalization/slash/). > 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.