Documentation Style Guide

Suggest edits

Introduction

EDB docs follow the 5 Cs of technical writing:

  • Clear
  • Correct
  • Concise
  • Complete
  • Consistent

Follow these guidelines to ensure consistency.

Included in this guide:

Language and tone

EDB docs are helpful, humble, positive, and friendly. To achieve this, write topics that are factual and free of hyperbole and wordiness.

Where possible, use active voice instead of passive.

Tense and voice

For reference and general task-based docs, use the second-person imperative present tense, also known as "imperative mood." These docs should be straightforward and conventional.

Example: Use the following command to create a user:

CREATE USER john IDENTIFIED BY abc; 

For tutorials, the docs can be more casual and conversational but must also be straightforward and clear.

Example: In this lab, start with a fresh cluster. Make sure to stop and clean up the cluster from the previous labs.

Person

Use second person (you) when referring to the user. Don’t use “the user,” which is third person, unless you are talking about the customer’s user.

Use first person plural (we) to refer to EDB. For example, use:

We recommend that you restart your server.

Instead of

EDB recommends that you restart your server.

However, don’t use first person plural when talking about how the software works or in an example. For example:

Instead of:

Next, we process the instruction.

Use:

Next, Barman processes the instruction.

Instead of:

Next, we enter the following the information:

Use:

Enter the following information:

Sentence length

Use simple and direct language and keep your sentences short. Avoid combining sentences, which makes the content complicated. Maximum sentence length is 26 words when possible.

Contractions

In keeping with the casual and friendly tone, use contractions. However, use common contractions (isn’t, can’t, don’t). Don't use contractions that are unclear or difficult to pronounce (there’ll).

Latin abbreviations

Don’t use the Latin abbreviations i.e. and e.g. Use “that is” and “for example” instead.

Em-dashes and en-dashes

Avoid using em-dashes to set off phrases within a sentence, which creates a complicated sentence structure and can be difficult to translate. You can use em-dashes for definition lists such as:

  • Autonomous — Use to create autonomous calls to the server.

Use spaces around em-dashes in a definition list. Otherwise, don't put spaces around em-dashes.

To create an em-dash, use the character entity —.

Use en-dashes to mean “through,” for example, items 1–10. Don’t use en-dashes otherwise. (There's only one other use of en-dashes that doesn’t typically come up in technical writing.). To create an en-dash, use the character entity –.

Numbers

Spell out numbers zero through nine. Use digits for numbers 10 and greater. Spell out any number that starts a sentence. For this reason, avoid starting a sentence with a long or complex number.

Capitalization and punctuation

Capitalization rules:

  • Use sentence-case for headings (including column headings in tables).
  • Capitalize the first letter in each list item except for function and command names that are naturally lower case
  • Capitalize link labels to match the case of the topic you're linking to.
  • Capitalize proper nouns and match the case of UI features: Examples: EDB, the Overview dashboard, the SQL Queries graph
  • Don’t capitalize the words that make up an initialization unless they're part of proper noun. For example, single sign-on is not a proper noun even though it is usually written as the initialism SSO.

Punctuation rules:

  • Avoid semicolons. Instead, use two sentences.
  • Don’t join related sentences using a comma. This syntax is incorrect.
  • Don't end headings with a period or colon
  • Use periods at the end of list items that are a sentence or that complete a sentence. If one item in a list uses a period, use a period for all the items in that list.
  • Use the Oxford (a.k.a. serial) comma.

Topic structure

  • Procedure headings use gerunds, for example, Modifying your cluster.
  • Use a stem sentence to introduce a procedure only if multiple paragraphs of text fall between the head and the start of the procedure. The stem sentence helps to reorient the user when the heading might have scrolled of the screen. A stem sentence starts with “To” and ends with a colon:
    To modify your cluster:
  • In general, include text between a heading and any subheadings. However, if such text is superfluous, a subhead can directly follow the head.

See also Headings.

Verbiage

Use language that's precise and informative.

Future and conditional tenses

Avoid future tense (will) and conditional tenses (would, could, should). These tenses lack precision and can create passive voice. You can use future tense when an action occurs in the future, for example, “This feature will be removed in a future release.”

Empty phrases

Phrases like, “This section tells you about how to [do something]” are empty and don’t impart any real information. The title of the chapter or section tells you what the section is about. These phrases describe the documentation (documenting the documentation) rather than the product or user actions.

Replace these empty phrases with wording that focuses on the product or process. So instead of:

This chapter is divided into five sections. Each section tells you about part of the process.

Write:

To complete the process, perform these five steps:

You can then link to each of the sections.

Weak sentence starters

“There is” and “there are” are weak sentence starters. Avoid starting sentences this way.

“This” without a noun

Avoid using “this” without a noun following. Doing so can lead to ambiguity. For example, instead of:

This happens when…

Write:

This error happens when…

Misplaced modifiers

Make sure the word “only” precedes the word or expression you mean to modify. For example, instead of:

This condition only happens after you select Okay.

Write:

This condition happens only after you select Okay.

Hyphen use

With a prefix

Don't use hyphens with prefixes such as re, non, multi, and pre unless needed for readability or to eliminate ambiguity. Often, when two vowels end up up together, a hyphen is needed, for example, multi-instance. However, preexisting is a legitimate word; don’t hyphenate it. Re-create (create again) requires a hyphen to avoid confusion with recreate (play). You can check many words using a spell checker. For example, nonexistent is not flagged by the spell checker.

If you're unsure whether to include a hyphen, check with your editor or google the word without the hyphen

With compound adjectives

A compound adjective is formed when two words together describe a noun, for example, red-bellied warbler. Don’t use a hyphen when and adverb and a verb together describe a noun. The adverb describes the verb and doesn’t need a hyphen to create the relationship between the words. An example is finely tuned settings.

Directing users up and down through a topic

Don’t use words like “below” and “above” to refer to previous and following sections. Link to the section instead.

It also isn't necessary to use the words “the following” to refer to list items. These words are empty. So, for example, instead of:

The palette includes the following colors:

Write:

The color palette includes:

Select versus click

House style is to use “select” instead of “click” to allow for mobile-device use.

Common errors/words to avoid

Avoid these common errors and wording issues.

Login and log in

The verb form is “log in”:

To log in to the system…

The adjective form is “login”:

At the login screen, enter your username.

Setup and set up

The verb form is “set up”:

To set up your environment…

The noun form is “setup”:

Check your setup for errors.

Words to avoid

Don't use:

  • Please
  • Note that
  • In order to (just use “to”)

Headings

Use headings to create a hierarchy for readers to navigate to more easily find information.

In Markdown, headings are denoted by number signs (#) followed by one space. Enter a line break between a heading and its content. EDB docs use Heading 2 (##), Heading 3 (###) and Heading 4 (####). Use Heading 4 sparingly.

Heading 1 is reserved for page titles. You can denote anything below Heading 4 using bold text or other layout options. (Consider redesigning the material.)

Examples:

  • ## This is heading 2
  • ### This is heading 3
  • ## Step 2. This is a step in a tutorial

Font treatments

Don’t use any font treatments for:

  • Roles
  • User names (e.g. edb_admin)
  • Permissions
  • Window or dialog box names

Bold (**text**)

Use for UI elements. For menu items, include a greater-than sign: Select File > Save.

Courier aka code or monospace ('text')

Use for text entered in text boxes, parameters, commands, text in configuration files, and file paths. Don’t use for utility names.

If you need to enter a value in a field, type the ls or dd command, add a setting to a configuration=file or just refer to /etc/passwd, then this is the font treatment to use.

See Code for more information.

Italics (text)

Use for book titles and first instance of terms. Do not use Italics for keywords.

Underline

Do not use underlined text in EDB docs.

Links

Whenever an EDB feature is referenced, provide a link to the relevant documentation. For example, “BDR (Bi-Directional Replication) dashboards and probes to monitor status and activities for Admin, Nodes, and Groups. See Monitoring BDR Nodes.”

Avoid using the URL as the label. For example,

Best practice: For information about the platforms and versions supported by PEM, see Product Compatibility on the EnterpriseDB website.

Avoid: For information about the platforms and versions supported by PEM, visit the EnterpriseDB website at: https://www.enterprisedb.com/services-support/edb-supported-products-and-platforms.

You can also provide links to external resources, but only if the resource is vetted and no EDB documentation covers the topic. For example: “Information about managing authentication is also available in the Postgres core documentation.”

If you're referring to a guide on Docs 2.0, the label is the name of the guide and in italics. For example, “For information about modifying the pg_hba.conf file, see the PEM Administrator's Guide.”

Link capitalization can be either title- or sentence-case:

  • Use title-case and italics when referring to the linked doc by name. For example. “For information about modifying the pg_hba.conf file, see the PEM Administrator's Guide.”).
  • Use sentence-case when linking in the middle of a sentence. For example, “[…] follow the identifier rules when creating […]“).

Addresses are relative. In these examples of links to topics, “folder” means the folder in the repo such as the product folder or the guide folder. For the destination topic, use the name of the file without the .mdx extension. If the destination includes a topic_identifier (sub-section of a file), include the topic_identifier prefixed with a # sign, such as in “/09_controlling_logging/#enabling_syslog.”

Link typeSyntaxExampleSource pathDestination path
Link typeSyntaxExampleSource pathDestination path
Another topic in the same folder[here](file_name)[Using the EFM Utility](07_using_efm_utility/#using_efm_utility)/efm/4.2/efm_user/07_using_efm.mdx/efm/4.2/efm_user/07_using_efm_utility.mdx
Another topic in a different folder at the same level[here](../dest_folder_name/file_name)[The ERD Tool](../pem_ent_feat/04_pem_erd_tool/)/pem/8/pem_rel_notes/08_810_rel_notes.mdx/pem/8/pem_ent_feat04_pem_erd_tool/
Another topic in a different folder at a different level[here](../../folder_name/file_name)[Enabling syslog Log File Entries](../../09_controlling_logging/#enabling_syslog)/efm/4.2/efm_user/04_configuring_efm/01_cluster_properties/index.mdx/efm/4.2/efm_user/09_controlling_logging.mdx/enabling_syslog
  • To link to a specific heading on another page, use the name of the file plus the heading. Example: [xyz](file_name#heading-on-page)
  • To link to a specific heading on the current page, use just the heading. Example: [xyz](#heading-on-page)
  • To link to a specific location on a page that isn't a heading (for example, a specific command-line flag in a table), add a manual anchor and use the id parameter: Example: # Anchor: <a id="flags-max-offset"></a>`--max-offset` # Link: [--max-offset](#flags-max-offset)

Admonitions: notes, tips, and warnings

Our docs currently use notes, tips, and warnings.

See https://github.com/EnterpriseDB/docs/blob/develop/README.md for more information on admonitions.

For multiple, consecutive admonitions, use separate admonitions. If there are more than two consecutive admonitions, consider adding a subsection called Additional notes or Additional information. Admonitions can contain bullets and code, but consider instead adding a subsection (or whether an admonition is the appropriate mechanism) to keep the formatting simple.

Notes

Use notes to call attention to a piece of clarifying information. This information isn't crucial to accomplishing the task in the document.

For example, you might use a note to let users know that the DELETE command deletes only rows and that to delete columns you must use ALTER TABLE. This information helps to clarify the command's purpose and point users to the right place.

Tips

Use for indicating a new version added in a particular release when working in the major version of the documentation for products that are adhering to semantic versioning. See the PEM documentation for examples. Also can use for information that might improve productivity.

Warnings

Use warning to express that a piece of information is critical to preventing unexpected things from happening.

For example, you might include a warning that using CASCADE in DROP INDEX drops dependent objects without warning. This is critical to prevent users from unexpectedly losing constraints or additional indexes.

Code

Code can be shown inline or as a code block.

Inline code

Inline code has back-ticks (``) around it and is used when referring to code, commands, or other technical syntax within a sentence.

Example: The CREATE TABLE statement creates a new table in a database.

Code blocks

Code blocks provide executable code samples, marked with an opening and closing set of three backticks (```). Code blocks can support syntax highlighting if you add the language name immediately after the first line of backticks. Use one returned line before and after a code block for better Markdown readability. For example:

This is a sample line of text. ``` {% include copy-clipboard.html %} ~~~shell $ go get -u github.com/lib/pq ~~~ ``` This is more sample text.

Use syntax highlighting for configuration file , shell, and SQL commands, where appropriate, as follows.

Shell code samples

Start shell code samples with  ```shell followed by a line break. Use the terminal marker $ as the first character of the next line. For multi-line shell commands, use a backslash (\) at the end of each line to indicate a line break.

SQL code samples

SQL code samples are broken into two sections: commands and responses.

  • Commands (e.g., SELECT, CREATE TABLE) begin with  ```sql followed by a line break. The first character of the next line should be the terminal marker >. Capitalize commands properly. Use only one command per code sample.
  • Responses (e.g., retrieved tables) add (_ 0UTPUT _) on a line between the command and the output, you'll get highlights for the code but not the output. For example, ```sql SELECT slot_name, slot_type, database, active FROM pg_replication_slots ORDER BY 1; __OUTPUT__ slot_name | slot_type | database | active -------------+-----------+-----------+-------- xdb_47877_5 | logical | MMRnode_a | t xdb_47878_5 | logical | MMRnode_b | t xdb_47879_5 | logical | MMRnode_c | t (3 rows) ```
sql SELECT slot_name, slot_type, database, active FROM pg_replication_slots ORDER BY 1;
Output
slot_name | slot_type | database | active -------------+-----------+-----------+-------- xdb_47877_5 | logical | MMRnode_a | t xdb_47878_5 | logical | MMRnode_b | t xdb_47879_5 | logical | MMRnode_c | t (3 rows)

Configuration file samples

For files that have key-value pairs use ```ini. For example:

```ini promotable=false auto.reconfigure=false ```

Tables

Use tables to display structured information in an easy-to-read format. There are two types of tables we use: Markdown and HTML.

Markdown

If table formatting can be kept simple (e.g., basic text formatting and using <br> tags for paragraph breaks), create a table using Markdown. This is the preferred table format.

To create a table, use pipes (|) between columns and at least 3 dashes (-) separating the header cells from the body cells. A return denotes the start of the next row. The text within each column does not need to align in order to be rendered correctly, and you can inline Markdown or HTML.

We don’t use outer pipes.

Example:

Term | Description | Example ----------|-----------------------------|---------------- `term_1` | This is a description. | `3.14` `term_2` | This is also a description. | `"lola mcdog"`

Lists

EDB docs uses two types of lists:

  • Numbered (ordered) — Use to list information that should appear in order, like tutorial steps. Bulleted (unordered) — Use to list related information in an easy-to-read way. Introduce lists with a sentence and a colon. Use periods at the end of list items if it is a sentence or completes a sentence.

For each item of a numbered list, use 1. followed by a period and a space, for example,1. This is a numbered list. Markdown renders the steps in the correct order.

For each item of a bulleted list, use one dash followed by one space to denote a list item, e.g., - This is a bulleted list.

Images

Use images to clarify a topic, but use them only as needed. Images are either:

  • Screenshots — Provide a UI visual. Don’t use to show dialog boxes and parts of the UI a user can see for themselves, as these are hard to maintain and don’t provide useful information. If a screenshot needs an annotation, use a red box.
  • Diagrams — Provide a visual of a complicated theory. Diagrams must be simple and easy to read.

Syntax:

! [Alternate_text](<path_to_image_file>/<image_filename.png>)

Example:

![PEM Architecture](../images/pem_architecture.png)

Dates

When specifying dates for human readability, use the DD mmm YYYY format with a short month name in English. Where the date is being used in a column in a table, use a leading 0 on the day of month, e.g. 01 Jan 2024, for easier alignment.

When specifying dates as solely numbers, use ISO8601 format; YYYY/MM/DD. This is the internationally accepted, disambiguous format and should be used where you may expect the date to be read by automated systems.

Could this page be better? Report a problem or suggest an addition!