Adding content

docs/pages/content-design/plain-language-checklist.md

@@ -0,0 +1,21 @@
+---
+title: Plain language checklist
+description: ODI's detailed guide for making sure content is in plain language
+---
+
+Adapted from the US Department of Labor’s [Use plain language for claimant notices](https://www.dol.gov/agencies/eta/ui-modernization/claimant-notices)
+
+| **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. |
+| [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. |
+| [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. |
+| [Uses lists](https://www.plainlanguage.gov/guidelines/organize/use-lists/) and [tables](https://www.plainlanguage.gov/guidelines/design/use-tables-to-make-complex-material-easier-to-understand/) to simplify complex material | Yes, No, N/A | When possible, provide information in lists, which are easier to process than large chunks of text. Tables can be used for more complex material. |

docs/pages/content-design/plain-language-equity-standard.md

@@ -0,0 +1,35 @@
+---
+title: Plain language equity standard
+description: ODI’s recommendations for how to help everyone understand content
+---
+
+<p class="text-lead">All state departments should:</p>
+
+* Provide information to the public at an 8th grade reading level or lower
+* Use smaller, more common words
+* Avoid jargon and technical terms as much as possible
+* Keep sentences short and simple
+
+This standard applies to print and digital information.
+
+## Key considerations
+
+It can be a challenge to balance plain language and accuracy. Achieve the lowest reading level you can.
+
+Write for your audience. Using technical terms might be appropriate if you're writing for a specialized audience. Examples include attorneys, scientists, or engineers.
+
+Cite laws, code, or regulations as written. Summarize this information whenever possible to help people understand it.
+
+## Definitions
+
+* Code: The text of laws, as found at [California Legislative Information](https://leginfo.legislature.ca.gov/)
+* Department: A department, commission, office, or other administrative agency of state government
+* Jargon: Words used by specialists that are not used or understood by the average person
+
+## Where to start
+
+* Begin with documents you are already working on.
+* Focus on documents that have the highest impact on outcomes for Californians like:
+  * Applications
+  * Appeals
+* When addressing language access issues, start by writing in plain language in English.

docs/pages/content-design/principles.md

@@ -0,0 +1,27 @@
+---
+title: Content design principles
+description: ODI’s 7 keys for writing great content, including ways to implement them
+---
+
+<p class="text-lead">Great content takes work. The good news is that anyone can do it.</p>
+
+These 7 principles contain strategies and tips to help you write excellent content.
+
+* [Focus on user needs and services](/style/content/focus-on-user-needs-services/)
+* [Meet your audience where they are](/style/content/meet-your-audience-where-they-are/)
+* [Build in accessibility from the start](/style/content/build-accessibility-from-start/)
+* [Be concise](/style/content/be-concise/)
+* [Write in plain language](/style/content/write-in-plain-language/)
+* [Write with a conversational and official voice](/style/content/write-with-conversational-official-voice/)
+* [Organize content strategically](/style/content/organize-content-strategically/)
+
+## Our inspiration
+
+We were inspired by the work of teams that came before us, including:
+
+* [18F](https://18f.gsa.gov/)
+* [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/)
+* [U.S. Digital Service](https://www.usds.gov/)

docs/pages/content-design/principles/be-concise.md

@@ -0,0 +1,44 @@
+---
+title: Be concise
+description: Simple writing supports equal outcomes.
+---
+
+<p class="text-lead">Government content is notorious for being long and complicated. It does not have to be. Simple writing supports equal outcomes.</p>
+
+## Standards
+
+Keep sentences short and simple.
+
+## Why this is important
+
+Short sentences and paragraphs are easier to read. Assume your audience includes:
+
+* People who use screen readers. Short sentences help screen readers provide natural inflections.
+* People who read at elementary levels. It’s harder to find and understand information in long sentences and paragraphs.
+* People with limited English fluency, but who do not trust translated content. These readers may translate as they read. Complex sentences make this difficult.
+
+When there is less to read, it’s easier for people to complete their task.
+
+## How to do this in your writing
+
+* Think about every word you use. Remove words that do not add value.
+  * For example: do not use the word **please**.
+* The [Hemingway Editor](http://hemingwayapp.com/) identifies long sentences that are hard to read and words that do not add value.
+  * One way to fix long sentences is to break them into two sentences.
+* Have one thought per sentence.
+* Do not duplicate content. This actually makes it harder for people to find information instead of easier.
+  * Saying the same thing multiple ways is one form of duplicate content.
+* Be direct and confident.
+  * People expect the government to be a source of truth. Stating the facts confidently reassures them they’re getting accurate information
+
+Here’s an example of how to make content more concise:
+
+**Complicated**
+
+> If an individual has a payment to submit to the Treasurer’s Office of Department of Weights and Measures that accompanies their license renewal, this payment must be submitted through the online portal at the same time of the submission of their application to the Department.
+
+**Concise**
+
+> You must pay your license fee when you renew your license. Use the Department of Weights and Measures online portal to renew and pay.
+
+Plainlanguage.gov has more tips for [writing concise content](https://www.plainlanguage.gov/guidelines/concise/). You can also see examples of how to improve government writing.

docs/pages/content-design/principles/build-accessibility-from-start.md

@@ -0,0 +1,93 @@
+---
+title: Build in accessibility from the start
+description: Accessibility goes beyond the technical components of a website. It’s about including everyone who has a right to information.
+---
+
+<p class="text-lead">We write for all Californians, not most Californians.</p>
+
+We must create content that:
+
+* Is easy to consume across different devices and bandwidths
+* Works with assistive technology
+* Addresses access challenges
+* Embraces California’s diversity
+
+Accessibility goes beyond the technical components of a website. It’s about including everyone who has a right to information. That’s everyone who lives in California. Our content must respect the variety of their experiences.
+
+## 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.
+
+## Why this is important
+
+Californians use a range of devices and have varying levels of education. Government content often assumes that people have access to fast devices and understand complicated language and internal jargon. This creates a barrier for many people, including those who most need the services the government offers.
+
+Content designed for people on a variety of devices from a range of backgrounds is easier for everyone to access, understand, and use.
+
+When a reader feels that the content is “for them,” this builds trust and empowerment.
+
+## How to do this in your writing
+
+Well-designed content is naturally accessible. Following the other content principles (like using plain language and being concise) will do a lot to make your content accessible. You can get the rest of the way there through a few extra steps.
+
+### Write for California’s rich tapestry of communities
+
+Keep the following Californians in mind when you write:
+
+* People with limited financial resources
+* People with limited internet access
+* People who live in difficult situations (like domestic violence)
+* People struggling with mental health issues (like depression or suicide)
+* People who are unhoused or without a fixed address
+* People with disabilities
+* People of all gender identities
+* Communities of color
+* Immigrants
+* Tribal communities
+* People of all ages
+* People with limited or no English fluency
+* Rural communities
+
+We can lower barriers to accessing services and increase trust in content by considering the experiences of these communities.
+
+### Be specific about program details
+
+When discussing benefits and services, state:
+
+* Minimum requirements
+* Any income restrictions
+* Eligible groups that might feel excluded
+* How their personal information is protected
+* Whether it’s available regardless of immigration status, including:
+  * Which immigrants are eligible
+  * If it counts under the public charge rule
+
+### Avoid content formats that are not accessible
+
+Documents that require third-party software are not accessible. This includes:
+
+* Word documents
+* Excel spreadsheets
+* PowerPoint slides
+* .zip files
+
+PDFs are viewable in a browser, but are still difficult for people to use. They:
+
+* Are not searchable through the site search
+* Are more difficult to open on a mobile device
+* Require people to download them to view
+  * If people download them on a mobile device and do not have unlimited data, this can cost them money.
+* Often do not perform well on low-end devices
+* Cannot be automatically translated
+* Hide content from the reader unless they are downloaded
+* Are meant to be printed, not read on a screen, and cannot be easily resized
+
+Do not make PDFs and other files the only way you provide a piece of information. It’s OK to have the content on a webpage and offer a PDF with the same info people can download to share or print.
+
+### Write descriptive link text
+
+Link text like **click here**, **read more**, and **more** are not useful to people who use screen readers. Write link text that gives readers a sense of what they’ll find if they select the link. Make your link text different for each URL you use. Using the same link text for multiple URLs confuses people, including those that use screen readers.
+
+### Add alt text to images
+
+Screen readers look for alt text. [Add useful alt text to images](https://accessibility.huit.harvard.edu/describe-content-images) so screen readers can describe images to people who use them.

docs/pages/content-design/principles/focus-on-user-needs-services.md

@@ -0,0 +1,36 @@
+---
+title: Focus on user needs and services
+description: Give people what they need and direct them to services.
+---
+
+<p class="text-lead">Give people what they need and direct them to services. Your website’s purpose is not to tell people what to think about the government or your agency.</p>
+
+## Why this is important
+
+People come to a government website to do something. This could be completing a transaction or learning what they need to do. If they cannot perform their task, people can feel stuck.
+
+People expect digital interactions in their lives, including their government interactions. It’s our job to meet this expectation.
+
+## How to do this in your writing
+
+When writing, ask yourself questions like:
+
+* How will someone use this information to take action?
+* What do they need to do on this page?
+* Have you given them enough information to complete their task?
+
+“We just want people to know this” is not a good reason to include content.
+
+Make sure all your content addresses users’ needs.
+
+* Make the top user needs central in your writing, using language familiar to the user. Do not prioritize the names of your program or people.
+* Talk about the services and benefits available today. People are most interested in the current state.
+  * People are not interested in how we got here or what’s coming.
+  * Do not apologize for the limits of a program.
+
+Encourage your stakeholders to focus their content on requirements instead of recommendations.
+
+* 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/).

docs/pages/content-design/principles/meet-your-audience-where-they-are.md

@@ -0,0 +1,34 @@
+---
+title: Meet your audience where they are
+description: Knowing who they are and what they need helps you design for them.
+---
+
+<p class="text-lead">All your content is for someone. Knowing who they are and what they need helps you design for them.</p>
+
+## Why this is important
+
+When you write with your audience in mind, your content is more likely to be useful to them. Content designed with an audience in mind makes people feel like they’re heard and understood.
+
+When content meets an audience where they are, it reduces the struggle to complete tasks. The audience’s cognitive burden is lower and they’re more pleased with their experience.
+
+Meeting the audience where they are shifts the burden of understanding processes from the user back to the government, where it belongs. It puts the “serve” back in “services.”
+
+## How to do this in your writing
+
+Think about things like:
+
+* Do people come to this content as part of a larger process? Processes can span multiple agencies.
+* What friction points exist in the process? Highlight how to work through them if you cannot solve them.
+* Does your audience have concerns that would block them from using your service? Address them.
+
+Do not assume you know everything about your audience and what they need. Work with user researchers to understand who your users are and how well they can complete tasks on your website. You may discover audiences and needs you do not know about.
+
+If possible, test your content with your audience before publishing it. Even if you only talk to one or two people, you can learn things you can use to improve your content.
+
+You cannot cover every situation or fix every aspect of a service. Focus on what you can do with content to make things better.
+
+### Google Analytics
+
+Google Analytics tracks user behavior on websites. It’s an easy way to learn about your audience and how well you’re meeting their needs. Performing full user research is important, but Google Analytics can answer a lot of questions without having to interview people.
+
+Talk with your web engineers about enabling Google Analytics on your website.