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're 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. The preferred maximum sentence length is 26 words.
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).
In new reference material, don't use contractions.
For instructions that concern important lifecycle operations of an environment, the functionality of databases, or when warning against actions that could interrupt a procedure, it's okay to spell out the words if you choose to, for example:
Do not restart the server.
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's 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.
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 off 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.
Avoid future tense (will) and conditional tenses (would, could, should). These tenses lack precision and can create passive voice.
Use future tense when an action occurs in the future, for example:
This feature will be removed in a future release.
While present tense is strongly preferred, future tense can be useful and accurate in an "if/then" phrase. For example, it's okay to write:
If you perform this action, another action will occur.
The conditional tense is okay only if you explain the conditions and any action to take. For example, use:
A message should appear. If it doesn't, restart the server.
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 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 an 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 "above" and “below” to refer to previous and following sections. Link to the section instead or use "earlier" or "later."
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. You can denote anything below Heading 4 using bold text or other layout options. (Consider redesigning the material.)
Heading 1 is reserved for page titles.
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 (for example, 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.
Use for book titles and first instance of terms. Do not use italics for keywords.
Underline
Don't use underlined text in EDB docs.
Links
Whenever an EDB feature is referenced, provide a link to the relevant documentation. For example:
Use Postgres Distributed (PGD) dashboards and probes to monitor status and activities for admin, nodes, and groups. See Monitoring EDB Postgres Distribute.
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.
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 type
Syntax
Example
Source path
Destination 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
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:
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. To keep the formatting simple, consider instead adding a subsection (or whether an admonition is the appropriate mechanism).
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 a 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 information 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 (`code`) and is used when referring to code, commands, or other technical syntax within a sentence. For example:
The CREATE TABLE statement creates a new table in a database.
Nesting inline code
To format code that includes back-ticks, add additional back-ticks to demarcate: `` \echo `date` ``. You need spaces to separate the demarcation from the code in this example.
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
~~~
```
Which results in:
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 (__OUTPUT__) 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)
```
Results in
SELECT slot_name, slot_type,database, active FROM pg_replication_slots ORDERBY1;
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:
Use tables to display structured information in an easy-to-read format. We use two types of tables: Markdown and HTML.
Markdown
If table formatting can be kept simple (for example, 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 doesn't need to align 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"`
Resulting in
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 must 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 that are sentences or complete 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, for example:
- 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.
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 for easier alignment, for example, 01 Jan 2024.
When specifying dates as solely numbers, use ISO8601 format; YYYY/MM/DD. This is the internationally accepted, disambiguous format. Use it where you may expect the date to be read by automated systems.
Terminology considerations
Ambiguity of the term "cluster"
The term "cluster" can refer to different groups of resources in the technological field.
At EDB, the product documentation uses the term "cluster" to refer to several different objects/concepts.
To avoid ambiguity, always use an adjective (describing word) to clarify which of the cluster types you're referring to in the specific context.
Here are a few examples:
Postgres cluster: Also known as a database cluster, a Postgres cluster is a Postgres server that hosts a number of databases in a single file system location.
PGD cluster: A PGD cluster is a Postgres Distributed system with a group of multiple redundant database systems in different locations.
Kubernetes cluster: A Kubernetes cluster is a set of multiple nodes that run containerized applications.
Postgres distributions
EDB products support three types of Postgres distributions:
PostgreSQL (open-source or community Postgres)
EDB Postgres Advanced Server (EPAS)
EDB Postgres Extended Server (PGE)
Although also referred to as "Postgres flavors," the preferred terms are "Postgres" or "Postgres distributions" to refer to all three options.
Trademark symbols
Use the ™ or ® symbol at least upon the first use of the EDB Postgres® + [product] trademark in the body text of a page.
For other trademarks, the documentation site already includes a general disclaimer at the footer of every page called "Trademark" which links to https://www.enterprisedb.com/trademarks.
Contrary to the specifications on Trademarks, don't include the symbol in page titles,
because the symbol can affect how search engines index and find pages.
Frontmatter
The frontmatter is located at the top of every Markdown page and allows you to specify metadata and options in YAML language. Frontmatter lets you control how a page renders.
Ensure your page, at minimum, includes a title and description as metadata. It can include other metadata such as navTitle, deepToC, and so on.
---title: Working with the repo
description: Step-by-step instructions to install and use the docs repo.
---
Note
Ensure the description has a final stop (period), even if it isn't a full grammatical sentence. Descriptions are used to dynamically build a summary for each section in index pages. Since all descriptions are then displayed next to each other, add a full stop to ensure visual consistency.