I am a technical communicator who loves words and technology—not necessarily in that order.
Why Are Punctuation Marks Important?
As technical writers, we should strive to make our product documentation as user-friendly as possible. Punctuation marks have the power to make or break a document. If used correctly, punctuation marks can convey more than intended and help the end-users understand your explanations better.
Most of us already know the basic punctuation rules. Some of these include using a period at the end of the sentence, starting a sentence with a capital letter, using apostrophes and question marks, etc. However, this article concentrates on the five most commonly misused punctuation marks in technical writing and how to use them correctly.
1. Exclamation Marks
Exclamation marks (!) are acceptable in creative writing. However, they tend to look out of place in technical documents that require a more formal tone. Use them only for displaying errors or cautionary messages.
Example: Warning! Changing the default settings may cause the system to crash.
Wrong: The screen displays all available attendance recording tools! Choose one!
The comma (,) is most commonly used in technical documents to separate items in a list.
The last comma used in the list is an Oxford comma (also known as serial comma or Harvard comma).
Use the comma whenever you require the reader to pause briefly before continuing.
Example: If the function displays an error, try restarting the program.
Do not use a comma to join two sentences unrelated to each other. New technical writers often tend to make this mistake. The two sentences used below are distinct. Use a period to separate them.
Wrong: HTML defines the basic structure of a web page, MadCap Flare allows customized CSS.
The semicolon (;) is one of the most misused punctuation marks in technical documents.
Read More From Toughnickel
Some technical writers replace the comma with a semicolon thinking it defines a pause longer than a comma. This usage is incorrect. Use the semicolon whenever you want to unite two highly related ideas.
Example: Always check if the links are correct; the output does not display broken links.
The sentences separated by a semicolon should make sense even if you flip the order.
Example: The output does not display broken links; always check if the links are correct.
It is acceptable to use a transitional word like however and therefore right after a semicolon.
Example: Incorrect links can cause errors; therefore, you must ensure all links are correct.
The sentences below do not make sense individually. Use a comma to indicate a brief pause.
Wrong: Although the links are correct; the output does not display them.
What should technical writers use instead of a comma to specify a more dramatic pause? We already understood from the previous section that we should not use the semicolon for this purpose. It is where the em-dash (—) comes into play. You can include an em-dash whenever you want to indicate a pause longer than a comma.
Example: Financial technology—often called fintech—can help manage your investments.
The em-dash is more pleasing to the eye as compared to a comma. Therefore, you can replace the comma with the em-dash if required.
You can avoid spaces before and after an em-dash though it is not a hard-and-fast rule. Most newspapers and magazines tend to add a space before and after an em-dash, but most books and journals avoid it. I personally prefer to use a space before and after an em-dash, but the Google Style Guide advises not to include spaces.
Technical writers should avoid the overuse of em-dash as it can make your document look unprofessional.
Wrong: Financial technology—often called fintech—can leverage technology—to improve financial management.
Parentheses () can contain low-priority notes that the user can refer to for better clarity. The sentence should grammatically make sense even if you skip the phrase included in the parentheses.
The most common mistake with parentheses concerns another punctuation mark—the period. When the parentheses contain the whole sentence, you should include the period before and not outside of the closing parentheses.
Example: (The product has both offline and online features.)
Wrong: (The product has both offline and online features).
When the information contained in the parentheses is a part of another phrase, use the period outside the closing parenthesis.
Example: The product includes various reporting tools (explained in detail later in the document).
Wrong: The product includes various reporting tools (explained in detail later in the document.)
The misuse of punctuation marks in technical documentation is quite common, but it can make your document look shabby. It can even make your reader lose interest, which is the last thing we need.
To capture a reader's interest is not easy, with attention spans decreasing considerably over the years. It is therefore essential to ensure that the punctuations are proper. A tool like Grammarly can help catch and correct incorrect or missing punctuations in your document.
- Google developer documentation style guide | Google Developers
Editorial style guidelines for public-facing Google developer documentation.
This content is accurate and true to the best of the author’s knowledge and is not meant to substitute for formal and individualized advice from a qualified professional.
© 2022 Dhanya V