From 42358e3529439595b41b9560832470a4ab086b08 Mon Sep 17 00:00:00 2001 From: Betsy Gitelman Date: Tue, 11 Jun 2024 16:22:36 -0400 Subject: [PATCH 1/3] Edits to style guide Added clarification on future tense, conditional tense, and contractions. Cleaned up the rest of the text to better adhere to our style guide. --- .../community/contributing/styleguide.mdx | 140 +++++++++++------- 1 file changed, 83 insertions(+), 57 deletions(-) diff --git a/advocacy_docs/community/contributing/styleguide.mdx b/advocacy_docs/community/contributing/styleguide.mdx index 6fe5fab021f..ad322cdb296 100644 --- a/advocacy_docs/community/contributing/styleguide.mdx +++ b/advocacy_docs/community/contributing/styleguide.mdx @@ -2,7 +2,7 @@ title: Documentation Style Guide navTitle: Documentation Style Guide iconName: Docs -description: Our style guide to help you get your writing right +description: EDB style guide to help you get your writing right indexdepth: 3 rootisheading: true deepToC: true @@ -95,13 +95,13 @@ For tutorials, the docs can be more casual and conversational but must also be ### 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 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 +Instead of: EDB recommends that you restart your server. @@ -125,12 +125,18 @@ 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. +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 the safety of a person, equipment, or code, 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. @@ -139,27 +145,26 @@ Don’t use the Latin abbreviations i.e. and e.g. Use “that is” and “for e 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. +* 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 —. +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 –. +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 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 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. @@ -167,7 +172,7 @@ Capitalization rules: **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. +* 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: @@ -183,12 +188,11 @@ Punctuation rules: * Use the [Oxford (a.k.a. serial) comma](https://en.wikipedia.org/wiki/Serial_comma). -Topic structure ---------------- +### 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: +* 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. @@ -202,7 +206,19 @@ 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.” +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 @@ -246,17 +262,17 @@ This condition happens only after you select **Okay**. #### 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. +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 +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_. +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 “below” and “above” to refer to previous and following sections. Link to the section instead. +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: @@ -270,8 +286,7 @@ The color palette includes: House style is to use “select” instead of “click” to allow for mobile-device use. -Common errors/words to avoid ----------------------------- +## Common errors/words to avoid Avoid these common errors and wording issues. @@ -310,9 +325,9 @@ Don't use: 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. +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. 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: @@ -329,12 +344,12 @@ Don’t use any font treatments for: * Roles -* User names (e.g. edb_admin) +* User names (for example, edb_admin) * Permissions * Window or dialog box names - + ### Bold (\*\*text\*\*) @@ -350,36 +365,42 @@ See [Code](#code) for more information. ### Italics (`_text_`) -Use for book titles and first instance of terms. Do not use _Italics_ for keywords. +Use for book titles and first instance of terms. Do not use _italics_ for keywords. ### Underline -Do not use underlined text in EDB docs. +Don't 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](https://www.enterprisedb.com/docs/pem/latest/monitoring_BDR_nodes/).” +Whenever an EDB feature is referenced, provide a link to the relevant documentation. For example: -Avoid using the URL as the label. For example, +Use Postgres Distributed (PGD) dashboards and probes to monitor status and activities for admin, nodes, and groups. See [Monitoring EDB Postgres Distribute](https://www.enterprisedb.com/docs/pem/latest/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](https://www.enterprisedb.com/services-support/edb-supported-products-and-platforms) 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](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](https://www.postgresql.org/docs/current/static/auth-pg-hba-conf.html).” +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](https://www.postgresql.org/docs/current/static/auth-pg-hba-conf.html). -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_](https://www.enterprisedb.com/docs/pem/latest/pem_admin/).” +If you're referring to a guide on Docs 2.0, the label is the name of the guide and in italics. For example: -Link capitalization can be either title- or sentence-case: +For information about modifying the `pg_hba.conf` file, see the [_PEM Administrator's Guide_](https://www.enterprisedb.com/docs/pem/latest/pem_admin/). -* **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_](https://www.enterprisedb.com/docs/pem/latest/pem_admin/).”). +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_](https://www.enterprisedb.com/docs/pem/latest/pem_admin/).”). -* **Use sentence-case** when linking in the middle of a sentence. For example, “\[…\] follow the identifier rules when creating \[…\]“). +* **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** | +| 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/ | @@ -406,11 +427,11 @@ Addresses are relative. In these examples of links to topics, “folder” means ## Admonitions: notes, tips, and warnings -Our docs currently use notes, tips, and warnings. +Our docs use notes, tips, and warnings. See [https://github.com/EnterpriseDB/docs/blob/develop/README.md](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. +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 @@ -424,9 +445,9 @@ Use for indicating a new version added in a particular release when working in t ### Warnings -Use warning to express that a piece of information is critical to preventing unexpected things from happening. +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 is critical to prevent users from unexpectedly losing constraints or additional indexes. +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 @@ -434,13 +455,13 @@ 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. +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: -Example: The `CREATE TABLE` statement creates a new table in a database. +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` `` ``` - note we need spaces to separate the demarcation from the code in this example. +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 @@ -470,7 +491,7 @@ Which results in: > This is more sample text. -Use syntax highlighting for configuration file , shell, and SQL commands, where appropriate, as follows. +Use syntax highlighting for configuration file, shell, and SQL commands, where appropriate, as follows. **Shell code samples** @@ -529,16 +550,15 @@ Which results in: > ``` -Tables ------- +### Tables -Use tables to display structured information in an easy-to-read format. There are two types of tables we use: Markdown and HTML. +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 (e.g., basic text formatting and using `
` tags for paragraph breaks), create a table using Markdown. This is the preferred table format. +If table formatting can be kept simple (for example, basic text formatting and using `
` 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. +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. @@ -562,24 +582,30 @@ Term | Description | Example EDB docs uses two types of lists: -* **Numbered** (ordered) — Use to list information that should appear in order, like tutorial steps. +* **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. + **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. + 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 **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: -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`. +`- 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. +* **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. +* **Diagrams** — Provide a visual of a complicated theory. Diagrams must be simple and easy to read. **Syntax:** @@ -592,9 +618,9 @@ Use images to clarify a topic, but use them only as needed. Images are either: ## 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 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](https://www.iso.org/iso-8601-date-and-time-format.html) 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. +When specifying dates as solely numbers, use [ISO8601](https://www.iso.org/iso-8601-date-and-time-format.html) 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 From a5603894c6635fca3b5dd23b30a8f154e6f47c92 Mon Sep 17 00:00:00 2001 From: Betsy Gitelman Date: Tue, 25 Jun 2024 15:17:28 -0400 Subject: [PATCH 2/3] Update advocacy_docs/community/contributing/styleguide.mdx Co-authored-by: gvasquezvargas --- advocacy_docs/community/contributing/styleguide.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/advocacy_docs/community/contributing/styleguide.mdx b/advocacy_docs/community/contributing/styleguide.mdx index ad322cdb296..b2fa95cb746 100644 --- a/advocacy_docs/community/contributing/styleguide.mdx +++ b/advocacy_docs/community/contributing/styleguide.mdx @@ -133,7 +133,7 @@ In keeping with the casual and friendly tone, use contractions. However, use com In new reference material, don't use contractions. -For instructions that concern the safety of a person, equipment, or code, it's okay to spell out the words if you choose to, for example: +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. From 1748c39e8e325ecb75883ba9397bc7d53f405605 Mon Sep 17 00:00:00 2001 From: Betsy Gitelman Date: Tue, 25 Jun 2024 15:17:46 -0400 Subject: [PATCH 3/3] Update advocacy_docs/community/contributing/styleguide.mdx Co-authored-by: gvasquezvargas --- advocacy_docs/community/contributing/styleguide.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/advocacy_docs/community/contributing/styleguide.mdx b/advocacy_docs/community/contributing/styleguide.mdx index b2fa95cb746..ae6809abe16 100644 --- a/advocacy_docs/community/contributing/styleguide.mdx +++ b/advocacy_docs/community/contributing/styleguide.mdx @@ -618,7 +618,7 @@ Use images to clarify a topic, but use them only as needed. Images are either: ## 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 for easier alignment,for example, 01 Jan 2024. +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](https://www.iso.org/iso-8601-date-and-time-format.html) 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.