Grammar

This page provides some common grammar tips in documentation.

Titles and headings

The following are some tips on how to write titles and headings:

• Try to keep titles and headings short. However, don't sacrifice clarity for brevity.
• Don't spell out acronyms in titles or headings. When including an acronym in a title or heading, you don't need to spell out the acronym. However, be sure to spell out the acronym on first mention in the body of the text.

Will the doc or section help the user achieve a task?

Yes

This means that the user will do a task in the document or section.

In this case, make the title or heading a verb phrase since the doc or section is action or task oriented. When possible, try to avoid the verb “use” since it's too generic.

Examples

• Title
  • Run a Sample Microservices Application
  • Model Your Data
  • Configure a License Key
• Heading 2 to 4
  • Load the schema
  • Enable and configure encryption
  • Start a PostgreSQL container

No

This likely means that the document or section won't guide the user in achieving a task. Titles or headings with this type of grammatical structure are used to describe concepts, features, or other non-actionable information.

In this case, make the title or heading a noun phrase since the doc or section is for reference.

Examples

• Title
  • ScalarDB Overview
  • API Guide
  • Configurations
• Heading 2 to 5
  • Relational databases
  • Query-driven data modeling
  • Version skew policy

Bulleted text and numbered text

When adding bulleted text or numbered text, make the wording consistent for each item in the list. For example, each item in the list should start with one of the following:

• Nouns: For listing products, components, features, and other short phrases or sentences
• Verbs: For listing actions that the user or software does
• Adjectives: Lists benefits and tends to be more for marketing and appealing to readers