Skip to main content

Punctuation

This page describes some tips on using punctuation in documentation.

Commas​

When including a list of items in a sentence, be sure to use the Oxford comma. The Oxford comma, also known as the serial comma, comes before the conjunction in a list. For example:

  • ScalarDL Core, ScalarDB Cluster, and ScalarDB Analytics
  • Relational databases that support JDBC, such as MariaDB, Microsoft SQL Server, MySQL, Oracle Database, PostgreSQL, SQLite, and their compatible databases, like Amazon Aurora, Google AlloyDB, TiDB, and YugabyteDB.

In addition, you should consider using a bulleted list to improve readability. For example:

If a sentence contains a list of more than three items

The following Java Development Kits (JDKs) are verified and supported:

  • Oracle JDK: 8, 11, 17, or 21 (LTS versions)
  • OpenJDK (Eclipse Temurin, Amazon Corretto, or Microsoft Build of OpenJDK): 8, 11, 17, or 21 (LTS versions)

If the items listed in a sentence require a long explanation

Several solutions, such as global transaction managers, data federation engines, and HTAP systems, have similar goals, but they are limited in the following perspectives:

  • Global transaction managers (like Oracle MicroTx and Atomikos) are designed to run transactions across a limited set of heterogeneous databases (like only XA-compliant databases).
  • Data federation engines (like Denodo and Starburst) are designed to run analytical queries across heterogeneous databases.
  • HTAP systems (like TiDB and SingleStore) run both transactions and analytical queries only on homogeneous databases.

Ellipsis​

Don't use an ellipsis since its usage is ambiguous.

Exclamation marks​

Don't use exclamation marks unless they're included in a UI element.