IMPORTANT: This topic is about bad shortcuts. However, all of the following examples contain discussions of multiple subjects—not just bad shortcuts. Therefore, in addition to bad shortcuts, you are going to learn a lot of different things about good writing and rewriting.
Example 1
REWRITE THIS SENTENCE
PROBLEM
Do not use the forward slash in formal documentation except in these circumstances:
- With fractions
- Between the lines of quoted poetry (not likely to happen in software documentation!)
- In Internet addresses (URLs) and pathnames
- In descriptive phrases such as 9/11 or 24/7
Facebook/Google+ is not acceptable in formal documentation. You might see it in informal, backend documentation. That is OK as long as it stays there.
DISCUSSION
DO NOT use the forward slash as a signifier of alternatives, options, or choices in formal software documentation. The forward slash is not a punctuation mark according to the AP style guide, and it is discouraged in the Chicago and Microsoft style guides. The reason is obvious. It is not clear whether the forward slash means or or and. Don’t leave your reader guessing. Write around it.
The expression and/or is precisely the kind of ambiguity we want to avoid in technical writing. Make up your mind, and then rewrite the sentence.
The forward slash in TCP/IP is acceptable. This is the most common occurrence of the forward slash found in software documentation, but there are others. Check with your lead technical writer for guidance.
As for the backslash (\), its use generally is restricted to computing. For example, URL addresses take backslashes.
REVISION
Before
You’ll see how to log in through Facebook/Google+.
After
You’ll see how to log in through Facebook and Google+.
Example 2
REWRITE THIS SENTENCE
PROBLEM
The word account(s). This is a bad shortcut.
DISCUSSION
The author is trying to say the user interface may highlight only one account or it may highlight more than one account. In other words, the user should not be surprised to see more than one account highlighted. However, to use the “(s)” construction as a suffix is incorrect. Don’t do that. Say account or accounts.
REVISION
Before
The UI highlights the account(s) that have the fakeParameter field’s value set to true.
After
The UI highlights the account or accounts that have the fakeParameter field’s value set to true.
Example 3
REWRITE THIS SENTENCE
PROBLEM
parameter(s).
I see this a lot at my current place of business. I am not aware of any style guide that recommends this practice. It’s a bad shortcut.
DISCUSSION
Don’t ever do this.
You have two solutions:
- Use the phrase parameter or parameters
- Use the plural form—the reader can assume the plural includes a single query parameter
REVISION
Before
This command returns guest profile data that matches your query parameter(s).
After
This command returns guest profile data that matches your query parameter or parameters.
Or
This command returns guest profile data that matches your query parameters.
