AI-generated Key Takeaways
-
Prioritize conciseness in error messages by eliminating unnecessary text and focusing on the core issue.
-
Use active voice instead of passive voice to make sentences shorter and clearer, as it improves readability.
-
Be concise without sacrificing clarity; avoid making error messages so brief that they become ambiguous or cryptic.
-
Error message example: "The SiteID
-
The document refers to another unit with regards to tips for reducing sentence lengths.
Write concise error messages. Emphasize what's important. Cut unnecessary text. See the Short sentences unit of Tech Writing One for tips on reducing sentence length.
Not recommended
Unable to establish connection to the SQL database. [Explanation of how to fix the issue.]
Recommended
Can't connect to the SQL database. [Explanation of how to fix the issue.]
Not recommended
The resource was not found and cannot be differentiated. What you selected doesn't exist in the cluster. [Explanation of how to find valid resources in the cluster.]
Recommended
Resource <name> isn't in cluster <name>. [Explanation of how to find valid resources in the cluster.]
Converting from passive voice to active voice often makes sentences conciser and easier to understand:
Not recommended
The Froobus operation is no longer supported by the Frambus app.
Recommended
The Frambus app no longer supports the Froobus operation.
In your enthusiasm to be concise, don't remove so many words that the resulting error message becomes cryptic. For example, don't reduce the preceding error message down to the following:
Not recommended
Unsupported.
Multiple choice exercise
Reorder and shorten the following start of an error message. How many words can you remove?
- The SiteID <SiteID> you have entered is invalid.
Next unit: Avoid double negatives