You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: src/content/docs/style-guide/documentation-content-strategy/writing-guidelines.mdx
+6-6Lines changed: 6 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,7 +10,7 @@ Use the following writing guidelines to create product content that is clear and
10
10
11
11
## Use plain language
12
12
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.
14
14
15
15
Consider the following tips for using plain language in your writing:
16
16
@@ -75,7 +75,7 @@ Use present tense verbs. Avoid past tense whenever possible, as it can quickly m
75
75
76
76
| Do | Don't | Rationale |
77
77
| --- | --- | --- |
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.|
79
79
80
80
---
81
81
@@ -92,12 +92,12 @@ Use the guidelines below to create product content that is more accessible to pe
92
92
- Provide informative, unique page titles.
93
93
- Use headings to convey meaning and structure.
94
94
- Make the link text meaningful.
95
-
- Writing meaningful text alternatives for images.
95
+
- Writing meaningful text alternatives (alt text) for images.
96
96
- Create transcripts and captions for multimedia.
97
97
- Provide clear instructions.
98
98
- Keep content clear and concise.
99
99
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.
101
101
102
102
---
103
103
@@ -107,7 +107,7 @@ Use simple language and formatting, as appropriate for the context. Respect our
107
107
108
108
- Keep sentences between 8 to 12 words.
109
109
- 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.
111
111
- Expand acronyms on the first use. For example, Web Content Accessibility Guidelines (WCAG).
112
112
- Consider providing a glossary for terms readers may not know.
113
113
- Use list formatting as appropriate.
@@ -128,7 +128,7 @@ Participles are verbs that end in _-ed_ or _-ing_ and act as modifiers. Gerunds
128
128
| Test the certificate **by using** a browser to connect to your server. | Test the certificate **using** a browser to connect to your server. |
129
129
| 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. |
130
130
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.
132
132
133
133
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.
0 commit comments