Have a question? Contact us for help with general inquiries, feedback, or bugs.
- -{%- from "macros/contact-us-form-wrapper.njk" import wrappedContactForm -%} -{{ wrappedContactForm("Contact us") }} - -## Get support from developers - -Post questions on [GitHub](https://github.com/cagov/design-system) and leverage our digital community. diff --git a/docs/pages/content-design/odi-style-guide.md b/docs/pages/content-design/odi-style-guide.md new file mode 100644 index 00000000..832ae011 --- /dev/null +++ b/docs/pages/content-design/odi-style-guide.md @@ -0,0 +1,539 @@ +--- +title: ODI’s style guide +description: How ODI keeps our writing consistent, including the reasons for our choices +--- + +These are the Office of Data and Innovation’s conventions and standard terms for writing. Our content design principles provide general guidance in how to write well.
+ +## Capitalization + +Always use sentence case. It’s easier to read and understand. Only capitalize proper nouns and the first word of a sentence or bullet. + +> Examples: +> Your actions save lives +> Blueprint for a Safer Economy +> Public health orders are issued by the California Department of Public Health + +When a word or phrase could correctly be written in title case or sentence case, default to sentence case. + +When writing out a URL, use lowercase letters. But if it’s the first word in a sentence, capitalize the first letter. + +> Examples: +> Check myturn.ca.gov for walk-in clinics in your area. +> Vaccines.gov is the CDC’s vaccination portal. + +Capitalize acronyms. + +> Example: +> CDC + +Capitalize the suffix for time of day, and add a space before it. + +> Example: +> 10:40 AM + +When creating a link to a page or document on another website, use the same case for the link text that the visitor will find when they use the link. + +> Example: +> [Fact Sheet: Omicron Variant](https://www.cdph.ca.gov/Programs/CID/DCDC/Pages/COVID-19/Omicron-Variant-Fact-Sheet.aspx) + +When making a bulleted list, capitalize the first word in each bullet. + +> Example: +> The best thing we can do to limit virus spread and mutation is to: +> * Get vaccinated +> * Get your booster if you’re eligible + +## Dates + +Write out the month in a date. + +> Example: +> January 15, 2022 + +Do not use only numbers, which can lead to confusion. Some cultures interpret 9/5/2020 as May 9, 2020 instead of September 5, 2020. + +## Formatting + +### Bulleted list + +Use bulleted lists for a list of items that are related. They break up long blocks of text into shorter, easier-to-read lists. Do this wherever you have 2 or more nouns or verbs in a series. + +Give context for your list with a lead-in sentence followed by a colon: + +* Capitalize the first word in each bullet. +* Decide if your bullets will all be complete sentences or fragments. Do not mix both within one list. This confuses people. + * If your bullets are complete sentences, end them with periods. + * If your bullets are fragments, do not end them with periods. +* Do not make a list of more than two levels. This is hard for people to read. On websites, this often cramps text against the right margin on mobile devices. + +### Buttons + +On a website or digital service, use a button with a form or to highlight something people may want to do. + +* Be short, descriptive, and distinctive. +* Start with an active verb like **Apply**, **Submit**, or **Search**. This keeps the focus on what people need to do. + +Buttons make it easier to find and take actions. + +### Headings + +Use headings to break up blocks of text and make your content scannable. + +People scan content, especially online, rather than reading every word. When there are large blocks of solid text, they often scan in an F-shaped pattern. This is inefficient and makes what they’re looking for easy to miss. + +Headings serve as guideposts. They help people know which parts of the page they want to read more closely. Headings enable more efficient scanning, which looks like a layer-cake pattern. + +To make your headings effective: + +* Keep them short. +* Use sentence case. It’s easier to read and understand. +* Order headings (and your content) by priority. Start with what’s useful to most people and end with the information the fewest people need. If they are steps, go from first to last. +* Don’t use punctuation. +* Don’t make your heading a full sentence. + * Example: **What we do** is better than **ODI does many things to help state departments**. +* Don’t write headings as questions. Convey certainty whenever you can, not uncertainty. + * Example: **How the DIF helps** is better than **How does the DIF help?** +* Don’t skip heading levels. For example, don’t go straight from H2 to H4. Each level has its own style. Using levels consistently makes a good experience for readers. This also helps people using screen readers. +* Nest heading levels appropriately. For example, H3s can be used for content relevant to the H2 above it. But don’t go past H4. That much nesting is hard for readers to follow. + +### Links + +Links are embedded in text instead of standing alone. + +* Make the link title match the title of the destination page as much as possible. This helps people know they arrived in the right place. + * Example: A link named [Quarantine and isolation](https://covid19.ca.gov/quarantine-and-isolation/) goes to a page named **Quarantine and isolation**. +* Do not use **See more**, **Learn more**, **Here**, or **View more** in link names. They do not give people a good idea where they’ll go. Some of these phrases also assume everyone can see. +* Limit the number of links. Too many links make the text hard to read. If you have several relevant links, put them in a bulleted list after your main text. +* Have links support comprehension, not disrupt it. People often open links when they come to them. Do not link until it’s alright to send the person away (after you’ve conveyed your point). +* Open links in [the same tab and window](https://www.w3.org/TR/WCAG20-TECHS/G200.html). Only open content in a new tab or window when there’s a good reason to do so. Give people [warning when a new tab or window will open](https://www.w3.org/TR/WCAG20-TECHS/G201.html). This is especially important for people on mobile devices. Pages that open in new tabs can confuse people and disrupt their experience. + +### Notes and disclaimers + +When info (especially data in tables or graphs) needs an explanation, follow it with a note to provide clarity. Putting notes next to what they explain makes it easy for people to get more information if they want it. Make the note smaller to signal to the reader that it is secondary info. This makes it easy for people to skip the details if they want. + +### Numbered list + +Use numbered lists when you want to show information in a particular order. The numbers help people know there’s an order. They guide readers by providing a start and end. Do not use a numbered list if order does not matter. + +> Example: +> To get your $50 card, just: +> * Get your code (via email or text within 7-10 days) +> * Redeem and pick your reward (within 90 days) + +If you’re walking people through an important step-by-step process on a website, use a [step list component](https://designsystem.webstandards.ca.gov/components/step-list/readme/). It lets you add detail to each step and makes them more readable. + +### Webpage titles + +Browsers show a page title when you hover over the page tab. It helps people know what’s in a tab on their browser. + +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 + +### Webpage URLs + +Use the H1 of the page to create your URL. This helps search engines find the page. + +Replace spaces in the title with hyphens so search engines can read them. Delete the conjunctions, prepositions, and articles as long as the URL still keeps the same meaning. + +* A page titled **Request a birth certificate** would become **/request-birth-certificate**. +* Do not make **Prepare for a wildfire** into **/prepare-wildfire**. This has a different meaning. +* If your URL feels too long, consider shortening the page’s H1. Make sure both give enough detail so people know what the page is about. + +Use the site map to build the URL. If the birth certificate page lives under a page called **Services**, the URL would be: **alpha.ca.gov/services/request-birth-certificate**. + +## Numbers + +### Abbreviations + +#### Thousands (K) + +Write out the number. This is clear to people, even after translation. + +> Example: +> Grants of up to $15,000 are available. + +When writing numbers with limited space (like labels in a chart), use a K instead of writing out the full number. + +For rates that use 100,000 as their base, use “per 100K.” + +> Example: +> 15.2 cases per 100K + +#### Millions (M) + +For exact numbers where every digit is important, write out the whole number. + +> Example: +> 15,435,899 cases + +For round or approximate numbers, write out the word “million.” Use up to one decimal point. Do not add **.0** to the end of a number. This is extra text that does not increase understanding. Just use the whole number. + +> Example: +> There is $10.5 million in funding for the program. +> Nearly 40 million people live in California. + +For rates that use million as their base, write out the word “million.” + +> Example: +> Unvaccinated deaths per million: 7.2 + +When writing numbers with limited space (like labels in a chart), use an M instead of writing out the full number. + +> Example: +> $15M in funding + +### Commas + +Use commas in numbers over 999. People have trouble understanding more than three numbers in a row. Commas break up the number and make it easier for people to read. + +> Example: +> 15,000 testing sites + +### Decimals +Use decimals only when you need to. This reduces the amount of numbers people have to read. Only go to one decimal place in most situations. + +Example: +> 78.6% of population vaccinated +> 0.1 new deaths + +Use more than one decimal place when using this rule or rounding would cause you to show a value as 0 when it is not truly 0. This most often comes into play when reporting data. + +> Example: +> .04 deaths per 100K + +### Fractions + +Write fractions using a slash. This is more accurate than using decimal places. It’s also easier for people to understand. + +> Example: +> About 2/3 of California’s cities and counties do not allow cannabis retail activity. + +Do not use 0.0. + +Use 2 decimal places if you’re writing a price that isn’t a round number. + +> Example: +> The cost of a new license is $29.99. + +### Numerals + +In sentences, use numerals for all numbers, except for “one.” People recognize numerals more easily than numbers written as words. This is especially true when people scan text. Scanning is common when reading on a screen. + +> Examples: +> Choose one of the following options. +> There are 3 information sessions. + +If you have to start a sentence with a number, write it out. Try to avoid starting sentences with numbers so you can use numerals. + +> Example: +> Twelve cities in Los Angeles County allow cultivation of cannabis. + +### Times + +Use **AM** and **PM** with times. Put a space between the time and AM or PM. Convert times to the Pacific time zone. Unless your target audience is out of state, do not state the time zone since California is only in one time zone. + +> Example: +> The press conference is at 10:30 AM. + +If you use a dash when writing a time range, put a space between the dash and the times. + +> Example: +> The statewide call center is open 7 days a week: +> * Monday through Friday, 8:00 AM - 8:00 PM +> * Saturday and Sunday, 8:00 AM - 5:00 PM + +## Styling + +### Bold + +Use **bold** for emphasis, but sparingly. When too many things are emphasized, nothing stands out. + +Do not add bold to a heading. Heading style is usually set through a template for consistency throughout a document or site. If you need to change the heading style, do that in the template. + +On websites, adding bold tags to a heading can cause it to appear in the wrong font. + +### Italics + +In websites or digital services, do not use *italics*. This makes text harder to read. Use **bold** for emphasis instead. In an image caption or data chart note, use smaller text. + +### Larger introductory text + +On webpages, use larger introductory text on the first paragraph to state its most important takeaway. This sets people’s expectations about what they’ll find on this page and if it’s valuable to them. + +Making this text bigger emphasizes its importance and helps people see it. But because this text is larger, keep the paragraph brief. + +> Example: +> California has rules to keep workplaces safe from COVID-19. + +Only use larger introductory text in the first paragraph on a page. + +### Underline + +Do not underline text. On websites or documents shared online, it makes text look like a hyperlink. Use **bold** for emphasis instead. + +## Words + +### Alaska Native + +Use **Alaska Native** instead of **Inuit** or other Tribe names when referring to people descended from the native peoples of Alaska. This follows federal [Bureau of Indian Affairs language guidelines](https://www.bia.gov/guide/editorial-guide#cultural-terms). This may be abbreviated to **AI/AN** in charts as part of the American Indian/Alaska Native federal demographic group. + +### alright + +Use **alright** as a synonym for **OK**. Spell it this way and not **all right**. + +### American Indian + +In charts only, use **American Indian** instead of **Native American** when referring to people descended from the native peoples of the continental U.S. This follows federal demographic language (abbreviated to **AI/AN**). In all other cases, use “Native American.” + +### Asian American + +Use **Asian American** when referring to people of Asian descent. Capitalize this wherever it appears in a sentence. + +### Black + +Use **Black** when referring to people of African descent. Capitalize this wherever it appears in a sentence. + +### CA.gov + +Use CA.gov when writing about the ecosystem of state websites or the [State of California homepage](https://www.ca.gov/). This follows the California Department of Technology style. Use ca.gov when writing a URL, like digital.ca.gov. + +### Cal OES + +The **Governor’s Office of Emergency Services** is abbreviated **Cal OES**. This follows the [office’s](https://www.caloes.ca.gov/) style. Write out the full name before using the abbreviation on each page. + +### Cal/OSHA + +The **California Division of Occupational Safety and Health** is abbreviated **Cal/OSHA**. This follows the [division’s](https://www.dir.ca.gov/dosh/) style. Write out the full name before using the abbreviation on each page. + +### county + +Use **county** in lowercase when referring to a level of government. + +> Example: +> The county is paying for this program. + +Capitalize “county” if it starts a sentence. + +> Example: +> County testing facilities are open daily. + +Capitalize “county” when referring to a specific county. + +> Examples: +> Sacramento County is working to address homelessness. + +When referring to more than one county, do not capitalize “counties.” + +> Example: +> Orange, San Diego, and Imperial counties are working together to prevent wildfires. + +### data +Write data as if it’s singular. This sounds more natural and conversational than writing it as if it’s plural. + +> Example:> This data supports making a change. + +### directorate + +The collective term for ODI’s director and chief deputy director. + +### disability + +Use **people with disabilities** instead of **disabled people**. This affirms the humanity of people with a disability instead of defining them by their condition. + +If writing about people who share the same disability, be specific. + +> Example: +> There are new online tools to help blind people. + +### division + +The major organizational units of ODI are divisions. They are: + +* Operations +* Strategy, Partnerships & Training +* CalInnovate +* CalData + +### e.g. +Do not use Latin abbreviations like *e.g.* (which stands for *exempli gratia*, or “for example”). Many people do not understand them. Use **for example** instead. + +### executive team + +We use **executive team** to collectively refer to ODI’s senior leadership team and their direct reports (often deputy directors). + +### for example + +Use **for example** instead of **e.g**, which is an abbreviation of the Latin phrase *exempli gratia*. This translates to “for example.” Writing out “for example” makes it clear to the reader what you mean. + +### Governor + +Always capitalize the word **Governor**, either with or without their name. This follows the [Office of the Governor’s](https://www.gov.ca.gov/) style. + +> Examples: +> The Governor’s order +> Governor Gavin Newsom + +### homelessness + +Use **people who are homeless** or **people without homes** instead of **the homeless** or **homeless people**. This affirms the humanity of people in this situation instead of defining them by their present situation. + +### i.e. + +Do not use Latin abbreviations like **i.e.** (which stands for *id est*, or “that is”). Many people do not understand them. Use “that is” instead. + +### Latino + +Use **Latino** instead of **Latinx** or **Hispanic** when referring to people of Latin American or Spanish descent. + +### LGBTQ+ + +Use **LGBTQ+** instead of **LGBTQ** or similar initialisms. This is the prevailing convention among state departments. + +### Multi-race + +Use **Multi-race** only in dashboards or chart notes to refer to those of more than one race. Do not capitalize the “R” in race. + +### Native American + +Use **Native American** instead of **American Indian** when referring to people descended from the native peoples of the continental U.S. This follows the [California Native American Heritage Commission’s](https://nahc.ca.gov/) style. The one exception is in charts, where “American Indian” is used to match federal demographic language. + +### Native Hawaiian + +Use **Native Hawaiian** when referring to people of Hawaiian descent. This follows the federal [Department of the Interior’s](https://www.doi.gov/hawaiian) style. It can be abbreviated as **NHPI** in charts as part of the Native Hawaiian/Pacific Islander category. + +### Office of Data and Innovation + +When spelling out the full name of the office, use the word **and**. Do not use an ampersand (&). If you mention ODI more than once in the content, use **(ODI)** after the first use. Use **ODI** for all following references instead of writing out the full name. + +### OK + +Use **OK** instead of **okay**. + +### Pacific Islander + +Use **Pacific Islander** when referring to those descended from the peoples of Oceania. This follows federal demographic language. It can be abbreviated as **NHPI** in charts as part of the Native Hawaiian/Pacific Islander category. + +### senior leadership team +The collective term for ODI’s: + +* Director +* Chief deputy director +* Chief data officer +* Chief counsel +* Special advisor to the director + +### senior management team + +This term includes everyone with programmatic oversight and decision-making authority. It includes: + +* Executive team +* Management staff +* Select individual contributor staff, like the Government Relations Manager and Legislative & External Affairs Manager + +### staff +We call everyone who works at ODI **staff**. We modify this term to refer to specific groups within ODI. + +* Staff who do not manage people are **individual contributor staff**. +* Staff who manage people are **management staff**. + +### state + +Use **state** in lowercase when referring to: + +* The state of California as a place +* A level of government + +> Examples: +> The state is paying for this program. +> Neither the state nor federal government requires you to get vaccinated. +> The state of California is on the Pacific Ocean. + +Capitalize “state” if it starts a sentence. + +> Example: +> State testing facilities are open daily. + +Capitalize “state” when using the term **State of California** to refer to our state’s government. + +> Examples: +> The State of California is paying for this program. + +### team + +ODI calls its base organizational unit a **team**. Teams make up divisions. + +> Examples: +> The engineering team decided to use GitHub to host the website. +> The talent team recruits great people to work at ODI. +> The user research team piloted Ethnio intercepts on state webpages. + +### 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. + +> Examples: +> Yurok Tribe +> Kumeyaay Tribal lands +> The survivors of the shipwreck formed two tribes. + +### users + +The word **users** should be used only when you need to specifically indicate those who use an item or tool. + +> Example: +> This parking lot is reserved for wheelchair users. + +In most cases, it’s better to call them **people**. This affirms their humanity instead of seeing them only as users of a service. + +> Example: +> >This website is designed for people who use mobile devices. + +Do not use the word “users” where it can give the wrong meaning, such as in the context of drugs, addiction, or recovery. + +### white + +Use **white** when referring to people of European descent. Do not capitalize it unless it is at the start of a sentence. + +### zip code + +Though the United States Postal Service capitalizes it “[ZIP Code](https://tools.usps.com/go/ZipLookupAction!input.action),” use **zip code**. Most people don’t know that zip is an acronym. Using capital letters distracts readers. The unexpected capitalization makes them pause and question the content. The lowercase zip code is easier for people to understand and read. + +## Technical glossary + +The engineering team uses these abbreviations and capitalizations for consistency. + +* CMS - content management system +* CSS - cascading style sheets +* GitHub - code repository platform +* [JavaScript](https://www.w3schools.com/js/) - language +* [Markdown](https://www.markdownguide.org/) - language +* Microsoft Edge - browser +* [npm](https://docs.npmjs.com/about-npm) - software registry +* Nginx - web server +* Solr - search platform +* [Sass](https://sass-lang.com/) - language +* SCSS - syntax +* [WordPress](https://wordpress.org/download/) - a CMS +* jQuery - a JavaScript library +* CA.gov - see entry in [Words](/content-design/odi-style-guide#Words) section +* Bootstrap - a front end toolkit + +## Can’t find what you’re looking for? + +This guide doesn’t cover everything. If it doesn’t answer your question, here are resources the content team uses. + +### Inclusive language + +* Start with [Atlassian’s inclusive language guide](https://atlassian.design/content/inclusive-writing). It’s good general guidance. Their do’s and don’ts are helpful. +If you want advice on how to talk about a specific group, try the [CDC’s Preferred Terms for Select Population Groups & Communities](https://www.cdc.gov/healthcommunication/Preferred_Terms.html). It includes many terms that often come up in government work. + +### Other style questions + +For all other style questions, we use AP Style. It’s behind a paywall. But you can ask questions about AP Style in #odi-content-design on Slack. Someone on the content team with a subscription will get you an answer. + +### Suggest an addition + +If you think we should include something in this guide, let us know in #odi-content-design on Slack. diff --git a/docs/pages/content-design/plain-language-checklist.md b/docs/pages/content-design/plain-language-checklist.md new file mode 100644 index 00000000..4cee736a --- /dev/null +++ b/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. | diff --git a/docs/pages/content-design/plain-language-equity-standard.md b/docs/pages/content-design/plain-language-equity-standard.md new file mode 100644 index 00000000..fe7bcf10 --- /dev/null +++ b/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 +--- + +All state departments should:
+ +* 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. diff --git a/docs/pages/content-design/principles.md b/docs/pages/content-design/principles.md new file mode 100644 index 00000000..1b06c31b --- /dev/null +++ b/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 +--- + +Great content takes work. The good news is that anyone can do it.
+ +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/) diff --git a/docs/pages/content-design/principles/be-concise.md b/docs/pages/content-design/principles/be-concise.md new file mode 100644 index 00000000..e5ec0d0c --- /dev/null +++ b/docs/pages/content-design/principles/be-concise.md @@ -0,0 +1,44 @@ +--- +title: Be concise +description: Simple writing supports equal outcomes. +--- + +Government content is notorious for being long and complicated. It does not have to be. Simple writing supports equal outcomes.
+ +## 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. diff --git a/docs/pages/content-design/principles/build-accessibility-from-start.md b/docs/pages/content-design/principles/build-accessibility-from-start.md new file mode 100644 index 00000000..064f7449 --- /dev/null +++ b/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. +--- + +We write for all Californians, not most Californians.
+ +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. 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 new file mode 100644 index 00000000..473130fc --- /dev/null +++ b/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. +--- + +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.
+ +## 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/). diff --git a/docs/pages/content-design/principles/meet-your-audience-where-they-are.md b/docs/pages/content-design/principles/meet-your-audience-where-they-are.md new file mode 100644 index 00000000..c4d75c01 --- /dev/null +++ b/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. +--- + +All your content is for someone. Knowing who they are and what they need helps you design for them.
+ +## 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. diff --git a/docs/pages/content-design/principles/organize-content-strategically.md b/docs/pages/content-design/principles/organize-content-strategically.md new file mode 100644 index 00000000..702364d9 --- /dev/null +++ b/docs/pages/content-design/principles/organize-content-strategically.md @@ -0,0 +1,60 @@ +--- +title: Organize content strategically +description: Well-organized content helps readers find what they’re looking for. +--- + +Well-organized content helps readers find what they’re looking for.
+ +## Standards + +Put content first that is most important or affects the most people, then arrange the rest in descending order. Keep it in digestible chunks. + +## Why this is important + +Putting the most important information first makes it more likely you will meet people’s needs. This is because when people read online, most of the time they’re actually scanning. They could easily miss information in traditionally-written content. + +Dense content can discourage people from even attempting to read it. When you break up information into chunks, people can more easily find and understand it. + +## How to do this in your writing + +Arrange what your readers are looking for so they’re likely to see it. + +* Order content on your page like a funnel. + 1. Begin with the content that is most important or affects the most people. + 2. Make the next most important or applicable content the next section. + 3. Repeat until you get to your last section of content. This should be the content that applies to the fewest number of people (like specific groups). +* Headings are easy for readers to scan. Make your [headings useful](https://www.plainlanguage.gov/guidelines/organize/add-useful-headings/) so people understand what’s in that section. + * Use headings in descending order. Do not skip a level. + * Use three levels of headings (H2, H3, and H4). If you find yourself using H5 or H6 headings, your organization may be too complex. Break up the content into multiple pages. + * Only use one H1 per page for the title of the page. +* Break up large blocks of content into smaller chunks. + * Small paragraphs are easier to read. They also signal when a new topic begins. + * Empty space between paragraphs gives readers little breaks that make the content easier to read. + * The Nielsen Norman Group has a good guide on [how to chunk content](https://www.nngroup.com/articles/chunking/). +* Bullet points and lists add visual variety to pages and are easy to scan. + * Use a numbered list for processes and steps that occur in an order. +* Limit how much content is on a single page or screen. Too much information can overwhelm readers. + * It’s OK to have several short, focused pages instead of one large page that covers everything. + +### Accordions + +[Accordions](https://designsystem.webstandards.ca.gov/components/accordion/readme/) are expandable sections. They hide information unless someone opens them. This requires an extra click or tap, which means readers have to do extra work to get this information. People cannot scan for information that’s in an accordion. + +Only use accordions when: + +* A small group of people needs the information +* People only need certain information (like selecting one of several license types) +* Providing notes or disclaimers + +Do not use accordions: + +* If more than a third of your readers need the information in the accordion +* To make a page look shorter + +### FAQs + +Use frequently asked questions (FAQs) sparingly. Most of the time they are not actually frequently asked, but are a convention content writers default to. + +FAQs are hard for people to read, especially when there are a lot of them on one page. They also often duplicate content that’s already on your site. And by putting the content in the form of a question and answer, you’re at least doubling the text someone has to read to get the information. + +Use the same rules for accordions for FAQs. If more than a third of readers need the information, put it in your body content. diff --git a/docs/pages/content-design/principles/write-in-plain-language.md b/docs/pages/content-design/principles/write-in-plain-language.md new file mode 100644 index 00000000..83779985 --- /dev/null +++ b/docs/pages/content-design/principles/write-in-plain-language.md @@ -0,0 +1,65 @@ +--- +title: Write in plain language +description: Do the hard work to make content simple for people to understand. +--- + +We do the hard work to make content simple for people to understand.
+ +## Standards + +Aim for an 8th grade reading level or lower. Keep sentences short and simple. Use smaller, more common words. + +We recommend an 8th grade reading level because: + +* It lets people read with less effort. +* Kids who translate English content for their non-English-speaking parents can do this more easily. +* Translation into other languages is more accurate at this reading level. + +There's even a plain language requirement in [state law](https://leginfo.legislature.ca.gov/faces/codes_displaySection.xhtml?sectionNum=6219.&lawCode=GOV). + +## Why this is important + +Plain language ensures equal access to information. It helps Californians: + +* In general +* With limited English +* With intellectual and developmental disabilities + +[19% of Californians](https://oag.ca.gov/consumers/limited-english) say they speak English “less than very well.” 44% of Californians over the age of 5 speak a language other than English at home. + +Plain language lets people read with less effort. It reduces frustration and makes it easier for people to access services. People also trust information that’s easy to understand. + +It also reduces the workload of state staff. Examples include less: + +* Phone calls +* In-person appointments +* Data collection errors + +## How to do this in your writing + +Check reading levels with the [Hemingway Editor](http://hemingwayapp.com/). Eliminate very-hard-to-read sentences and minimize hard-to-read sentences. Check the reading level every time you edit content. + +* Use simple words. + * Your content still needs to be accurate. Do not sacrifice clarity for simplicity. +* Explain jargon when you have to use it. This includes proper nouns and government-centric terms. +* When using an acronym, spell out its full name first, followed by the acronym in parentheses. Afterwards, use just the acronym. + * If the name only appears once on the page, do not include the acronym. + * If an acronym is better known to your audience than the full name (like CDC), use the acronym only. When in doubt, spell out the full name. +* Tell people what they need to do instead of telling them what happens if they do not do something. It's easier for them to understand. + * For example, write **You must apply by February 10** instead of **If you do not apply by February 10, your application will not be accepted**. + * One way to avoid this is by removing [double negatives](https://www.plainlanguage.gov/guidelines/concise/use-positive-language/). +* Use [active voice](https://plainlanguage.gov/guidelines/conversational/use-active-voice/) and strong verbs. + * Do not use [hidden verbs](https://plainlanguage.gov/guidelines/words/avoid-hidden-verbs/). +* Do not use gerunds with **is** or **are**. A gerund is a verb that ends in -ing. + * For example: write **He helps** instead of **He is helping**. +* Write in present tense. +* When using **it**, **this**, **those**, and **these**, double check to make sure it’s clear what the pronoun refers to. +* Do not use directional references like **as above**. +* Write out or abbreviate months in dates instead of using numbers. Some cultures interpret 9/5 as May 9 instead of September 5. + * Use numerals instead of spelling out numbers. + * Only go to one decimal place. Only use decimals when you need to. + * 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. 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 new file mode 100644 index 00000000..16e264fd --- /dev/null +++ b/docs/pages/content-design/principles/write-with-conversational-official-voice.md @@ -0,0 +1,76 @@ +--- +title: Write with a conversational and official voice +description: Give reliable information with confidence. +--- + +Give reliable information with confidence.
+ +## Why this is important + +To be effective, government websites must inspire trust. The way to do this is to be a source of truth and speak to the reader comfortably and confidently. + +Government interactions have a reputation for being difficult. Many people bring this idea with them to their digital interactions with the State. To serve Californians, we must overcome this perception by writing in a way that better connects with the people we serve. Use empathy and compassion to understand the experiences of Californians and the challenges they face. + +Many web experiences now use a conversational tone. People have come to expect this tone in their digital interactions. When a government website uses a conversational tone, people feel comfortable because this tone is familiar. + +## How to do this in your writing + +A conversational tone and an official one can seem like they’re opposites of each other, but they work together well. Your content sounds **official** when you state facts clearly and confidently without modifiers or qualifiers. Your content is **conversational** when it’s in plain language that’s familiar to people and uses conventions similar to how people speak. + +### How to sound conversational + +* Read your writing out loud to hear how it sounds. This is especially helpful when you’ve done several rounds of edits. + * When speaking the text aloud, take a breath at each period and a pause at each comma. +* Approach writing like you’re helping a friend with a task. Be supportive without being superior. +* Think about how much work someone would have to do to retell this information. This reveals content that is complicated. + * Break ideas into small chunks for readers to help them understand. +* Use common contractions like **you’ll**, **it’s**, and **we’ll**. + * Do not use uncommon contractions like **this’ll**, **y’all**, and **ain’t**. +* Refer to people as **you**, and the government or department as **we**, as long as it’s clear who **we** refers to. This lowers the feeling of a divide between people and the State. + * 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._ +* 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. + +### How to sound official + +* Use active voice. It helps content sound official because it’s confident and direct. +* Use qualifying language like **approximately**, **around**, **about**, or **like** only when necessary. We use these words naturally when speaking to sound more accommodating, but people expect solid answers from the State. + * Be honest when the State does not have a definitive answer. + +### Finding the balance + +This example is too official, which can be hard to understand and confusing: + +> It is required that all people seeking to apply must do so prior to the deadline set by law of September 30. No applications shall be accepted after this date. + +This example is too informal, so readers may not trust it as a source of truth: + +> Listen up: you’ve got to get your application in before the end of the month. Don’t wait! Do it ASAP. + +This example strikes the right balance between being conversational and official: + +> Apply between August 1 and September 30. + +### Voice checklist + +Check your writing against these traits to make sure it’s conversational and official. + +| **Be** | **Do not be** | +| ----------------------- | ----------------------------------------------------------- | +| A source of truth | A source of opinions | +| Informative | Judgmental | +| Welcoming to everyone | Overbearing | +| Friendly | Fake | +| Official | Cold or distant | +| Conversational | Disrespectful | +| Straightforward | Blunt | +| Sensitive toward others | Patronizing, pretending that you know everything about them | + +### Use a style guide for consistency + +Style guides help you be consistent across your content. They standardize the way to write punctuation, dates, numbers, and other elements. Adopt an existing style guide if you often have questions about how to write something. + +If you want to adopt a style, but do not know how to choose one, [Associated Press (AP) Style](https://store.stylebooks.com/) is a good choice. diff --git a/docs/pages/content-design/recommended-reading.md b/docs/pages/content-design/recommended-reading.md new file mode 100644 index 00000000..cf7c81d0 --- /dev/null +++ b/docs/pages/content-design/recommended-reading.md @@ -0,0 +1,76 @@ +--- +title: "Recommended reading: content design" +description: Articles, guides, and tools to learn more about content design +--- + +The Office of Data and Innovation (ODI) periodically reviews and adds new resources. We select resources that are easy for people new to plain language and content design to understand and put into practice.
+ +## Principles + +* [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 +* [US Web Design System principles](https://designsystem.digital.gov/design-principles/) + +## Online courses + +* Cake Consultancy’s [Content design pathway course](https://cakeconsultancy.com/product/content-design-pathway-course/) + +## 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 +* [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) +* [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 + +### Accessibility + +* [Web Accessibility Toolkit](https://dor.ca.gov/Home/WebAccessibilityToolkit) - California Department of Rehabilitation +* Web Accessibility Initiative + * [Cognitive Accessibility Guidance](https://www.w3.org/WAI/WCAG2/supplemental/#-cognitive-accessibility-guidance) + * [An alt decision tree](https://www.w3.org/WAI/tutorials/images/decision-tree/) +* [How to: write good Alt Text](https://supercooldesign.co.uk/blog/how-to-write-good-alt-text) - Supercool +* [Write helpful alt text to describe images](https://accessibility.huit.harvard.edu/describe-content-images) - Harvard University +* [3 questions to help decide if an image doesn’t need alt text](https://www.boia.org/blog/3-questions-to-help-decide-if-an-image-doesnt-need-alt-text) - Bureau of Internet Accessibility, a for-profit company + +### Content design + +* [Why FAQs aren’t the answer you’re looking for](https://digitalblog.coop.co.uk/2018/09/13/why-faqs-arent-the-answer-youve-been-looking-for/) - Co-op +* [A guide to content design](https://design.shelter.org.uk/digital-framework/a-guide-to-content-design) - Shelter, a UK housing nonprofit + * [What is content design?](https://design.shelter.org.uk/digital-framework/a-guide-to-content-design#Aguidetocontentdesign-Whatiscontentdesign?) + * [Crits](https://design.shelter.org.uk/digital-framework/a-guide-to-content-design#Aguidetocontentdesign-Crits) +* [How content designers can convince subject matter experts content needs to change](https://medium.com/@WordsThatServe/how-content-designers-can-convince-subject-matter-experts-content-needs-to-change-522bde5fc6eb) - Lee Baker on Medium + +### Inclusive language + +* The University of Washington’s [IT inclusive language guide](https://itconnect.uw.edu/guides-by-topic/identity-diversity-inclusion/inclusive-language-guide/): terms often found in IT, with alternatives +* Atlassian’s [inclusive language guide](https://atlassian.design/content/inclusive-writing): alternatives to many terms and phrases +* Vox Media’s [Language, Please](https://languageplease.org/): a resource that defines many terms. In some cases it offers guidance on choosing terms +* Service Design Network’s [Supporting inclusive forms design with design systems](https://www.service-design-network.org/community-knowledge/supporting-inclusive-form-design-with-design-systems) + +### Plain language + +[Plainlanguage.gov](https://www.plainlanguage.gov/), maintained by the US federal government, is a great resource for how to implement plain language. Their site also includes [examples of plain language](https://www.plainlanguage.gov/examples/) in action. + +### Human-centered design + +* [Nielsen Norman Group](https://www.nngroup.com/articles/) + * [Content strategy](https://www.nngroup.com/topic/content-strategy/) + * [Information architecture](https://www.nngroup.com/topic/information-architecture/) + * [Writing for the web](https://www.nngroup.com/topic/writing-web/) + * [Web usability](https://www.nngroup.com/topic/web-usability/) + * [Why you only need to test with 5 users](https://www.nngroup.com/articles/why-you-only-need-to-test-with-5-users/) + +## Tools + +* [Hemingway Editor](http://hemingwayapp.com/) +* [ODI’s plain language checklist](/content-design/plain-language-checklist/): detailed guidance on how to improve your writing + +## + +* [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 diff --git a/docs/pages/contribute.md b/docs/pages/contribute.md deleted file mode 100644 index e69de29b..00000000 diff --git a/docs/pages/get-started.md b/docs/pages/get-started.md deleted file mode 100644 index 647b89c5..00000000 --- a/docs/pages/get-started.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Get started xx -description: Learn how you can get started with using the Innovation Hub. ---- - -What you need to know about the Innovation Hub depends on your role and discipline.
- -## Developers - -Learn [what’s different](/technical-approach/) about California’s Innovation Hub approach and how to install components. Learn about [Innovation Hub webpage structure](/structure/) and layout options. - -## UX and visual designers - -Start with the [visual design style guide](/style/design/). Learn about the [UI components](/components/) you can incorporate into your design. - -## Content designers - -Get familiar with the [guidelines for content design](/style/content/). - -## Everyone - -Everyone can benefit from the [Innovation Hub principles](/principles/). - -## Need help getting started? - -[Reach out to us](/contact-us/). We’re available to help you figure out how you can get started, even if you do not have a digital team. diff --git a/docs/pages/how-to-use.md b/docs/pages/how-to-use.md new file mode 100644 index 00000000..244a0733 --- /dev/null +++ b/docs/pages/how-to-use.md @@ -0,0 +1,32 @@ +--- +title: How to use the Hub +description: Recommendations for how to use each resource on the Innovation Hub +--- + +The Innovation Hub collects resources made and found by the Office of Data and Innovation (ODI). We share them to help state departments better serve Californians.
+ +Here are our recommendations for how to use each type of resource on the Hub. + +## Standards and principles + +They’re the big ideas that guide ODI’s work. If you’re new to a topic, the standards and principles are a good place to start. + +## Guides and playbooks + +These offer details about how to implement a standard or best practice. They can include step-by-step instructions to achieve a goal. Use guides and playbooks when doing work to achieve a great outcome. + +## Training + +Our training gives you access to best practices in innovation. They’re a great way to improve your knowledge and skills so you can deliver better services. + +## Recommended reading + +ODI is always researching how to deliver great services. We save our favorite articles and tools so we can use 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 with changes to fit your department, to make your work easier. + +## About ODI + +We partner with state departments to drive innovation. To learn more about ODI and our work, visit the [ODI website](https://innovation.ca.gov). diff --git a/docs/pages/human-centered-design/innovation-skills-accelerator.md b/docs/pages/human-centered-design/innovation-skills-accelerator.md new file mode 100644 index 00000000..9ffaf0fa --- /dev/null +++ b/docs/pages/human-centered-design/innovation-skills-accelerator.md @@ -0,0 +1,18 @@ +--- +title: Innovation Skills Accelerator +description: A 15-unit, self-paced course available to all State of California staff +keywords: +--- + +This 15-unit, self-paced course covers:
+ +* Human-centered design +* Innovative practices +* Problem definition +* Data analysis + +State of California staff can take the Accelerator for free. Just sign up with your ca.gov email address. + + + +Note: Clicking this link will take you from the Innovation Hub to innovate-us.org. This is not a state website. Be mindful of the information you provide while using that website. Their terms of use apply to any information you share with them. diff --git a/docs/pages/product-management/product-craft-accessibility.md b/docs/pages/product-management/product-craft-accessibility.md new file mode 100644 index 00000000..02d044f3 --- /dev/null +++ b/docs/pages/product-management/product-craft-accessibility.md @@ -0,0 +1,38 @@ +--- +title: "Product craft: accessibility" +description: Videos, guides, and presentations about how to help everyone access information +--- + +Making things accessible is an important part of product management. These are the ODI product managers’ favorite accessibility resources.
+ +## Web content + +* The Department of Rehabilitation’s (DOR) [Web Accessibility Toolkit](https://dor.ca.gov/Home/WebAccessibilityToolkit) is a great place to start. +* The [California Design System](https://designsystem.webstandards.ca.gov) is accessible out of the box. + +## PDFs (portable documents) + +The federal Accessible Electronic Document Community of Practice has [PDF training videos](https://www.section508.gov/create/pdfs/training-videos/). They explain and show how to make PDFs meet federal Section 508 requirements. + +[Module 3: Remediating PDFs for Accessibility](https://www.section508.gov/training/pdfs/aed-cop-pdf03/) describes how to: + +* Fix a PDF’s properties +* Add and adjust tags +* Adjust the reading and tab order +* Add alternative text to images and objects +* Set the document’s language properties + +DOR has a guide on [creating accessible content](https://dor.ca.gov/Home/HowToCreateAccessibleContent). They have a section on creating accessible PDFs. + +## Presentations + +DOR’s guide on [creating accessible content](https://dor.ca.gov/Home/HowToCreateAccessibleContent) also has a section on PowerPoint. + +## Videos + +* Build Capable has a guide on [how to add closed captions to videos](https://www.buildcapable.com/how-to-add-closed-captions-to-your-videos/) that people can turn on and off. +* We also like the UK’s National Health Service [accessibility guidance for content](https://service-manual.nhs.uk/accessibility/content). It covers: + * Audio description + * Closed captions + * Transcripts + diff --git a/docs/pages/product-management/run-of-show.md b/docs/pages/product-management/run-of-show.md new file mode 100644 index 00000000..5b43b063 --- /dev/null +++ b/docs/pages/product-management/run-of-show.md @@ -0,0 +1,19 @@ +--- +title: Run-of-show +description: How to keep things organized in the lead up to a launch, announcement, or update +--- + +A run-of-show tracker is a single unified table, organized by day and time.
+ +It’s sometimes called a “tick tock”. It’s a countdown to any launch and can even go beyond. + +It maps out the sequence of events to be sure you’ve covered every angle. It also makes sure the process is reviewed and approved. The run-of-show is a real-time checklist for making sure the “show” goes on as planned. + +You can use a run-of-show for: + +* A new product launch +* A site change timed to an announcement or campaign +* A major update that requires alignment across multiple stakeholders +* Any complex delivery that requires orchestrating dependencies across multiple teams + +## Example diff --git a/docs/pages/technical-approach.md b/docs/pages/technical-approach.md deleted file mode 100644 index 98635ceb..00000000 --- a/docs/pages/technical-approach.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: A different approach -description: An introduction to the technical approach of the California Design System. ---- - - diff --git a/docs/site/_includes/site-navigation.njk b/docs/site/_includes/site-navigation.njk index 5997babc..7678f227 100644 --- a/docs/site/_includes/site-navigation.njk +++ b/docs/site/_includes/site-navigation.njk @@ -27,16 +27,86 @@ + + + + - {% if env.dev %} - \ No newline at end of file +