Skip to content

Fixes grammar and brevity #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
SKhubaib wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Fixes grammar and brevity #1

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0088ed0
Fixes grammar and brevity
SKhubaib Jun 15, 2022
2d3022e
Apply suggestions from code review
SKhubaib Jun 15, 2022
07fb204
✏️ Add missing object
CollierCZ Jun 16, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 9 additions & 9 deletions contributing/content-style.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -107,7 +107,7 @@ 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
-----------------------------------------------------------|-------
Expand All @@ -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.
Expand Down Expand Up @@ -184,7 +184,7 @@ 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.
You generally want to 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.
<!-- vale Platform.condescending = YES -->

Expand Down Expand Up @@ -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
---------------------------------------|-------
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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 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.
Expand All @@ -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.
All pull requests against the default branch are also checked by Vale automatically.