18f / content-guide

18F Content Guide

⚠️ This guide has moved to the consolidated 18F guides repository.

18F Content Guide

This is the repository for the 18F Content Guide. This guide was developed for 18F employees, but we hope it's a useful reference for everyone.

For a detailed introduction, see how to use this guide.

History

18F's Content Guild (#g-content) maintains this guide.

We started by adapting GOV.UK’s work, and we’d like to thank their team for championing plain language and information accessibility. We've since expanded the guide to cover more topics, reorganized things, and moved the site from 18F Pages to Federalist. This guide is a work in progress, and we'll continue refining it over time.

Contributors

• Jamie Albrecht
• Emileigh Barnes
• Nicole Fenton
• Andre Francisco
• Britta Gustafson
• Jeannine Hunter
• James Hupp
• Andrew Maier
• Corey Mahoney
• Kate Saul
• Anna Heller Sebok
• Will Slack
• Tadhg O'Higgins
• Atul Varma
• Jeff Durland
• Ryan Johnson
• Michelle Rago

Development

The Content Guide uses USWDS-Jekyll.

To run it locally:

1. Clone the repository.
2. Install Jekyll and the necessary dependencies: bundle install
3. Run the web server with bundle exec jekyll serve
4. Visit the local site at http://localhost:4000

or

1. Install Docker for Mac.

2. Clone this repository.

3. From this repository directory, run:

   docker-compose up --build

4. Open http://localhost:4000

Public domain

As a work of the United States government, this project is in the public domain within the United States.

Additionally, we waive copyright and related rights in the work worldwide through the CC0 1.0 Universal public domain dedication.

content-guide's Issues

Washington, DC is the way to be

I propose a change to our style guide to remove the periods from "Washington, D.C." This is the way that the people of DC prefer, as is evident on dc.gov.

Preferring to use the naming conventions that the people of a country or city prefer is OpenStreetMap's policy, called the On the Ground Rule. (OpenStreetMap is an enormous and awesome open source project that has created a free map of the world for you and me.) I think this is generally a great policy that we should fork. The rule states:

If the dispute cannot be resolved through discussion, then the simple default rule is whatever name, designation, etc are used by the people on the ground at that location are used in the non-localized tags.

❤️

Presentation and composition of URLs/filenames

URLs are important and frequent, both in terms of referring to them and in terms of composing them so that they are reasonably sensible. Filenames follow most of the same rules, so should be addressed in the same section. Both are important aspects of modern content.

We currently don't have a section for URLs and filenames, but we should.

Use of stock imagery

If ever, when do we/when don't we? What makes it good/not good?

More alternative options on plain language page?

From https://twitter.com/rseymour/status/669262489549414402, a request for more alternatives on https://pages.18f.gov/content-guide/plain-language/. FWIW, this would also help me. :)

Citizen

Add guidance around using the word "citizen" as a generic term for people who live inside the U.S. Many government services serve non-citizens and individuals with various immigrations/visa statuses.

Could go in Conscious style section?

Duplicate info about numbers

See:

https://pages.18f.gov/content-guide/numbers-and-percentages/
https://pages.18f.gov/content-guide/specific-words-and-phrases/

I think we should cut the info under the word list (second link).

Typo/Grammar issues

"This guide takes into account that frustration as well as several commonly..."

• Should be "This guide takes that frustration into account, as well as several..."

"make a copy of this document and adapt its to your organizational needs."

• Should be 'it' not 'its'

Duplicate info about conciseness

Need to combine these:

https://pages.18f.gov/content-guide/structure-the-content/#keep-sentences-short-and-sweet

https://pages.18f.gov/content-guide/be-concise/ - if we keep this, we should give credit to GDS for it

Add section on guidance on writing for limited English proficiency users

This is a goal in the National Action Plan.
https://18f.slack.com/files/gregboone/F0DBY6YFJ/screen_shot_2015-10-28_at_10.00.31_am.png

Typo

@18F Great job with the guide, there's one small typo though after "websites" when giving the footnote:

https://twitter.com/OpsBug/status/618425204558200832

Add higher-level content principles

Working on this branch: https://github.com/18F/content-guide/tree/content-principles

Create voice and tone section

We do talk a bit about addressing the user as "you" and writing in an accessible way, but we don't yet have a dedicated voice/tone section.

Make a list of project-specific content guides

As content designers we sometimes build project-specific guides based on the specific needs of the project and the staff on the project. Let's collect examples of these somewhere in our 18F Content Guide.

For example:

• cloud.gov guide that addresses some technical writing topics very specific to that project.

Add mention of Hemingway App

@khandelwal suggested that we might mention the Hemingway App in the Content Guide — adding an issue as a reminder to add a small section about the app.

Update plainlanguage.gov entry in Resources section

Please replace "plainlanguage.gov" with Plain Language Action and Information Network (PLAIN) (linked to plainlanguage.gov) on the references page.

Names on second reference

Add guidance for how we refer to people on second reference, both inside and outside the organization.

Find a good place to link the 18F Open Source Style Guide

https://pages.18f.gov/open-source-guide/ is essentially a content guide for open source projects, including writing good readmes. We should find a nice visible way to integrate a link into this guide.

Thought experiment: we could even consider merging the two guides, since a decent-sized chunk of 18F content is open source project content.

Curious why "18F Content Guide" is using title case

Thanks

Revise and expand "Conscious language" guidance

Add something about ableist language along these lines?
https://twitter.com/lizduckchong/status/655952122484101120

Inconsistent use of quotes and italics

There seems to be an inconsistent use of quotation marks and italics to denote examples, sometimes in the same sentence. For example:

and (never “&” or “+,” unless part of an official title. For example, D.C. Tech Lady Hackathon + Training Day)

And other times a character is literally used without special formatting.

percent is preferred to %. For example, 10 percent of respondents cited. . .

and

Slash - avoid using /. Replace it with words.

https://pages.18f.gov/content-guide/specific-words-and-phrases/

There should probably be one style used to denote examples throughout the text.

Capitalization: proper nouns

Hi,
Thanks for the capitalization guidelines. Can you address proper nouns in the guidance? I know it's common sense, but I think it will be useful to remind readers of that exception. Thanks, Arva (USPTO)

Duplicate info about "citizens"

Need to combine these:

https://github.com/18F/content-guide/blob/18f-pages/_pages/our-approach/address-the-user.md#how-to-talk-about-the-public

https://pages.18f.gov/content-guide/conscious-style/#nationality

Years

'90s for 1990s. Likely for specific words and phrases section.

Consider adding guidance for Log in, Log-in, Login …

I've found this term can be tricky for people, especially when it's used as a noun vs. verb vs. adj.

"I couldn't log in to the website because the log-in page was totes janky." (Or whatever standard you guys decide on.)

Also I've been using this guide since it launched – thanks!

Clarify capitalization of URLs in non-narrative contexts

I think we want them to be lowercased everywhere unless there's a native style (to someone else's URL) that is CamelCase or something like that. But we should just get really clear about this and, more importantly, why. (I continue to be antsy about the content guide becoming a list of things rather than principles and reasons behind the things.

Add guidelines for interface instructions

Thread starts here: https://18f.slack.com/archives/g-content/p1458155182000024

I will draft something and run it by the team for discussion.

User Centered Design et al

user centered design? Or user-centered design? Same for human-centered design. And human-computer interaction (caps? hyphen?)

Seems in the same vein as open source software.

Plain Language Ideas from the Thanksgiving Table

For https://pages.18f.gov/content-guide/plain-language/

Modify > Change
Perform > Do
Purchase > Buy
Terminate > End
Navigate To > Go To
Image > Picture
Toggle > Switch
Obtain > Get
Configure > Set up
Execute > Run
Halt > Stop
Value > Number

Add front end guidance

I thought we had guidance in specific phrases about front end developer, but it looks like we only have back end. Did front end get removed?

Link to Content Guide in GitHub "website" field

It would be nice if the project's URL was in the GitHub project description space. (The "website" input to the right of the "description" input at the top of the repository page.) Otherwise, there's no way to find it from the project page.

https://pages.18f.gov/content-guide/

Idea: Add guidance on when to style words as code, and when to leave them styled as paragraph text.

It could look like this:

"Group each set of thematically related controls in a fieldset element. Use the legend element to offer a label within each one. The fieldset and legend element makes it easier for screen reader users to navigate the form.”

Or like this:

"Group each set of thematically related controls in a fieldset element. Use the legend element to offer a label within each one. The fieldset and legend element makes it easier for screen reader users to navigate the form.”

Could include guidance relating to how technical the audience is, is the code snippet going to be copied and pasted, and how jarring it is to read the content with a lot of code stylings.

Add more simple word choices

Go through this list and see if we should adopt any of these for our list of words to avoid.

http://www.kingcounty.gov/exec/styleguide/concisewriting/simplerwords.aspx

Fiscal Year

Guidance on capitalization and whether abbreviation is ok.

Add single space guidance

One space after a period. No exceptions.

Add guidance for mass emails/newsletters

More people are moving their email lists to MailChimp and are creating new lists of users of our products. They have been asking for guidance on 18F style for emails. Our content guidance could include:

• Subject line, header, and from best practices
• Newsletter specific tone
• Image, media, and video embedding guidance
• Length an organization guidance
• Strategies for responding

Image section

Add a guide for image. Could include:

• Common 18F sizes
• Link to accessibility requirements
• Copyright rules
• Cropping guidelines
• Sites to look for good images
• Guidelines for picking stock images
• When to use images vs graphics

Sticky Notes

The information on Sticky Notes on the "Specific words and phrases" page is incorrect. The trademark applies to "pads of adhesive-backed paper notes".

broken link in EITI example

In this paragraph on the "Optimize headings and titles" page, the example is outdated and the link goes to a 404 page:

For example, an interior page on the U.S. EITI site is titled “U.S. Natural Resource Sectors.” Before naming a page like this, you should compare the phrase “natural resources” to similar phrases like “natural deposits.” A Google Trend search comparing those two phrases, shows that “natural resources” is a much more popular search term.

...while this is a great reminder to revisit EITI keywords, that page no longer exists. Happy to fix this, but wanted to note it so I don't forget.

Marketing, promotion, and social media

We don't always have time to help partners promote the work we did together after launch—but we could provide overarching guidance on how to think about that well.

Question about FAQs

From previous work, I think an FAQ is sometimes super useful as a place to publicly track questions received and answers given via e-mail, which can then be moved en masse during a content sprint. An FAQ becomes a more public issues list, for example.

Rethink the prohibition on passive voice

The given rationale for avoiding passive voice is that it "allows the reader to more easily identify each sentence's subject." (https://pages.18f.gov/content-guide/active-voice/) However, when used effectively, passive voice actually serves to make the topic of the sentence the grammatical subject, therefore making it easier to discern.

A good example of this focus shift can be seen here:

(1) Congress passed the Complicated Documentation Act in 1866 to assuage fears that government paperwork was too easy for the public to understand.

(2) The Complicated Documentation Act was passed in 1866 to assuage fears that government paperwork was too easy for the public to understand.

The subject of the first sentence is Congress; the subject of the second is the act that's actually being written about. The second sentence is the better one for its purpose, and it is in the passive.

It is true that a writing style that leans heavily on the passive can sometimes feel dry, long-winded, and harder to read, but it's not true enough often enough to drop a blanket statement against it in a wide-reaching style guide like this one, especially when many people can't reliably identify the passive to begin with.

Please consider expanding that section to be more informative and to encourage people to make a deliberate choice about the voice they use based on what part of the sentence is the topic (not the subject) rather than following a blind law.

Add a section or guide about content research/testing

@khandelwal also suggested including a research/testing section in the Content Guide. This could take the form of a new section, or it could be its own guide. (We discussed this briefly during the blog huddle — topic warrants further discussion.)

cc @jeanninehunter @awfrancisco @emileighoutlaw @gboone

Use consistent section headings

The headings within the guide switch between topics (nouns) and directives (verb phrases). We could clean this up a bit and make it more scannable (happy to do it, just logging for now).

Include note for why we differ from GPO

We can use this, if you'd like:

Although we are aware of the GPO, we used AP as a basis for our style guide. We decided to use lower case lettering for a few reasons:

1. We feel that readers are slowed down by capital words. So even if we contradict the GPO,federal government is ultimately more friendly and faster to read and comprehend.
2. We took some inspiration from this plain language page and then adapted it. As I remember, the basic motivation was that big official capital Federal Government was uninviting and unnecessary. There’s only one federal government and we couldn't think of an example when the federal government would not be operating in an official capacity.
3. GPO's mission is producing 'the official information products of the U.S. Government.' GPO's style may govern for official information, but we think it's preferable for the rest of us to favor readability over officialness.

Encourage orgs to adopt a style "stack"

In most publishing places, there is typically an order of precedence when writing to a particular style. Usually, the order is:

1. In-house style
2. Adopted style guide (18F, Associated Press, Chicago Manual of Style)
3. Dictionary

If following AP, the dictionaries to follow are:

• Webster’s New World College Dictionary (not made by M-W)
• Webster's Third New International Dictionary

If following CMoS, the dictionaries to follow are:

• Merriam-Webster's Collegiate Dictionary
• Webster's Third New International Dictionary

Rather than tell organizations which books to use, I think adding a page to the Content Guide encouraging organizations to adopt their own "stacks" would add clarity to how an organization should publish their text and resolve ambiguities.

endorsements

Add guidance about not talking about specific products we use at 18F? Goes in Trademark and brands maybe?

Clean up Markdown for inline examples

We have several ways of showing text examples in the content guide. I will review and clean up the markdown.

Project names

Guidance on capitalization and general constructions of project names. For instance, do we prefer "openFOIA" or "OpenFEC."

URLs Should Never Stop Working: I think at some point they should

The language in there makes it sound like a "forever and ever" rule, but I would propose that ever a period of time with enough status codes (e.g. 301) then at some point the URLs should be sunset. This should also be driven by usage data, i.e. if you haven't had a hit on a URL after (x) years it's probably ok to retire.

This is in direct relation to a situation I've seen an agency "endure" where they maintain very out-dated URLs, including SSL certificates and redundant systems just to preserve a very legacy structure.

Create a CONTRIBUTING.md file with voting rules

I believe the content guild is using a fancy voting system to approve substantive additions/changes to the content guide. Can you detail this process in the repo? (I'm selfishly asking because I'd like to borrow this for the research guild's documentation.)