If you want a place to start, we have recommendations for how to use each type of resource.
From 561088607780cc9109901439ddedceb899483507 Mon Sep 17 00:00:00 2001 From: Michael Sullivan <69169190+m-sullivan7@users.noreply.github.com> Date: Wed, 20 Dec 2023 09:14:09 -0800 Subject: [PATCH 02/11] Update how-to-use.md Content QA fixes --- docs/pages/how-to-use.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/pages/how-to-use.md b/docs/pages/how-to-use.md index bc7a86eb..3796dd4d 100644 --- a/docs/pages/how-to-use.md +++ b/docs/pages/how-to-use.md @@ -22,11 +22,11 @@ Our training gives you access to best practices in innovation. They’re a great ## Recommended reading -ODI is always researching how to deliver great services. We save our favorite articles and tools to use them in our work. Our recommended reading is a good way to dive into a topic and expand your knowledge. +ODI is always researching how to deliver great services. We save our favorite articles and tools to reference them in our work. Our recommended reading is a good way to dive into a topic and expand your knowledge. ## Templates -We often make templates to streamline our work. Take our templates and use them as-is, or change them to fit your department, to make your work easier. +We often make templates to streamline our work. Take our templates and use them to make your work easier. Feel free to change them to fit your department. We’ve organized resources by topic. The topics on the Hub are: From dfc8f0d52319892de74d5e8295a3000fe6450550 Mon Sep 17 00:00:00 2001 From: Michael Sullivan <69169190+m-sullivan7@users.noreply.github.com> Date: Wed, 20 Dec 2023 09:16:27 -0800 Subject: [PATCH 03/11] Update principles.md Link update --- docs/pages/content-design/principles.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/content-design/principles.md b/docs/pages/content-design/principles.md index e5732caa..b67775af 100644 --- a/docs/pages/content-design/principles.md +++ b/docs/pages/content-design/principles.md @@ -24,5 +24,5 @@ We were inspired by the work of teams that came before us, including: * [Government Digital Service](https://www.gov.uk/government/organisations/government-digital-service) in the United Kingdom * The [Plain Language Action and Information Network](https://www.plainlanguage.gov/) at the US federal government * [Public Digital](https://public.digital/) -* [San Francisco Digital Services](https://digitalservices.sfgov.org/) +* [San Francisco Digital Services](https://www.sf.gov/departments/city-administrator/digital-services)) * [U.S. Digital Service](https://www.usds.gov/) From 2ff4422e9faf9a068e5450c40ab00adad2dae9f9 Mon Sep 17 00:00:00 2001 From: Michael Sullivan <69169190+m-sullivan7@users.noreply.github.com> Date: Wed, 20 Dec 2023 09:17:08 -0800 Subject: [PATCH 04/11] Update focus-on-user-needs-services.md Link update --- .../content-design/principles/focus-on-user-needs-services.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/content-design/principles/focus-on-user-needs-services.md b/docs/pages/content-design/principles/focus-on-user-needs-services.md index 473130fc..2702aeea 100644 --- a/docs/pages/content-design/principles/focus-on-user-needs-services.md +++ b/docs/pages/content-design/principles/focus-on-user-needs-services.md @@ -33,4 +33,4 @@ Encourage your stakeholders to focus their content on requirements instead of re * Use **must** when telling people what they need to do. * Use **should** as little as possible and only for recommendations. * When stakeholders want to use **should**, ask them if people have to do something or if it’s a suggestion. -* Learn more about how to write about requirements at [plainlanguage.gov](https://www.plainlanguage.gov/guidelines/conversational/use-must-to-indicate-requirements/). +* Learn more about [how to write about requirements at plainlanguage.gov](https://www.plainlanguage.gov/guidelines/conversational/use-must-to-indicate-requirements/). From b22e7524eb0b0e71366fb4422d7f6ea573af9e2d Mon Sep 17 00:00:00 2001 From: Michael Sullivan <69169190+m-sullivan7@users.noreply.github.com> Date: Wed, 20 Dec 2023 09:19:42 -0800 Subject: [PATCH 05/11] Update build-accessibility-from-start.md Link update --- .../content-design/principles/build-accessibility-from-start.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/content-design/principles/build-accessibility-from-start.md b/docs/pages/content-design/principles/build-accessibility-from-start.md index 064f7449..59a00bc6 100644 --- a/docs/pages/content-design/principles/build-accessibility-from-start.md +++ b/docs/pages/content-design/principles/build-accessibility-from-start.md @@ -16,7 +16,7 @@ Accessibility goes beyond the technical components of a website. It’s about in ## Standards -State law requires that state websites be accessible. Content writers are responsible for maintaining some of these standards. An accessibility audit service (like [SiteImprove](https://siteimprove.com/)) will check your website against accessibility standards and identify where you can take action. +State law requires that state websites be accessible. Content writers are responsible for maintaining some of these standards. An accessibility audit service (like [SiteImprove](https://www.siteimprove.com/)) will check your website against accessibility standards and identify where you can take action. ## Why this is important From 4cb6684370ece69277f983fcdb27958dfdbe4395 Mon Sep 17 00:00:00 2001 From: Michael Sullivan <69169190+m-sullivan7@users.noreply.github.com> Date: Wed, 20 Dec 2023 09:20:19 -0800 Subject: [PATCH 06/11] Update write-in-plain-language.md Removed outdated content --- docs/pages/content-design/principles/write-in-plain-language.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/pages/content-design/principles/write-in-plain-language.md b/docs/pages/content-design/principles/write-in-plain-language.md index 83779985..ed97ce86 100644 --- a/docs/pages/content-design/principles/write-in-plain-language.md +++ b/docs/pages/content-design/principles/write-in-plain-language.md @@ -61,5 +61,3 @@ Check reading levels with the [Hemingway Editor](http://hemingwayapp.com/). Elim * Use commas in numbers over 999. This helps people understand the order of magnitude. * Use the serial comma (also called the Oxford comma) to reduce confusion. It’s the comma that comes before **and** in a list of 3 or more. * For example: _We brought apples, bananas, and oranges_. - -The Office of Data and Innovation has more [plain language resources](https://docs.data.ca.gov/calinnovate-toolkit/NQUp2SeHnvd3YF16tw4N/readme/plain-language-resources) in their service delivery toolkit. From 16265543c2358685be2a287d75dcdd4b888923a1 Mon Sep 17 00:00:00 2001 From: Michael Sullivan <69169190+m-sullivan7@users.noreply.github.com> Date: Wed, 20 Dec 2023 09:22:25 -0800 Subject: [PATCH 07/11] Update write-with-conversational-official-voice.md Link text update --- .../principles/write-with-conversational-official-voice.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/content-design/principles/write-with-conversational-official-voice.md b/docs/pages/content-design/principles/write-with-conversational-official-voice.md index e8dfc5e6..639cda3a 100644 --- a/docs/pages/content-design/principles/write-with-conversational-official-voice.md +++ b/docs/pages/content-design/principles/write-with-conversational-official-voice.md @@ -30,7 +30,7 @@ A conversational tone and an official one can seem like they’re opposites of e * For example: _If you need benefits, apply by May 23, 2021_. Do not say _The benefits application deadline is May 23, 2021_. * Do not use **me** or **my**. It’s unclear if it refers to the reader or the writer. * Use transition words where it makes sense. Start sentences with **And** or **But** to show the relationship between pieces of information. - * Example (courtesy of [Plainlanguage.gov](https://www.plainlanguage.gov/guidelines/organize/use-transition-words/)): _A topic sentence may provide a transition from one paragraph to another. But a transition word or phrase (usually in the topic sentence) clearly tells the audience whether the paragraph expands on the paragraph before, contrasts with it, or takes a completely different direction._ + * Example (courtesy of [Plainlanguage.gov's Use transition words](https://www.plainlanguage.gov/guidelines/organize/use-transition-words/)): _A topic sentence may provide a transition from one paragraph to another. But a transition word or phrase (usually in the topic sentence) clearly tells the audience whether the paragraph expands on the paragraph before, contrasts with it, or takes a completely different direction._ * Vary the lengths of your sentences and paragraphs. This makes your writing sound natural. * Avoid jargon or unfamiliar terms. If you must use them, do so sparingly, and define them for the reader. From 8dc9a04561e203459d728811ce100058b05cfe83 Mon Sep 17 00:00:00 2001 From: Michael Sullivan <69169190+m-sullivan7@users.noreply.github.com> Date: Wed, 20 Dec 2023 09:23:01 -0800 Subject: [PATCH 08/11] Update plain-language-checklist.md Content QA fix --- docs/pages/content-design/plain-language-checklist.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/content-design/plain-language-checklist.md b/docs/pages/content-design/plain-language-checklist.md index ec2589cb..235d9562 100644 --- a/docs/pages/content-design/plain-language-checklist.md +++ b/docs/pages/content-design/plain-language-checklist.md @@ -8,7 +8,7 @@ Adapted from the US Department of Labor’s [Use plain language for claimant not | **Category** | **Rating** | **Tips** | | ----- | ----- | ----- | -| [Written for easy reading by the average reader](https://www.plainlanguage.gov/guidelines/audience/) | Grade 0-14 reading level, plus Postgraduate | Measure reading level to make sure it’s not too high for your audience. Check this through [Hemingway](https://hemingwayapp.com/). Target is 6th-8th Grade level. | +| [Written for easy reading by the average reader](https://www.plainlanguage.gov/guidelines/audience/) | Grade 0-14 reading level, plus Postgraduate | Measure reading level to make sure it’s not too high for your audience. Check this through [Hemingway](https://hemingwayapp.com/). Target is grade 8 or lower. | | [Organized to serve the reader’s needs](https://www.plainlanguage.gov/guidelines/organize/) | Yes, No, N/A | Content should be organized around what the reader wants to know and their potential next steps. | | [Has useful headings](https://www.plainlanguage.gov/guidelines/organize/add-useful-headings/) | Yes, No, N/A | Content should be organized around what the reader wants to know and their potential next steps. | | [Has useful headings](https://www.plainlanguage.gov/guidelines/organize/add-useful-headings/) | Yes, No, N/A | Headings act as landmarks that help people understand what they are about to read, so make these as clear as possible. For example, including “Unemployment insurance benefits” in your heading makes it clear to claimants which benefits they are about to read about, which can be helpful if individuals have applied for multiple benefits. | From c37372163a49aadb9b094b2fe1325b385e7f2aca Mon Sep 17 00:00:00 2001 From: Michael Sullivan <69169190+m-sullivan7@users.noreply.github.com> Date: Wed, 20 Dec 2023 09:25:37 -0800 Subject: [PATCH 09/11] Update odi-style-guide.md Content QA fixes --- docs/pages/content-design/odi-style-guide.md | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/docs/pages/content-design/odi-style-guide.md b/docs/pages/content-design/odi-style-guide.md index e8dbdc13..7b804950 100644 --- a/docs/pages/content-design/odi-style-guide.md +++ b/docs/pages/content-design/odi-style-guide.md @@ -130,7 +130,7 @@ Browsers show a page title when you hover over the page tab. It helps people kno Make the title the same as the H1 of the page, followed by a pipe and the site name. This gives people a full understanding of the page. > Example: -> Content style guide | California Design System +> ODI's style guide | Innovation Hub ### Webpage URLs @@ -204,19 +204,19 @@ Use more than one decimal place when using this rule or rounding would cause you > Example: > .04 deaths per 100K -### Fractions +Do not use 0.0. -Write fractions using a slash. This is more accurate than using decimal places. It’s also easier for people to understand. +Use 2 decimal places if you’re writing a price that isn’t a round number. > Example: -> About 2/3 of California’s cities and counties do not allow cannabis retail activity. +> The cost of a new license is $29.99. -Do not use 0.0. +### Fractions -Use 2 decimal places if you’re writing a price that isn’t a round number. +Write fractions using a slash. This is more accurate than using decimal places. It’s also easier for people to understand. > Example: -> The cost of a new license is $29.99. +> About 2/3 of California’s cities and counties do not allow cannabis retail activity. ### Numerals @@ -470,6 +470,10 @@ ODI calls its base organizational unit a **team**. Teams make up divisions. > The talent team recruits great people to work at ODI. > The user research team piloted Ethnio intercepts on state webpages. +### that is + +Use **that is** instead of **i.e.**, which is an abbreviation of the Latin phrase *id est*. This translates to “that is.” Writing out “that is” makes it clear to the reader what you mean. + ### Tribe When referencing a specific Native American community, capitalize **Tribe** or **Tribal** as a sign of respect. This follows federal [Bureau of Indian Affairs language guidelines](https://www.bia.gov/guide/editorial-guide#cultural-terms). In other contexts, do not capitalize. From bd64b6343837e1e2c5075a55a56e079556d821a3 Mon Sep 17 00:00:00 2001 From: Michael Sullivan <69169190+m-sullivan7@users.noreply.github.com> Date: Wed, 20 Dec 2023 09:27:15 -0800 Subject: [PATCH 10/11] Update plain-language-checklist.md Content QA fixes --- docs/pages/content-design/plain-language-checklist.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/content-design/plain-language-checklist.md b/docs/pages/content-design/plain-language-checklist.md index 235d9562..65088940 100644 --- a/docs/pages/content-design/plain-language-checklist.md +++ b/docs/pages/content-design/plain-language-checklist.md @@ -10,12 +10,12 @@ Adapted from the US Department of Labor’s [Use plain language for claimant not | ----- | ----- | ----- | | [Written for easy reading by the average reader](https://www.plainlanguage.gov/guidelines/audience/) | Grade 0-14 reading level, plus Postgraduate | Measure reading level to make sure it’s not too high for your audience. Check this through [Hemingway](https://hemingwayapp.com/). Target is grade 8 or lower. | | [Organized to serve the reader’s needs](https://www.plainlanguage.gov/guidelines/organize/) | Yes, No, N/A | Content should be organized around what the reader wants to know and their potential next steps. | -| [Has useful headings](https://www.plainlanguage.gov/guidelines/organize/add-useful-headings/) | Yes, No, N/A | Content should be organized around what the reader wants to know and their potential next steps. | | [Has useful headings](https://www.plainlanguage.gov/guidelines/organize/add-useful-headings/) | Yes, No, N/A | Headings act as landmarks that help people understand what they are about to read, so make these as clear as possible. For example, including “Unemployment insurance benefits” in your heading makes it clear to claimants which benefits they are about to read about, which can be helpful if individuals have applied for multiple benefits. | | [Uses sentence case](https://readabilityguidelines.co.uk/grammar-points/capital-letters/), even in titles and headings | Yes, No, N/A | Capitalize only proper nouns and the first word in sentences. This makes text easier to read and understand. | | [Uses “you” and other pronouns to speak to readers](https://www.plainlanguage.gov/guidelines/audience/address-the-user/) | Yes, No, N/A | Addressing the reader directly and using a human-centered tone helps readers understand what is relevant to them. | | Uses [short sections](https://www.plainlanguage.gov/guidelines/concise/write-short-sections/) and [short sentences](https://www.plainlanguage.gov/guidelines/concise/write-short-sentences/) | Yes, No, N/A | Overly complex sentences can be hard to parse. Review long sentences for core points and break them up into shorter sentences, grouping them by theme or timeline of events to increase clarity. | | [Uses the simplest tense possible](https://www.plainlanguage.gov/guidelines/conversational/use-the-present-tense/) | Yes, No, N/A | Speak in the present tense. Simple present is best. | +| [Uses active voice, not hidden verbs](https://www.plainlanguage.gov/guidelines/words/avoid-hidden-verbs/) | Yes, No, N/A | Use the strongest, most direct form of the verb possible. For example: “We scheduled a fact-finding interview” vs. “There was a fact-finding interview scheduled.” | | [Omits excessive words](https://www.plainlanguage.gov/guidelines/concise/write-short-sentences/) | Yes, No, N/A | Have one main idea per sentence. | | [Uses common, familiar words](https://www.plainlanguage.gov/guidelines/words/use-simple-words-phrases/) | Yes, No, N/A | Avoid legalese, jargon, and figurative language. | | [Places words carefully](https://www.plainlanguage.gov/guidelines/words/place-words-carefully/) | Yes, No, N/A | Avoid large gaps between the subject, the verb, and the object. Put exceptions last. Place modifiers correctly. | From b0588d30a3882a1bf873e74941abcd920ed55174 Mon Sep 17 00:00:00 2001 From: Michael Sullivan <69169190+m-sullivan7@users.noreply.github.com> Date: Wed, 20 Dec 2023 09:29:29 -0800 Subject: [PATCH 11/11] Update recommended-reading.md Content QA fixes --- docs/pages/content-design/recommended-reading.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/pages/content-design/recommended-reading.md b/docs/pages/content-design/recommended-reading.md index cf7c81d0..cc4dc927 100644 --- a/docs/pages/content-design/recommended-reading.md +++ b/docs/pages/content-design/recommended-reading.md @@ -9,7 +9,7 @@ description: Articles, guides, and tools to learn more about content design * [ODI's content design principles](/content-design/principles/) * [California Design System principles](https://designsystem.webstandards.ca.gov/principles/) -* [Government Code 6219](https://designsystem.webstandards.ca.gov/principles/), California’s plain language statute +* [Government Code 6219](https://leginfo.legislature.ca.gov/faces/codes_displaySection.xhtml?sectionNum=6219.&lawCode=GOV), California’s plain language statute * [US Web Design System principles](https://designsystem.digital.gov/design-principles/) ## Online courses @@ -19,10 +19,10 @@ description: Articles, guides, and tools to learn more about content design ## Style guides * [Associated Press (AP) Style](https://store.stylebooks.com/): ODI’s default for style questions not covered by [our style guide](/content-design/odi-style-guide/) -* [18F content guide](https://content-guide.18f.gov/) at the federal government +* [18F content guide](https://guides.18f.gov/content-guide/) at the federal government * [How to write for SF.gov](https://sfdigitalservices.gitbook.io/style-guide/city-standards) * [Federal plain language guidelines](https://www.plainlanguage.gov/guidelines/) at plainlanguage.gov -* Federal [style guides by government agencies](https://digital.gov/resources/style-guides-by-government-agencies/?dg) +* Federal [style guides by government agencies](https://digital.gov/resources/style-guides-by-government-agencies/) * [GOV.UK A to Z of style – words to avoid](https://www.gov.uk/guidance/style-guide/a-to-z-of-gov-uk-style#words-to-avoid): a list of some words that make your content less clear, created by a UK government content team ## How-to's @@ -70,7 +70,7 @@ description: Articles, guides, and tools to learn more about content design * [Hemingway Editor](http://hemingwayapp.com/) * [ODI’s plain language checklist](/content-design/plain-language-checklist/): detailed guidance on how to improve your writing -## +## Books * [Content Design](https://contentdesign.london/shop/content-design-by-sarah-winters-paperback) - Sarah Winters * [Writing for dollars, writing to please: The case for plain language in business, government, and law](https://a.co/d/3bHM6Md) - Joseph Kimble