From 307938f60af7cee4da542f276d75f60f2d251e75 Mon Sep 17 00:00:00 2001 From: Jordan Wood <104526584+thejordanwood@users.noreply.github.com> Date: Wed, 21 Aug 2024 16:36:58 -0500 Subject: [PATCH 1/5] Update plain-language.md --- _guide/plain-language.md | 146 +++++++++++++++------------------------ 1 file changed, 54 insertions(+), 92 deletions(-) diff --git a/_guide/plain-language.md b/_guide/plain-language.md index f8b5c126..3110ab6e 100644 --- a/_guide/plain-language.md +++ b/_guide/plain-language.md @@ -1,7 +1,7 @@ --- layout: guide title: Plain language -description: +description: How to use plain language to make your content accessible. excerpt: sidenav: docs categories: @@ -17,112 +17,74 @@ roles: - UX designer --- -## Overview +# Plain Language -You worked hard getting your content online. How do you make sure your readers can find, understand and use it? Apply plain language. Clear and direct writing makes your content [accessible](https://www.w3.org/WAI/WCAG21/Understanding/reading-level.html) (it's also the [law](https://www.plainlanguage.gov/law/)!). Plain language also helps people with different cognitive abilities. Or speakers of a non-English language. Or those who rely on audio to listen to text. -You might also be writing for the public. Or a group of experts. Either way, your audience's reading level is likely [lower than you think](https://literacyproj.org/). +Plain language helps make your content accessible by allowing your audience to quickly understand it the first time they interact with it. This helps people with different cognitive abilities, people whose first language isn’t English, and those that rely on audio to listen to text. -## Who this is for +Plain language means that your content is written as clear and simple as possible. Good plain language will help readers find what they need, understand it quickly, and use that information to meet their needs. -* CivicActions employees -* Public servants -* Government communications teams -* Anyone designing content for the public +## Basic guidelines for plain language -## A quick guide to plain language +1. Use short sentences. + - Try to write one idea per sentence. + - Avoid repeating words. +2. Use simple words. + - Try to keep the writing below an 8th grade reading level. + - Choose words your readers use. + - Imagine you're talking to your reader over the phone. What words would you use to answer questions directly? +3. Use an active voice. + - The subject of a sentence should be performing an action. + - For example, “You need to submit the form online.” You, as the subject of the sentence, are performing the action by submitting the form. +4. Write for your audience. + - People visit your website to do something. Before writing, identify the reader’s needs. + - How can you answer your reader’s top questions quickly? + - What do readers need to know or do after reading your content? +5. Make it scannable. + - Users don’t read, they scan. They often leave web pages within 10 to 20 seconds. + - Structure your content with clear headers and present them in a logical order. + - Use short paragraphs, bullet points, and lists to sort content into smaller sections that are easier to read. +6. Don’t use jargon. + - Business and technical jargon can be confusing. Try to use common words in place of jargon. + - Spell out acronyms the first time one is used. +7. Don’t use idioms. + - Idioms are only clear to people that are in a certain group. + - These can be confusing for someone whose first language isn’t English. + - Try to use simple words in place of phrases. -### Keep it simple +## Test your content -Avoid: +Now that you’ve written your content, it’s important to test it! This can help you improve your content. You can test your content using readability tools, listening to your content read aloud, and conducting user testing with your audience. -* Jargon and government legalese. If you have to use an acronym, spell it out first. -* Filler words. For example, use the word 'analyze' not 'conduct an analysis'. -* Repetitive words -* Irony or idioms -* Intro text. For example, "Welcome to our department homepage." +### Use a readability tool -Try: +Always run your content through a readability tool and try to get the reading grade level lower than 8th grade. Some common readability tools are: -* Using active voice throughout your site -* Writing one idea per sentence -* Using the simpler synonym. For example, 'use' not 'utilize'. -* Keeping the reading level between 6th and 8th grade reading level. Remember to remove proper nouns and titles. +- [Hemingway App](https://www.hemingwayapp.com/): This app highlights content that could be hard for your audience to read. +- [Readable](https://readable.io/): This is a paid service that analyzes your content to identify its readability score, grammar errors, and style issues. +- [Microsoft’s Flesch-Kincaid](https://support.microsoft.com/en-us/office/get-your-document-s-readability-and-level-statistics-85b4969e-e80a-4777-8dd3-f7fc3c8b3fd2): This can be used with Microsoft Word to calculate your content’s readability score. -### Write for your audience +### Use a text-to-speech reader +Text-to-speech (TTS) is a type of assistive technology that takes words on a digital device and reads it aloud. Simply hearing text read aloud can help authors better understand where improvements can be made. We recommend this tool: +- [Microsoft’s Immersive Reader](https://support.microsoft.com/en-us/topic/use-immersive-reader-in-microsoft-edge-78a7a17d-52e1-47ee-b0ac-eff8539015e1): In Microsoft Edge, this mode has a Read Aloud tool that can be used to read the text of a web page. -Before writing, ask yourself: What are your reader's needs? What do they need to know or do after reading your content? +### User testing with your audience +Automated readability tools won't catch everything. You'll need to test your content with humans too. When user testing, you can: -### Make it actionable +- Use tree testing to discover if menu labels and other content is easy to find. This is a research method where you ask users to look for important resources. +- Ask your users to read your content aloud. This can help you identify what words they may struggle with. Users can also rate the clarity of the language. +- Ask your users to paraphrase what they read to gauge their understanding. -People visit your website to do something: answer a question or complete a specific task. Ask yourself: what are the top questions my target reader wants to know? How can I answer it quickly? +## Resources -### Choose words your reader uses +- [Federal Plain Language guidelines](https://www.plainlanguage.gov/guidelines/) +- [Plain Language Association International guidelines](https://plainlanguagenetwork.org/plain-language/what-is-plain-language/) +- [WCAG 2.1 Reading level success criterion ](https://www.w3.org/WAI/WCAG21/Understanding/reading-level.html) -Imagine you're talking to your reader over the phone. What words would you use to answer questions directly? -You can also use different keyword research tools. Try Google's [Keyword Research Planner](https://ads.google.com/home/tools/keyword-planner/) or [Moz Analytics](https://moz.com/login?redirect=https://analytics.moz.com/pro). They can help you brainstorm user-friendly words and phrases related to your topic. +## Next steps -### Make it scannable +When you are ready to learn more, here are some further guides and resources that may help your content: -Structure your content with [clear headers](https://www.nngroup.com/articles/headings-pickup-lines/). Present headers in a logical order. This will help a user scan the content easily to figure out what it's about. Make it specific to the topic or sub-topic. The clearest headers tell you something useful. -Use bulleted lists to make content easy to scan. Remember: website users don't read, they scan. They often leave web pages within 10 to 20 seconds. +- [Accessible documents](https://accessibility.civicactions.com/guide/documents) +- [Social media guidelines](https://accessibility.civicactions.com/guide/social-media) +- [Additional tools](https://accessibility.civicactions.com/guide/tools) -### Test your content with a readability tool - -Always run your content through a readability tool. You can use [Hemingway App](https://www.hemingwayapp.com/), [Readable.io](https://readable.io/), or [turn on Flesch-Kincaid](https://support.microsoft.com/en-us/topic/get-your-document-s-readability-and-level-statistics-85b4969e-e80a-4777-8dd3-f7fc3c8b3fd2) if editing in Microsoft Word. Try to get the reading grade level lower than 8th grade. Before using the tool, remember to remove: - -* proper nouns -* titles -* any domain-specific language you have to use. For example, a medical term you might need to include in your content. - -### Listen to your text in Reader Mode - -There are many tools to help with the readability of your site. Some of them offer a text to speach functionality that makes it easy for people to listen to what you have written. In our testing, [Microsoft's Immersive Reader](https://support.microsoft.com/en-us/topic/use-immersive-reader-in-microsoft-edge-78a7a17d-52e1-47ee-b0ac-eff8539015e1) is one of the best. - -Simply hearing how text read out loud can help authors better understand where improvements can be made. - -### Do more "just enough" user testing with your audience - -See "[just enough](https://www.nngroup.com/articles/why-you-only-need-to-test-with-5-users/)" article. - -Automated readability tools won't catch everything. You'll need to test your content with humans too. You can test: - -* [Menu labels](https://www.nngroup.com/articles/tree-testing/) and micro-content. Keep your [user goals](https://www.nngroup.com/articles/task-scenarios-usability-testing/) in mind. -* Language. Ask your users to read your content out loud. What words do they stumble over? How do they rate the clarity of the language (on a scale from 1 to 5)? -* Understanding. Ask your users to paraphrase what they read. What did they summarize correctly? What did they miss? What did they get wrong? - -## Join a plain language community - -* [Digital.gov Plain Language Action and Information Network](https://digital.gov/communities/plain-language/). They promote plain language in all government communications. -* [Plain Language Association International LinkedIn](https://www.linkedin.com/groups/158634/). This group advocates for plain language in business, government, and law. - -## Find a plain language tool - -* [Hemingway App](https://www.hemingwayapp.com/) -* [Readable.io](https://readable.io/) -* [Flesch-Kincaid](https://support.microsoft.com/en-us/topic/get-your-document-s-readability-and-level-statistics-85b4969e-e80a-4777-8dd3-f7fc3c8b3fd2) (available in tools like Microsoft Word) -* [OpenAdvocate WriteClearly](https://www.openadvocate.org/writeclearly/) - [OpenAdvocate on GitHub](https://github.com/openadvocate/writeclearly-server) - -## Helpful plain language resources - -### Guides - -* [USA Federal plain language guidelines](https://www.plainlanguage.gov/guidelines/) -* [USA Federal online training resources](https://www.plainlanguage.gov/training/online-training/) -* [USDS: Guide to accessibility for teams](https://accessibility.digital.gov/content-design/plain-language/) -* [California.gov Content Style Guide: Write in Plain Language](https://designsystem.webstandards.ca.gov/style/content/write-in-plain-language/) -* [South Australia: Steps to make your content plain language](https://www.accessibility.sa.gov.au/your-role/content/plain-language) -* [Content Design London: Readability Guidelines](https://readabilityguidelines.co.uk/) - -### Videos - -* [How Testing Your Documents Can Improve Plain Language Compliance](https://www.youtube.com/watch?v=fYJUdp83f_M) -* [Plain Language: Accessibility for Content](https://www.youtube.com/watch?v=n_WYcQnVOf4) - -### Organizations - -* [Center for Plain Language](https://centerforplainlanguage.org/) -* [Plain Language Association International](https://plainlanguagenetwork.org/plain/who-we-are/) - -### Events - -* Celebrate your plain language success on [Plain Language Day](https://plainlanguagenetwork.org/plain/international-plain-language-day/) (October 13) From e24446635a58aa4d472babb1d2ef912616a43b3a Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Wed, 21 Aug 2024 21:47:00 +0000 Subject: [PATCH 2/5] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- _guide/plain-language.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/_guide/plain-language.md b/_guide/plain-language.md index 3110ab6e..ffa22ff5 100644 --- a/_guide/plain-language.md +++ b/_guide/plain-language.md @@ -19,7 +19,7 @@ roles: # Plain Language -Plain language helps make your content accessible by allowing your audience to quickly understand it the first time they interact with it. This helps people with different cognitive abilities, people whose first language isn’t English, and those that rely on audio to listen to text. +Plain language helps make your content accessible by allowing your audience to quickly understand it the first time they interact with it. This helps people with different cognitive abilities, people whose first language isn't English, and those that rely on audio to listen to text. Plain language means that your content is written as clear and simple as possible. Good plain language will help readers find what they need, understand it quickly, and use that information to meet their needs. @@ -34,26 +34,26 @@ Plain language means that your content is written as clear and simple as possibl - Imagine you're talking to your reader over the phone. What words would you use to answer questions directly? 3. Use an active voice. - The subject of a sentence should be performing an action. - - For example, “You need to submit the form online.” You, as the subject of the sentence, are performing the action by submitting the form. + - For example, "You need to submit the form online." You, as the subject of the sentence, are performing the action by submitting the form. 4. Write for your audience. - - People visit your website to do something. Before writing, identify the reader’s needs. - - How can you answer your reader’s top questions quickly? + - People visit your website to do something. Before writing, identify the reader's needs. + - How can you answer your reader's top questions quickly? - What do readers need to know or do after reading your content? 5. Make it scannable. - - Users don’t read, they scan. They often leave web pages within 10 to 20 seconds. + - Users don't read, they scan. They often leave web pages within 10 to 20 seconds. - Structure your content with clear headers and present them in a logical order. - Use short paragraphs, bullet points, and lists to sort content into smaller sections that are easier to read. -6. Don’t use jargon. +6. Don't use jargon. - Business and technical jargon can be confusing. Try to use common words in place of jargon. - Spell out acronyms the first time one is used. -7. Don’t use idioms. +7. Don't use idioms. - Idioms are only clear to people that are in a certain group. - - These can be confusing for someone whose first language isn’t English. + - These can be confusing for someone whose first language isn't English. - Try to use simple words in place of phrases. ## Test your content -Now that you’ve written your content, it’s important to test it! This can help you improve your content. You can test your content using readability tools, listening to your content read aloud, and conducting user testing with your audience. +Now that you've written your content, it's important to test it! This can help you improve your content. You can test your content using readability tools, listening to your content read aloud, and conducting user testing with your audience. ### Use a readability tool @@ -61,11 +61,11 @@ Always run your content through a readability tool and try to get the reading gr - [Hemingway App](https://www.hemingwayapp.com/): This app highlights content that could be hard for your audience to read. - [Readable](https://readable.io/): This is a paid service that analyzes your content to identify its readability score, grammar errors, and style issues. -- [Microsoft’s Flesch-Kincaid](https://support.microsoft.com/en-us/office/get-your-document-s-readability-and-level-statistics-85b4969e-e80a-4777-8dd3-f7fc3c8b3fd2): This can be used with Microsoft Word to calculate your content’s readability score. +- [Microsoft's Flesch-Kincaid](https://support.microsoft.com/en-us/office/get-your-document-s-readability-and-level-statistics-85b4969e-e80a-4777-8dd3-f7fc3c8b3fd2): This can be used with Microsoft Word to calculate your content's readability score. ### Use a text-to-speech reader Text-to-speech (TTS) is a type of assistive technology that takes words on a digital device and reads it aloud. Simply hearing text read aloud can help authors better understand where improvements can be made. We recommend this tool: -- [Microsoft’s Immersive Reader](https://support.microsoft.com/en-us/topic/use-immersive-reader-in-microsoft-edge-78a7a17d-52e1-47ee-b0ac-eff8539015e1): In Microsoft Edge, this mode has a Read Aloud tool that can be used to read the text of a web page. +- [Microsoft's Immersive Reader](https://support.microsoft.com/en-us/topic/use-immersive-reader-in-microsoft-edge-78a7a17d-52e1-47ee-b0ac-eff8539015e1): In Microsoft Edge, this mode has a Read Aloud tool that can be used to read the text of a web page. ### User testing with your audience Automated readability tools won't catch everything. You'll need to test your content with humans too. When user testing, you can: From 22b3a25d10caf6544d23b5cc0428ad45046160af Mon Sep 17 00:00:00 2001 From: Jordan Wood <104526584+thejordanwood@users.noreply.github.com> Date: Wed, 21 Aug 2024 16:54:16 -0500 Subject: [PATCH 3/5] Update plain-language.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fixed title. Forgot that content of title appears in both

and and can’t be separated at this time. --- _guide/plain-language.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/_guide/plain-language.md b/_guide/plain-language.md index ffa22ff5..86d1184c 100644 --- a/_guide/plain-language.md +++ b/_guide/plain-language.md @@ -1,6 +1,6 @@ --- layout: guide -title: Plain language +title: Plain Language description: How to use plain language to make your content accessible. excerpt: sidenav: docs @@ -17,8 +17,6 @@ roles: - UX designer --- -# Plain Language - Plain language helps make your content accessible by allowing your audience to quickly understand it the first time they interact with it. This helps people with different cognitive abilities, people whose first language isn't English, and those that rely on audio to listen to text. Plain language means that your content is written as clear and simple as possible. Good plain language will help readers find what they need, understand it quickly, and use that information to meet their needs. From 5fd218108f95846538c637528bcdce11cd65fdb9 Mon Sep 17 00:00:00 2001 From: Jordan Wood <104526584+thejordanwood@users.noreply.github.com> Date: Wed, 21 Aug 2024 17:07:50 -0500 Subject: [PATCH 4/5] Update plain-language.md Changed - to * --- _guide/plain-language.md | 63 ++++++++++++++++++++-------------------- 1 file changed, 32 insertions(+), 31 deletions(-) diff --git a/_guide/plain-language.md b/_guide/plain-language.md index 86d1184c..1b05029e 100644 --- a/_guide/plain-language.md +++ b/_guide/plain-language.md @@ -24,30 +24,30 @@ Plain language means that your content is written as clear and simple as possibl ## Basic guidelines for plain language 1. Use short sentences. - - Try to write one idea per sentence. - - Avoid repeating words. + * Try to write one idea per sentence. + * Avoid repeating words. 2. Use simple words. - - Try to keep the writing below an 8th grade reading level. - - Choose words your readers use. - - Imagine you're talking to your reader over the phone. What words would you use to answer questions directly? + * Try to keep the writing below an 8th grade reading level. + * Choose words your readers use. + * Imagine you're talking to your reader over the phone. What words would you use to answer questions directly? 3. Use an active voice. - - The subject of a sentence should be performing an action. - - For example, "You need to submit the form online." You, as the subject of the sentence, are performing the action by submitting the form. + * The subject of a sentence should be performing an action. + * For example, "You need to submit the form online." You, as the subject of the sentence, are performing the action by submitting the form. 4. Write for your audience. - - People visit your website to do something. Before writing, identify the reader's needs. - - How can you answer your reader's top questions quickly? - - What do readers need to know or do after reading your content? + * People visit your website to do something. Before writing, identify the reader's needs. + * How can you answer your reader's top questions quickly? + * What do readers need to know or do after reading your content? 5. Make it scannable. - - Users don't read, they scan. They often leave web pages within 10 to 20 seconds. - - Structure your content with clear headers and present them in a logical order. - - Use short paragraphs, bullet points, and lists to sort content into smaller sections that are easier to read. + * Users don't read, they scan. They often leave web pages within 10 to 20 seconds. + * Structure your content with clear headers and present them in a logical order. + * Use short paragraphs, bullet points, and lists to sort content into smaller sections that are easier to read. 6. Don't use jargon. - - Business and technical jargon can be confusing. Try to use common words in place of jargon. - - Spell out acronyms the first time one is used. + * Business and technical jargon can be confusing. Try to use common words in place of jargon. + * Spell out acronyms the first time one is used. 7. Don't use idioms. - - Idioms are only clear to people that are in a certain group. - - These can be confusing for someone whose first language isn't English. - - Try to use simple words in place of phrases. + * Idioms are only clear to people that are in a certain group. + * These can be confusing for someone whose first language isn't English. + * Try to use simple words in place of phrases. ## Test your content @@ -57,32 +57,33 @@ Now that you've written your content, it's important to test it! This can help y Always run your content through a readability tool and try to get the reading grade level lower than 8th grade. Some common readability tools are: -- [Hemingway App](https://www.hemingwayapp.com/): This app highlights content that could be hard for your audience to read. -- [Readable](https://readable.io/): This is a paid service that analyzes your content to identify its readability score, grammar errors, and style issues. -- [Microsoft's Flesch-Kincaid](https://support.microsoft.com/en-us/office/get-your-document-s-readability-and-level-statistics-85b4969e-e80a-4777-8dd3-f7fc3c8b3fd2): This can be used with Microsoft Word to calculate your content's readability score. +* [Hemingway App](https://www.hemingwayapp.com/): This app highlights content that could be hard for your audience to read. +* [Readable](https://readable.io/): This is a paid service that analyzes your content to identify its readability score, grammar errors, and style issues. +* [Microsoft's Flesch-Kincaid](https://support.microsoft.com/en-us/office/get-your-document-s-readability-and-level-statistics-85b4969e-e80a-4777-8dd3-f7fc3c8b3fd2): This can be used with Microsoft Word to calculate your content's readability score. ### Use a text-to-speech reader Text-to-speech (TTS) is a type of assistive technology that takes words on a digital device and reads it aloud. Simply hearing text read aloud can help authors better understand where improvements can be made. We recommend this tool: -- [Microsoft's Immersive Reader](https://support.microsoft.com/en-us/topic/use-immersive-reader-in-microsoft-edge-78a7a17d-52e1-47ee-b0ac-eff8539015e1): In Microsoft Edge, this mode has a Read Aloud tool that can be used to read the text of a web page. + +* [Microsoft's Immersive Reader](https://support.microsoft.com/en-us/topic/use-immersive-reader-in-microsoft-edge-78a7a17d-52e1-47ee-b0ac-eff8539015e1): In Microsoft Edge, this mode has a Read Aloud tool that can be used to read the text of a web page. ### User testing with your audience Automated readability tools won't catch everything. You'll need to test your content with humans too. When user testing, you can: -- Use tree testing to discover if menu labels and other content is easy to find. This is a research method where you ask users to look for important resources. -- Ask your users to read your content aloud. This can help you identify what words they may struggle with. Users can also rate the clarity of the language. -- Ask your users to paraphrase what they read to gauge their understanding. +* Use tree testing to discover if menu labels and other content is easy to find. This is a research method where you ask users to look for important resources. +* Ask your users to read your content aloud. This can help you identify what words they may struggle with. Users can also rate the clarity of the language. +* Ask your users to paraphrase what they read to gauge their understanding. ## Resources -- [Federal Plain Language guidelines](https://www.plainlanguage.gov/guidelines/) -- [Plain Language Association International guidelines](https://plainlanguagenetwork.org/plain-language/what-is-plain-language/) -- [WCAG 2.1 Reading level success criterion ](https://www.w3.org/WAI/WCAG21/Understanding/reading-level.html) +* [Federal Plain Language guidelines](https://www.plainlanguage.gov/guidelines/) +* [Plain Language Association International guidelines](https://plainlanguagenetwork.org/plain-language/what-is-plain-language/) +* [WCAG 2.1 Reading level success criterion ](https://www.w3.org/WAI/WCAG21/Understanding/reading-level.html) ## Next steps When you are ready to learn more, here are some further guides and resources that may help your content: -- [Accessible documents](https://accessibility.civicactions.com/guide/documents) -- [Social media guidelines](https://accessibility.civicactions.com/guide/social-media) -- [Additional tools](https://accessibility.civicactions.com/guide/tools) +* [Accessible documents](https://accessibility.civicactions.com/guide/documents) +* [Social media guidelines](https://accessibility.civicactions.com/guide/social-media) +* [Additional tools](https://accessibility.civicactions.com/guide/tools) From 8c58881f3a3cd9d75785341d6707e6d01be0f6bc Mon Sep 17 00:00:00 2001 From: Jordan Wood <104526584+thejordanwood@users.noreply.github.com> Date: Wed, 21 Aug 2024 17:19:06 -0500 Subject: [PATCH 5/5] Update plain-language.md Fixed spacing --- _guide/plain-language.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_guide/plain-language.md b/_guide/plain-language.md index 1b05029e..114a5aad 100644 --- a/_guide/plain-language.md +++ b/_guide/plain-language.md @@ -77,7 +77,7 @@ Automated readability tools won't catch everything. You'll need to test your con * [Federal Plain Language guidelines](https://www.plainlanguage.gov/guidelines/) * [Plain Language Association International guidelines](https://plainlanguagenetwork.org/plain-language/what-is-plain-language/) -* [WCAG 2.1 Reading level success criterion ](https://www.w3.org/WAI/WCAG21/Understanding/reading-level.html) +* [WCAG 2.1 Reading level success criterion](https://www.w3.org/WAI/WCAG21/Understanding/reading-level.html) ## Next steps