From 0088ed032cd8119f22a573e71b04a7810e48f913 Mon Sep 17 00:00:00 2001 From: SKhubaib <107524270+SKhubaib@users.noreply.github.com> Date: Wed, 15 Jun 2022 10:05:10 +0500 Subject: [PATCH 1/3] Fixes grammar and brevity Line 93: helping: incorrect form of verb - change to 'help'. Line 105: and instead try: missing punctuation - add comma after instead. Line 110: offers an explanation of: against your guidelines for brevity - change to 'explains'. Line 133: chance readers leave the page and not return: missing particle and helping verb - change to 'chance that readers leave the page and don't return'. Line 187: want be: missing particle - change to 'want to be'. Line 188: make it clearer: unnecessary pronoun - change to 'make clearer'. Line 242: making readings think: incorrect noun - change to 'making readers think'. Line 243: Make use to use `it's` only for: against guidelines for brevity and incorrect preposition: change to 'Use `it's` only for'. Line 257: these aren't always understood correctly: negation is incorrect - change to 'these are always understood correctly'. Line 284: too many in one place: missing noun - change to 'too many note in one place'. Line 319: checks note when: change to 'check notes when'. --- contributing/content-style.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/contributing/content-style.md b/contributing/content-style.md index 0866a26b11..2fc4ad3176 100644 --- a/contributing/content-style.md +++ b/contributing/content-style.md @@ -90,7 +90,7 @@ allowlist | whitelist ### Resources for inclusive language -Some guides to helping you make sure your writing is inclusive and accessible to everyone. +Some guides to help you make sure your writing is inclusive and accessible to everyone. * [Mailchimp guide to writing for accessibility](https://styleguide.mailchimp.com/writing-for-accessibility/) * [Microsoft's ideas on writing for all abilities](https://docs.microsoft.com/en-us/style-guide/accessibility/writing-all-abilities) @@ -102,12 +102,12 @@ Some guides to helping you make sure your writing is inclusive and accessible to To make your content as accessible as possible, the purpose of a link should be clear from its text alone. Avoid links with text like `click here` -and instead try to include meaning inside the link itself. +and instead, try to include meaning inside the link itself. Remember to use the [proper format for links](./markup-format.md#links) The supporting documentation for the Web Content Accessibility Guidelines -offers an explanation of [why link purpose in the text alone is good](https://www.w3.org/WAI/WCAG21/Understanding/link-purpose-link-only). +explains [why link purpose in the text alone is good](https://www.w3.org/WAI/WCAG21/Understanding/link-purpose-link-only). Use | Avoid -----------------------------------------------------------|------- @@ -130,7 +130,7 @@ For more information, see how to [configure apps](https://example.com). | For mo Adding links can often provide helpful context. It's a great way to offer additional information for those who want it, while letting those who know the concept skip past. -But having many links increases the chance readers leave the page and not return. +But having many links increases the chance that readers leave the page and don't return. Especially when writing how-to guides and procedures, try to minimize the number of links in the middle. Each link that's added gives another reason for the reader to not finish the article. @@ -184,8 +184,8 @@ see Content Design London's [Readability Guidelines on clear language](https://r ### Use direct sentences -You generally want be as direct as possible to keep the ideas simple. -By avoiding overly wordy phrases, you help make it clearer what needs to be done. +You generally want to be as direct as possible to keep the ideas simple. +By avoiding overly wordy phrases, you help make clearer what needs to be done. For example, try to avoid using sentences starting with `There is/are` or `It is` too often. @@ -239,8 +239,8 @@ Apply this even to negative contractions as there is some evidence people are less likely to skip the negative in `don't` than in `do not`. Avoid contractions that are uncommon or that might be confusing -(such as making readings think something is a possessive rather than a verb). -Make use to use `it's` only for a contraction of `it is`, not as a possessive. +(such as making readers think something is a possessive rather than a verb). +Use `it's` only for a contraction of `it is`, not as a possessive. Use | Avoid ---------------------------------------|------- @@ -254,7 +254,7 @@ Too many abbreviations can be confusing to readers. Make sure to explain any abbreviations that might be unfamiliar the first time they're used. Avoid abbreviations for Latin terms, such as `i.e.`, `e.g.`, and `etc.`. -as these aren't always understood correctly. +as these are always understood correctly. Use | Avoid ----------------------------------------------------------------------------|------- @@ -281,7 +281,7 @@ To login, run `platform login`. | To login, run `p Notes are pieces of information that stand outside the normal text flow. Use them for short ideas that aren't. -Don't use too many in one place or they lose their value. +Don't use too many notes in one place or they lose their value. There are three types of notes: @@ -316,7 +316,7 @@ Some of the rules are enforced with [Vale](https://docs.errata.ai/vale/about), a Because writing style is subjective and no checking tool is perfect, the rules are mostly set to warnings rather than errors. -So checks note when something might be wrong, +So check notes when something might be wrong, but use your common sense and ignore them when appropriate. One exception is spelling, which returns errors. @@ -333,4 +333,4 @@ To get the most out of the rules, [install Vale](https://docs.errata.ai/vale/ins and run it locally with the command `lint-prose` from the repository root. Or use it in your IDE, such as with [Vale for VS Code](https://github.com/errata-ai/vale-vscode). -All pull requests against the default branch are also checked by Vale automatically. \ No newline at end of file +All pull requests against the default branch are also checked by Vale automatically. From 2d3022e9885deed375c94e1ddffba18a0fbdd0a1 Mon Sep 17 00:00:00 2001 From: SKhubaib <107524270+SKhubaib@users.noreply.github.com> Date: Wed, 15 Jun 2022 14:22:31 +0500 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: Aaron Collier Co-authored-by: Ludovico Altana --- contributing/content-style.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/contributing/content-style.md b/contributing/content-style.md index 2fc4ad3176..e8adc9f505 100644 --- a/contributing/content-style.md +++ b/contributing/content-style.md @@ -102,7 +102,7 @@ Some guides to help you make sure your writing is inclusive and accessible to ev To make your content as accessible as possible, the purpose of a link should be clear from its text alone. Avoid links with text like `click here` -and instead, try to include meaning inside the link itself. +and instead try to include meaning inside the link itself. Remember to use the [proper format for links](./markup-format.md#links) @@ -185,7 +185,7 @@ see Content Design London's [Readability Guidelines on clear language](https://r ### Use direct sentences You generally want to be as direct as possible to keep the ideas simple. -By avoiding overly wordy phrases, you help make clearer what needs to be done. +By avoiding overly wordy phrases, you help make it clearer what needs to be done. For example, try to avoid using sentences starting with `There is/are` or `It is` too often. @@ -254,7 +254,7 @@ Too many abbreviations can be confusing to readers. Make sure to explain any abbreviations that might be unfamiliar the first time they're used. Avoid abbreviations for Latin terms, such as `i.e.`, `e.g.`, and `etc.`. -as these are always understood correctly. +as these aren't always understood correctly. Use | Avoid ----------------------------------------------------------------------------|------- @@ -281,7 +281,7 @@ To login, run `platform login`. | To login, run `p Notes are pieces of information that stand outside the normal text flow. Use them for short ideas that aren't. -Don't use too many notes in one place or they lose their value. +Don't use too many in one place or they lose their value. There are three types of notes: @@ -316,7 +316,7 @@ Some of the rules are enforced with [Vale](https://docs.errata.ai/vale/about), a Because writing style is subjective and no checking tool is perfect, the rules are mostly set to warnings rather than errors. -So check notes when something might be wrong, +So automated checks show when something might be wrong, but use your common sense and ignore them when appropriate. One exception is spelling, which returns errors. From 07fb204a7a23f9615697d27448c16b2218bb43dc Mon Sep 17 00:00:00 2001 From: Aaron Collier Date: Thu, 16 Jun 2022 07:52:53 +0200 Subject: [PATCH 3/3] =?UTF-8?q?=E2=9C=8F=EF=B8=8F=20Add=20missing=20object?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- contributing/content-style.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contributing/content-style.md b/contributing/content-style.md index e8adc9f505..e47a306be6 100644 --- a/contributing/content-style.md +++ b/contributing/content-style.md @@ -280,7 +280,7 @@ To login, run `platform login`. | To login, run `p ## Use notes appropriately Notes are pieces of information that stand outside the normal text flow. -Use them for short ideas that aren't. +Use them for short ideas that aren't part of the main idea. Don't use too many in one place or they lose their value. There are three types of notes: