Punctuation Rules — Consistent Punctuation Standards for Technical Documentation

In this tutorial, you will learn about Punctuation Rules. We cover key concepts, practical examples, and best practices to help you master this topic.

Punctuation rules define how to use commas, semicolons, colons, dashes, and other marks consistently. Proper punctuation improves readability and prevents ambiguity. Inconsistent punctuation distracts readers and makes documentation appear unprofessional.

In this lesson, you will learn punctuation rules for technical documentation.

What You'll Learn

You will understand punctuation rules for common marks, apply consistent punctuation in lists and code, and avoid common punctuation errors.

Why It Matters

Punctuation directly affects readability. A missing comma can change the meaning of a sentence. Inconsistent punctuation usage signals carelessness.

Real-World Use

DodaTech standardized on serial comma usage across all documentation. Support tickets about ambiguous instructions dropped after the change.

flowchart LR
  A[Punctuation] --> B[Serial Comma]
  A --> C[Colon]
  A --> D[List Punctuation]
  A --> E[Quotation Marks]
  B --> F[Compress, decompress, and verify]
  C --> G[Introduces a list]
  D --> H[Consistent endings]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Comma Rules

Use the serial comma also called Oxford comma before and in a list of three or more items. Compress, decompress, and verify.

Use a comma after introductory phrases. After installing the package, configure the settings.

Use commas to separate independent clauses joined by and, but, or. Install the package, and then configure the settings.

Do not use commas between two items. Compress and decompress not Compress, and decompress.

# Serial comma (use)
Supported algorithms: gzip, bzip2, and xz.

# No serial comma (avoid)
Supported algorithms: gzip, bzip2 and xz.

# Introductory comma
After the installation completes, restart the service.

Colons and Semicolons

Use colons to introduce lists, examples, or explanations. The colon follows a complete sentence.

Use semicolons sparingly in technical documentation. They connect closely related independent clauses. Most semicolons can be replaced with periods.

Capitalize the word after a colon if it starts a complete sentence. Do not capitalize if it continues the same thought.

# Colon usage (correct)
DodaZIP supports three algorithms: gzip, bzip2, and xz.

# Colon usage (incorrect - fragment before colon)
Supported algorithms: gzip, bzip2, and xz.

Common Mistakes

1. No Serial Comma

Compress, decompress and verify could be ambiguous. Use the serial comma.

2. Comma Splices

Joining two complete sentences with a comma. Use a period or semicolon instead.

3. Colon After a Fragment

Using a colon after an incomplete sentence. The text before a colon must be a complete sentence.

4. Quotation Mark Placement

Placing periods and commas inside or outside quotation marks inconsistently. US English places them inside.

5. Overusing Semicolons

Semicolons in technical documentation often confuse readers. Use periods for clarity.

6. Apostrophe in Plurals

Writing API's when meaning APIs. Apostrophes indicate possession, not plurality.

7. Hyphen vs Dash Confusion

Using hyphens where em dashes or en dashes are needed. Each has a specific use.

Practice Questions

1. What is the serial comma rule?

Use a comma before and in a list of three or more items. Compress, decompress, and verify.

2. When should you use a colon?

To introduce a list, example, or explanation. The text before the colon must be a complete sentence.

3. How should list items be punctuated?

If all items are complete sentences, end each with a period. If items are fragments, do not use periods. Be consistent.

4. What is the difference between a hyphen and an em dash?

A hyphen joins compound words. An em dash sets off parenthetical phrases. Em dashes are wider.

5. Challenge: Find 10 punctuation errors in a documentation page. Categorize them by type and correct each one.

FAQ

Mini Project

Create a punctuation reference guide for a documentation project. Include rules for serial comma, colons, semicolons, dashes, quotation marks, apostrophes, and list punctuation. Provide good and bad examples.

What's Next

Next: Numbers and Measurements