table headers

Author: patriciasantaana

src/content/docs/style-guide/documentation-content-strategy/writing-guidelines.mdx

@@ -66,14 +66,14 @@ Consider the following to help you avoid jargon in your writing:
 
 Active voice is more concise and direct than passive voice and should be used whenever possible. Make the message clear and comprehensible to anyone using Cloudflare's products. Choose clarity over concise copy.
 
-| Do | Avoid | Rationale | 
+| Do | Don't | Rationale | 
 | --- | --- | --- |
 | Cloudflare Load Balancing **automatically reduces** latency by directing visitors to infrastructure closest to them. | Latency is **automatically reduced** by Cloudflare Load Balancing. Visitors are directed to infrastructure closest to them. | Writing this sentence in the active voice shifts the focus from the pain point (latency) to the solution (Cloudflare Load Balancing). |
 | Now, paired with the HTML Rewriter API, **you can perform DOM transformations** on top of your static HTML. | Now, paired with the HTML Rewriter API, **DOM transformations can be performed** on top of your static HTML. | Writing this sentence in the active voice shifts the focus from the product to the customer. |
 
 Use present tense verbs. Avoid past tense whenever possible, as it can quickly make content feel outdated or irrelevant. Future tense should only be applied to actions that have not happened yet.
 
-| Do | Avoid | Rationale |
+| Do | Don't | Rationale |
 | --- | --- | --- |
 | FindLaw **uses** Cloudflare to accelerate and secure thousands of customer sites. | FindLaw **used** Cloudflare to accelerate and secure thousands of customer sites. | FindLaw is a current customer who still benefits from the performance and security Cloudflare provides, so we should refer to them in the present tense |
 
@@ -121,7 +121,7 @@ Apply the same unambiguous word or term consistently throughout a document.
 
 Participles are verbs that end in _-ed_ or _-ing_ and act as modifiers. Gerunds are verbs that end in _-ing_ and act as nouns. Both types of words are useful and acceptable, but they can cause confusion if they are misplaced in a sentence. For example, the word meeting can be a gerund or a participle (or even a noun) depending on its placement in a sentence. When you use gerunds and participles, ensure that the meaning is clear.
 
-| Do | Avoid |
+| Do | Don't |
 | --- | --- |
 | A job can include **metadata that schedules** the program to run at a specified date and time. | A job can include **scheduling metadata** that enables the program to run at a specified date and time. |
 | Public Cloud is infrastructure **that consists** of shared resources, deployed on a self-service basis over the Internet. | Public Cloud is infrastructure **consisting** of shared resources, deployed on a self-service basis over the Internet. |
@@ -132,7 +132,7 @@ The last example illustrates a dangling modifier. In the "Avoid" example, using
 
 The titles of tutorial or high-level process articles or topics typically start with a gerund. Titles have less context than sentences, so you must be especially careful to ensure that the meaning is clear.
 
-| Do | Avoid |
+| Do | Don't |
 | --- | --- |
 | Options for editing<br /><br /><i>or</i><br /><br />Editing of options | Editing options |
 | Billing for services | Billing services |
@@ -162,19 +162,19 @@ In addition to the guidelines outlined below, we have identified and replaced se
 
 Do not use terms that are rooted in racism. We do not use terms that describe good outcomes and actions as "white" and bad actions or outcomes as "black" (such as whitehat/blackhat hacker) nor do we use common industry terms that stem from language used to describe slavery (such as master/slave).
 
-| Do | Avoid | Rationale | 
+| Do | Don't | Rationale | 
 | --- | --- | --- |
 | Many search engines will **block** your site if you are hosting malicious content, which only compounds the issue for site owners that do not know that they have been compromised. | Many search engines will **blacklist** your site if you are hosting malicious content, which only compounds the issue for site owners that do not know that they have been compromised. | Since we do not want to use "black" to refer to a negative action here, we replace the term "blacklist" with a neutral, descriptive term that clearly explains the action that is being performed (in this case, "block"). |
 
 Replace gendered terms with non-gendered terms. Gendered language may be used when referring to specific people with known pronouns. It is unnecessary when discussing products and technical processes — for instance, referring to a hypothetical attacker as "he" or a piece of hardware as "she."
 
-| Do | Avoid | Rationale | 
+| Do | Don't | Rationale | 
 | --- | --- | --- |
 | One type of attack that could trigger a browser warning is a so-called **on-path** attack. In this attack, an attacker places **themselves** in between a visitor and a website, impersonating both. | One type of attack that could trigger a browser warning is a so-called **man-in-the-middle (MitM)** attack. In this attack, an attacker places **himself** in between a visitor and a website, impersonating both. | Because a "man-in-the-middle attack" is a term, not a reference to a specific attack carried out by a man, we opt for the term "on-path attack" and attach gender-neutral they/them pronouns when describing the attacker. |
 
 Avoid ableist terms and metaphors. This does not just apply to industry terms, but to descriptors like "crazy" and "insane," which reinforce negative, ableist stereotypes.
 
-| Do | Avoid | Rationale | 
+| Do | Don't | Rationale | 
 | --- | --- | --- |
 | As Workers use cases grow in complexity, the need to **validate** your code also grows. | As Workers use cases grow in complexity, the need to **sanity check** your code also grows. | We avoid metaphorical terms that reference mental health, like "sanity check," and replace them with words that more accurately describe the process taking place (in this case, "validate", though "smoke test" is also an approved replacement). |