Skip to content

Commit 53bc91f

Browse files
Apply suggestions from code review
Co-authored-by: Pedro Sousa <[email protected]>
1 parent 97ddd27 commit 53bc91f

File tree

1 file changed

+6
-6
lines changed

1 file changed

+6
-6
lines changed

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

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ Use the following writing guidelines to create product content that is clear and
1010

1111
## Use plain language
1212

13-
Plain language is writing that an audience can understand and act upon the first time they read it. Using plain language ensures your audience understands what you mean. Cloudflare users are a global audience whose first language might not be English. Plain language makes translation easier and documentation more accessible. Using plain language increases the chance that readers understand what you wrote the first time they read it.
13+
Plain language is writing that an audience can understand and act upon the first time they read it. Using plain language ensures your audience understands what you mean. Cloudflare users are a global audience whose first language might not be English. Plain language makes translation easier and documentation more accessible.
1414

1515
Consider the following tips for using plain language in your writing:
1616

@@ -75,7 +75,7 @@ Use present tense verbs. Avoid past tense whenever possible, as it can quickly m
7575

7676
| Do | Don't | Rationale |
7777
| --- | --- | --- |
78-
| 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 |
78+
| 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. |
7979

8080
---
8181

@@ -92,12 +92,12 @@ Use the guidelines below to create product content that is more accessible to pe
9292
- Provide informative, unique page titles.
9393
- Use headings to convey meaning and structure.
9494
- Make the link text meaningful.
95-
- Writing meaningful text alternatives for images.
95+
- Writing meaningful text alternatives (alt text) for images.
9696
- Create transcripts and captions for multimedia.
9797
- Provide clear instructions.
9898
- Keep content clear and concise.
9999

100-
Refer to [Writing for Web Accessibility](https://www.w3.org/WAI/tips/writing/) for additional information about WCAG requirements, detailed background, user stories, and more.
100+
Refer to [Writing for Web Accessibility](https://www.w3.org/WAI/tips/writing/) for additional information about WCAG requirements, detailed background, user stories, and more.
101101

102102
---
103103

@@ -107,7 +107,7 @@ Use simple language and formatting, as appropriate for the context. Respect our
107107

108108
- Keep sentences between 8 to 12 words.
109109
- Write in short, clear sentences and paragraphs.
110-
- Avoid using unnecessarily complex words and phrases. Consider providing a glossary for terms readers may not know.
110+
- Avoid using unnecessarily complex words and phrases.
111111
- Expand acronyms on the first use. For example, Web Content Accessibility Guidelines (WCAG).
112112
- Consider providing a glossary for terms readers may not know.
113113
- Use list formatting as appropriate.
@@ -128,7 +128,7 @@ Participles are verbs that end in _-ed_ or _-ing_ and act as modifiers. Gerunds
128128
| Test the certificate **by using** a browser to connect to your server. | Test the certificate **using** a browser to connect to your server. |
129129
| When **you use** a load balancer with a public-facing IP address, this address becomes the IP address of your website. | When **using** a load balancer with a public-facing IP address, this address becomes the IP address of your website. |
130130

131-
The last example illustrates a dangling modifier. In the "Don't" example, using does not have a subject, so the implied subject is address, which is incorrect. If the implied subject is not correct, you must revise the sentence to provide a subject for the modifying phrase.
131+
The last example illustrates a dangling modifier. In the "Don't" example, _using_ does not have a subject, so the implied subject is address, which is incorrect. If the implied subject is not correct, you must revise the sentence to provide a subject for the modifying phrase.
132132

133133
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.
134134

0 commit comments

Comments
 (0)