13 | {% endif %}
14 |
190 |
191 | {% if header.type == 'basic' or header.type == 'basic-mega' %}
192 |
193 | {% endif %}
194 |
15 |
30 |
31 |
32 |
33 |
3 |
4 |
20 |
61 |
62 |
67 |
68 |
69 |
--------------------------------------------------------------------------------
/_includes/footer.html:
--------------------------------------------------------------------------------
1 | {% assign identifier = site.data.usa_identifier %}
2 |
23 |
24 |
--------------------------------------------------------------------------------
/_layouts/redirect.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 |
5 |
19 |
6 |
7 | 
8 |
9 |
10 |
8 |
9 |
11 |
18 | {{ identifier.site_name }}
12 |An official website of the 13 | 14 | GSA’s Technology Transformation Services 15 | 16 |
17 |
63 |
66 | Looking for U.S. government information and services?
64 | Visit USA.gov
65 | Redirecting...
8 |If your browser doesn’t redirect automatically, you can 9 | do it manually.
10 | -------------------------------------------------------------------------------- /_pages/our-approach/address-the-user.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Address the user 3 | permalink: /our-approach/address-the-user/ 4 | sidenav: our-approach 5 | sticky_sidenav: true 6 | --- 7 | 8 | Content on government sites often makes a direct appeal to the public to get involved or take action. 9 | 10 | Address the user as _you_ whenever possible. For example: 11 | 12 | > You can email us at [18F@gsa.gov](mailto:18F@gsa.gov) or find us on [Twitter](https://twitter.com/18f). 13 | 14 | > Learn more about starting your MyRA account. 15 | 16 | If you’re creating content for multiple users—such as patients and their caregivers—address the primary user as _you_ and refer to secondary users by their roles or titles. 17 | 18 | We recommend against using the word _citizens_ when talking about the public. See the [inclusive language]({{ "/our-style/inclusive-language/#nationality" | relative_url }}) section for further guidance. 19 | -------------------------------------------------------------------------------- /_pages/our-approach/avoid-duplication.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Avoid duplication 3 | permalink: /our-approach/avoid-duplication/ 4 | sidenav: our-approach 5 | sticky_sidenav: true 6 | --- 7 | If something is written once and links to relevant information easily and well, people are more likely to trust the content. Duplicate content produces poor search results, confuses the user, and damages the credibility of our websites. 8 | 9 | If users can find two similar pieces of content on a subject, they might end up calling a helpline or sending an email to the first address they find because they aren’t sure they have the right information. 10 | 11 | There are thousands of federal websites. Collectively, they host hundreds of millions of pieces of content. What are you writing about? What are other agencies publishing? Are users across the country and the world seeing a coherent view? 12 | 13 | Before you publish something, check that the user need you’re trying to address has not already been covered: 14 | 15 | - Search for the content using search engines like Google, Bing, or DuckDuckGo. This is how most users will start, too. If content is already easy to find, duplicating it can lead us to compete with ourselves for search results. 16 | 17 | - Often, 18F team members write about a government service, tool, or program. Think authoritatively: What department or agency controls the thing you’re writing about? What information have they produced already? Use [usa.gov][] to search federal, state, and local government websites for the public. 18 | 19 | - Start significant projects with a [content audit][]. Identify how any existing information is used and whether it will be helpful to your users in its current state. If it isn’t, what must change for it to help you address your users’ needs? Focus your work on those changes. 20 | 21 | [content audit]: https://methods.18f.gov/decide/content-audit/ 22 | [usa.gov]: https://www.usa.gov/ 23 | -------------------------------------------------------------------------------- /_pages/our-approach/be-concise.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Be concise 3 | permalink: /our-approach/be-concise/ 4 | sidenav: our-approach 5 | sticky_sidenav: true 6 | subnav: 7 | - text: Keep sentences short and sweet 8 | href: '#keep-sentences-short-and-sweet' 9 | --- 10 | 11 | To keep content understandable, concise, and relevant, it should be: 12 | 13 | - Specific 14 | - Informative 15 | - Clear and concise 16 | - Brisk but not terse 17 | - Incisive (friendliness can lead to a lack of precision and unnecessary words) but human (not something generated by a faceless machine) 18 | - Serious but not pompous or emotionless—adjectives can be subjective and make the text sound more emotive and like spin 19 | 20 | You should: 21 | 22 | - Use contractions (such as _can’t_ and _won’t_) 23 | - Not let caveats dictate unwieldy grammar (for example, say _You can_ rather than _You may be able to_) 24 | - Use the language people are using 25 | - Use [Google Trends](https://www.google.com/trends) to check for common search terms 26 | - Use short sentences 27 | - Check sentences with more than 25 words to see if you can split them for clarity 28 | 29 | Words ending in *–ion* and *-ment* tend to make sentences longer and more complicated than necessary. Avoid turning verbs into nouns, a common sign of governmentese at work. 30 | 31 | ## Keep sentences short and sweet 32 | 33 | Craft sentences at 25 words or fewer, whenever possible. If a sentence has fewer than 14 words, [readers understand 90 percent of content](http://comprehension.prsa.org/?p=217). At 25 words, sentences are markedly more difficult to comprehend. 34 | 35 | We also recommend varying sentence length. Switching things up helps you keep readers interested. This tactic will also give you better control of your content’s [tone]({{ "/our-style/voice-and-tone" | relative_url }}) — a text with only short sentences can unintentionally sound terse. The occasional longer sentence adds a bit of narrative interest (and can help a piece of writing sound friendlier, too). 36 | 37 | Here’s an example of how you might transform a too-long sentence into something more manageable. 38 | 39 | Instead of: 40 | 41 | > Due to privacy and logistical considerations, passes cannot be replaced if lost or stolen; a new Paper Voucher must be accessed by going to our website and completing the same activities to obtain a new Paper Voucher. 42 | 43 | Use: 44 | 45 | > Unfortunately, we can’t replace lost or stolen passes. [Get a new pass on our website](https://www.recreation.gov/pass/). 46 | 47 | 48 | 49 | 50 | --- 51 | 52 | _Thanks to [GDS](https://www.gov.uk/guidance/content-design/writing-for-gov-uk), whom we looked to for inspiration when writing this page._ 53 | -------------------------------------------------------------------------------- /_pages/our-approach/gather-feedback.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Gather feedback 3 | permalink: /our-approach/gather-feedback/ 4 | sidenav: our-approach 5 | sticky_sidenav: true 6 | subnav: 7 | - text: How to give feedback 8 | href: '#how-to-give-feedback' 9 | - text: How to receive feedback 10 | href: '#how-to-receive-feedback' 11 | --- 12 | 13 | Giving and receiving feedback on writing is hard. Both need your time, energy, and care. That may feel daunting. But we all want our work to be strong and it only gets better with feedback. 14 | 15 | The beauty of the writing process is that it’s iterative — everyone (yes, everyone) writes crappy first drafts. The important thing is to share the draft, gather feedback, revise, and repeat. Even published content isn’t really “done.” It’s important to keep refining, and incorporating feedback from your readers is part of that process. 16 | 17 | Here are some ways to approach giving and receiving writing feedback. 18 | 19 | ## How to give feedback 20 | 21 | Start by reading the piece in its entirety before editing or making comments. Though you may be tempted to give line edits on an early draft, resist this temptation! It’s likely that much of the text will change from draft to draft, so your line-editing work may be lost by the final draft. Focus on the central goal or message of the piece—not specific wording or stylistic decisions. If you find yourself needing to comment on structural issues or key messages, it’s probably worth setting up a meeting to talk through things. 22 | 23 | As you read, think about the answers to the following questions: 24 | 25 | * Is it clear? 26 | * Is it easy to follow? 27 | * Are there any gaps or places you get lost? 28 | * How might someone feel after reading this? 29 | * Does it leave you with any questions? 30 | * Are there any places that could use a story or concrete examples? 31 | * Does it assume knowledge that the reader might not have? 32 | 33 | Respond as a reader and tell the writer: 34 | 35 | * What doesn’t feel right 36 | * What doesn’t make sense 37 | * What isn’t working — and what is! 38 | * What you want to know more or less about, and why 39 | * What questions you have 40 | * What doesn’t reflect your own experience 41 | 42 | Ask questions to help the writer revise: 43 | 44 | * Who is the audience? 45 | * Why does this matter? 46 | * What does this mean? 47 | * How does this help the reader? 48 | * What’s the most important thing for people to understand? 49 | * What do we want readers to do next? 50 | 51 | When people ask for feedback, they’re looking for your thoughts on what aspects of their work could be stronger. Even as you offer kindly worded suggestions for improvement, it’s nice to comment on what’s working in a piece, too. Everyone likes to receive recognition for what they’ve done well. Plus, you don’t want them to unknowingly change what’s working — sharing positive feedback can prevent them from doing so. 52 | 53 | Everyone needs feedback, even professional writers. Don’t second-guess yourself as the reader. You don’t have to have the solution or right answer. Ask questions, let the writer know if something doesn’t make sense, and tell them what you like. Finally, thank them for asking for your feedback. It’s not easy, and it shows that they care about the work and their reader. 54 | 55 | ## How to receive feedback 56 | 57 | It’s natural to feel timid about sharing your work, especially if it’s an early draft. But sharing work early in the writing process has great benefits. Your colleagues can help you identify the strengths and weaknesses of your piece, which can help you narrow your focus and determine which sections need the most work. Likewise, your colleagues can point out interesting areas that you could expand on. 58 | 59 | If you’re apprehensive about sharing your work, it can be helpful to label documents as drafts to help frame your readers’ expectations and perceptions. For example: ‘First draft: Giving feedback on writing.’ Sharing drafts with one person, rather than a larger group, can also help you ease into the process. 60 | 61 | First, be clear about the type of feedback you’re looking for to ensure you get comments that are useful for the stage of writing you’re in. Here’s a summary of some types of feedback you can ask for and at what stage: 62 | 63 | * Collaborative: These are some initial rough ideas—feel free to dig in and change anything. 64 | * High-level edits: Observations about a piece’s general concept, structure, and intent — are most useful for early drafts. Are the big ideas coming through? Does the structure make sense? Is the flow logical? 65 | * Line edits: Better suited to later, more finalized drafts, whose ideas are fleshed out and which could benefit from some polish. How’s the voice and tone? Is the writing clear and consistent? What doesn’t make sense? 66 | * Copyediting: We’re about to publish this — are there typos or awkward phrases? 67 | 68 | If your piece needs additional context, share it. There are all types of context that might be helpful: background information, strategies that have been tried in the past (and since abandoned), any legal considerations, audience needs or insights from research, or variations between our house style and a client’s content conventions. 69 | 70 | If you have a deadline, be honest and realistic about it. And if you’re unsure about how long it will take your reader to give feedback, be honest about that, too — it’s OK to ask them whether your expectations align with their timeframe. 71 | 72 | Lastly, show appreciation. Giving feedback takes time and energy. Thank the person for taking the time to read your piece and share their thoughtful observations. Consider sharing the end result with them so they can see how their feedback helped you. 73 | 74 | ### Additional resources 75 | 76 | - [Questions I ask when reviewing design](https://signalvnoise.com/posts/3024-questions-i-ask-when-reviewing-a-design), Jason Fried 77 | - [Writing Comments in the Margins](https://ctl.wustl.edu/resources/commenting-on-student-writing/#margins), Washington University 78 | - [The Power of Bad Ideas](http://www.core77.com/posts/22446/the-power-of-bad-ideas-22446), Steve Portigal 79 | -------------------------------------------------------------------------------- /_pages/our-approach/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Our approach 3 | permalink: /our-approach/ 4 | sidenav: our-approach 5 | sticky_sidenav: true 6 | subnav: 7 | - text: Start with user needs 8 | href: '#start-with-user-needs' 9 | - text: Do the hard work to make it simple 10 | href: '#do-the-hard-work-to-make-it-simple' 11 | - text: Write for everyone 12 | href: '#write-for-everyone' 13 | - text: Start small and iterate 14 | href: '#start-small-and-iterate' 15 | --- 16 | 17 | Here at 18F, we take an approach that is based on user-centered principles, acknowledging the broad audience that government content is often addressing. The pages in this section expand on the principles below. 18 | 19 | ## Start with user needs 20 | 21 | Write in a way that suits the situation. Ask yourself: Who is going to read this? What do they need to know? How might they be feeling? 22 | 23 | Help people find the information they need quickly and easily. Guide them through the process. 24 | 25 | ## Do the hard work to make it simple 26 | 27 | Use plain language and simple sentences. 28 | 29 | Choose clarity over cleverness. 30 | 31 | ## Write for everyone 32 | 33 | Respect the complexity of our users’ experiences. 34 | 35 | Be willing to be surprised about who’s reading your work. 36 | 37 | ## Build trust 38 | 39 | Talk like a person. 40 | 41 | Tell the truth. 42 | 43 | Use positive language and concrete examples. 44 | 45 | ## Start small and iterate 46 | 47 | Make sure your content works for users. Don’t be afraid to scrap what’s there and start over. 48 | 49 | Write a draft, test it out, gather feedback, and keep refining. 50 | 51 | --- 52 | 53 | _We drew from multiple sources to develop this. Thanks to [GDS](https://www.gov.uk/design-principles), [MailChimp](http://styleguide.mailchimp.com/), and [Facebook](https://www.facebook.com/design/) for inspiration._ 54 | -------------------------------------------------------------------------------- /_pages/our-approach/keep-refining.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Keep refining 3 | permalink: /our-approach/keep-refining/ 4 | sidenav: our-approach 5 | sticky_sidenav: true 6 | subnav: 7 | - text: Testing and ongoing research 8 | href: '#testing-and-ongoing-research' 9 | - text: Archiving and deleting content 10 | href: '#archiving-and-deleting-content' 11 | --- 12 | 13 | Content design is an ongoing process, and even published content isn’t really “done,” in a traditional sense — it’s not a static entity. To ensure that your content is helping users, you need to keep refining it over time. 14 | 15 | When you’re creating content, it’s best to base your refinements on insights from users. This section addresses ways to test your content’s effectiveness and includes tips for archiving and deleting content without disrupting the user experience. 16 | 17 | ## Testing and ongoing research 18 | 19 | Set aside time regularly to make sure your content works for users. If you’re not sure where to start, check your web analytics to identify: 20 | 21 | * Pages with high or low traffic 22 | * Pages with high or low reading times 23 | * Common search terms 24 | * Common user flows within your site 25 | 26 | You can also review: 27 | 28 | * User feedback from surveys, call center logs, and support emails 29 | * Recurring themes from channels like Twitter, Facebook, and tech blogs 30 | 31 | You should make a habit of listening to users, too. Conduct [usability testing](https://methods.18f.gov/#usability-testing) sessions regularly to understand how people access, use, and interpret key pieces of content on your site. See [Looking at the different ways to test content](https://18f.gsa.gov/2016/04/19/looking-at-the-different-ways-to-test-content/) on the 18F Blog for more details. 32 | 33 | ### Additional resources 34 | 35 | * [Usability Testing](https://methods.18f.gov/#usability-testing), 18F Method Cards 36 | * [Testing Content](https://alistapart.com/article/testing-content), A List Apart 37 | * [What Does This Mean? Tips for Testing Your Words](https://userresearch.blog.gov.uk/2015/07/01/what-does-this-mean-tips-for-testing-your-words/), GDS Blog 38 | * [Testing Web Content for Accessibility](http://webaim.org/resources/evalquickref/), WebAim 39 | * [Cloze Test for Reading Comprehension](https://www.nngroup.com/articles/cloze-test-reading-comprehension/), Nielsen Norman Group 40 | 41 | ## Archiving and deleting content 42 | 43 | You may occasionally need to archive or delete outdated content. Maybe it’s irrelevant after a recent policy change or redundant with other pages on your site. Avoid moving or deleting content without a good reason, because it can cause a lot of frustration for users. Changes to site structure may also slow down users who’ve learned specific navigation paths on your site. 44 | 45 | As part of ongoing site maintenance, you should [audit your content](https://methods.18f.gov/#content-audit) to keep everything updated and identify [potential duplication]({{ "our-approach/avoid-duplication/" | relative_url }}). Depending on the size of your site, you may want to review everything on a yearly basis, for example, or look at one or two sections at a time. 46 | 47 | Before you archive or delete anything, review your site analytics to understand how users are accessing the content now, and check in with the content owner or author to come up with a plan together. Be sure to consider cases that may not show up in analytics data too, such as: 48 | 49 | * Search engine results 50 | * User bookmarks 51 | * Links from external sites 52 | 53 | Each of these can be addressed by ensuring you have [redirects from the old URLs]({{ "content-types/urls-and-filenames/#maintaining-urls" | relative_url }}) to the latest content. 54 | 55 | When you’re looking at a particular page, think about the best way to meet user needs: 56 | 57 | * Who is this content for? 58 | * Is there a legal requirement for having it? 59 | * How often do people visit this page? 60 | * Are there any incoming links to it, either within your site or from popular referrers? 61 | * Are there other pages that cover this topic? Can you combine them? Which one shows up higher in search results? 62 | * Can you hide or archive the page instead of deleting it? 63 | * Was this content meant to expire quickly? Was the website the right channel for this type of content — or should posts like this move to a blog, newsletter, or social media account in the future? 64 | 65 | If you genuinely need to delete something, give users a path to find what they need. This could include: 66 | 67 | * [URL redirects]({{ "content-types/urls-and-filenames/#maintaining-urls" | relative_url }}) 68 | * Ceding ownership of the content to another organization who can maintain it 69 | * Keeping content around and adding context that it is depreciated or no longer maintained 70 | * Making the content available elsewhere with an archiving service like the National Archives and Records Administration’s [Government Web Harvests](https://www.webharvest.gov/) or the [Internet Archive](https://archive.org/) 71 | * Custom 404 pages to help users find what they’re looking for 72 | 73 | ### Additional resources 74 | 75 | - [A Sestina on Sunsetting Content](https://18f.gsa.gov/2016/05/23/a-sestina-on-sunsetting-content/), 18F Blog 76 | - [Guidance on Managing Web Records](https://www.archives.gov/records-mgmt/policy/managing-web-records-index.html), National Archives and Records Administration 77 | - [Withdrawing and Unpublishing Content, and Labelling Content from Previous Governments](https://www.gov.uk/guidance/content-design/gov-uk-content-retention-and-withdrawal-archiving-policy), GOV.UK 78 | - [Unpublishing and Withdrawing ('Archiving')](https://www.gov.uk/guidance/how-to-publish-on-gov-uk/unpublishing-and-archiving), GOV.UK 79 | - [Best Practice for Archiving and Deleting Content](http://www.contentstrategyinc.com/best-practices-for-archiving-and-deleting-content/), Content Strategy Inc. 80 | - [How Should You Handle Expired Content?](https://moz.com/blog/how-should-you-handle-expired-content), Moz 81 | -------------------------------------------------------------------------------- /_pages/our-approach/make-content-web-friendly.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Make content web-friendly 3 | permalink: /our-approach/make-content-web-friendly/ 4 | sidenav: our-approach 5 | sticky_sidenav: true 6 | --- 7 | 8 | One of the simplest ways to present accessible, maintainable information online is to use HTML. 9 | 10 | It can be tempting to choose file formats that are more convenient for the author, such as PDF or Word. However, presenting content in PDF, Word, or similar formats can make content much harder to use. 11 | 12 | Therefore, we strongly recommend using HTML for all web content. Here are some of the benefits: 13 | 14 | - It’s much easier to link to specific pages or sections of HTML pages. 15 | - It’s much easier to update and maintain HTML content. 16 | - HTML content avoids breaking the user out of their browsing flow, and maintains the context of the site’s navigation and structure. Conversely, this often means that HTML pages are easier to re-find and less likely to be “orphaned” or left online beyond their usefulness. 17 | - All web content should be accessible, and this is much easier to accomplish and enforce with HTML content. It is possible to create accessible PDFs, but requires significant specialized training and effort for each document. 18 | - HTML content is generally more accessible to search engines, and even within a page, HTML content is often more searchable and scannable for users seeking specific information. 19 | - HTML content is much more responsive-friendly (especially on responsive websites), and some systems don’t display PDFs within the browser. This makes for a confusing user experience, and may cause some users to be unable to view or find the PDF at all. 20 | 21 | Here are some alternate approaches for situations in which people often choose PDFs: 22 | 23 | - **When the content includes images, tables, or other graphics that you aren’t sure how to display in existing page templates:** Instead, work with a designer or your web publishing team to explore how you can translate the information you need into native web content. 24 | - **Formal or policy documents that are infrequently or never updated:** Instead of using PDF to convey permanence, use document structure, clear timestamps, and design cues to help users understand the context they need to interpret the document. 25 | - **Manuals or other long documents:** These are especially crucial to make available as HTML content, especially because they often need to be kept up-to-date as technology or processes change. If you expect users to need offline access, support PDF as an alternate format or ensure clean, useful print stylesheets so that users can generate their own PDF. 26 | 27 | PDF-first may be the appropriate choice for content that’s primarily and only intended for print use. This might include brochures, business cards, or forms that must submitted as paper copies. (Though a better long-term approach is to change forms and processes so people can submit soft copies or complete the form online.) 28 | 29 | If you do choose to present content in PDF, remember to ensure the information is also available on your website in an accessible, linkable, and responsive HTML format. 30 | 31 | Avoid using formats for which users need specific, proprietary software (for instance, Microsoft Word, PowerPoint, Pages). 32 | -------------------------------------------------------------------------------- /_pages/our-approach/plain-language.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Use plain language 3 | permalink: /our-approach/plain-language/ 4 | sidenav: our-approach 5 | sticky_sidenav: true 6 | redirect_from: 7 | - /legal-and-technical-terms/ 8 | subnav: 9 | - text: Words to avoid 10 | href: '#words-to-avoid' 11 | - text: When to use legal and technical terms 12 | href: '#when-to-use-legal-and-technical-terms' 13 | - text: Additional resources 14 | href: '#additional-resources' 15 | --- 16 | 17 | U.S. government websites are for everyone. The content they contain should be as straightforward as possible. 18 | 19 | One of the best ways to make content clear and usable is to use **plain language**. When we use words people understand, our content is more findable, accessible, and inclusive. [Plain language](http://www.plainlanguage.gov/) is also mandatory for all federal government websites. 20 | 21 | When we use jargon in our writing, we risk losing users’ trust. Government, legal, business jargon are often vague or unfamiliar to users, and can lead to misinterpretation. 22 | 23 | Another temptation that can hurt readability is figurative language: it often doesn’t say what you actually mean, and can make your content more difficult to understand. For example: 24 | 25 | - drive (you can only drive vehicles, not schemes or people) 26 | - drive out (unless it's cattle) 27 | - going forward (unless you’re giving directions) 28 | - one-stop shop (we’re the government, not a big box store) 29 | 30 | In most cases, you can avoid these figures of speech by describing what you’re actually doing. Be open and specific. 31 | 32 | If you're struggling to use plain language, try writing conversationally. Picture your audience and write as if you were talking to them one-on-one, with the authority of someone who can actively help. 33 | 34 | **Don’t use formal or long words when easy or short ones will do.** Use _buy_ instead of _purchase_, _help_ instead of _assist_, _about_ instead of _approximately_, and so on. 35 | 36 | Plain language lists can help spot problem words and consider alternatives, but keep in mind that plain language is more than just a list of words to avoid—it’s a way of writing. 37 | 38 | ## Words to avoid 39 | 40 | - agenda (unless you’re talking about a meeting) 41 | - advancing 42 | - collaborate (use _working with_) 43 | - combating (use _working against_ or _fighting_) 44 | - commit or pledge (we need to be more specific — we’re either doing something or we’re not) 45 | - countering (use _answering_ or _responding_) 46 | - deliver (pizzas, mail, and services are delivered — not abstract concepts like improvements or priorities) 47 | - deploy (unless you’re talking about the military or software) 48 | - dialogue (we speak to people) 49 | - disincentivize or incentivize 50 | - empower 51 | - execute (use _run_ or _do_) 52 | - facilitate (instead, say something specific about _how_ you are helping) 53 | - focusing 54 | - foster (unless it’s children) 55 | - illegals or illegal aliens (use _undocumented immigrants_) 56 | - impact or impactful 57 | - initiate (use _start_) 58 | - innovative (use words that describe the positive outcome of the innovation) 59 | - in order to (use _to_) 60 | - key (unless it unlocks something, use _important_ or omit) 61 | - land (as a verb only use if you’re talking about aircraft) 62 | - leverage (unless you use it in the financial sense) 63 | - liaise (use _collaborate_, _work with_, or _partner with_) 64 | - modify (use _change_ instead) 65 | - overarching 66 | - progress (what are you actually doing?) 67 | - promote (unless you’re talking about an ad campaign or some other marketing promotion) 68 | - robust 69 | - simple or simply (use _straightforward_, _uncomplicated_, or _clear_, or leave the descriptor out altogether) 70 | - slimming down (processes don’t diet) 71 | - streamline 72 | - strengthening (unless you’re referring to bridges or other structures) 73 | - tackling (unless you’re referring to football or another contact sport) 74 | - thought leader (refer to a person’s accomplishments) 75 | - touchpoint (mention specific system components) 76 | - transforming (what are you actually doing to change it?) 77 | - user testing (use _user research_ or _usability testing_) 78 | - utilize (use _use_) 79 | 80 | ## When to use legal and technical terms 81 | 82 | Present complicated information clearly so it’s easier to understand. If you need to include legal terms or technical language, include a short, plain-language summary or define your terms up front. 83 | 84 | It’s fine to use technical terms when they’re appropriate for the audience or the situation, but you need to explain what they mean on the first reference. 85 | 86 | If you’re publishing source code, see the [18F Open Source Style Guide](https://pages.18f.gov/open-source-guide/) for tips on making the project easy to use and understand. 87 | 88 | ## Additional resources 89 | 90 | * [Federal Plain Language Guidelines](http://www.plainlanguage.gov/howto/guidelines/FederalPLGuidelines/TOC.cfm) 91 | * [Avoiding legal, foreign, and technical jargon](http://www.plainlanguage.gov/howto/guidelines/FederalPLGuidelines/writeNoJargon.cfm) 92 | * King County: [Shorter, simpler words](http://www.kingcounty.gov/exec/styleguide/concisewriting/simplerwords.aspx) 93 | * Gov.uk: [Plain English](https://www.gov.uk/guidance/content-design/writing-for-gov-uk#plain-english) and [Words to avoid](https://www.gov.uk/guidance/style-guide/a-to-z-of-gov-uk-style#words-to-avoid) 94 | -------------------------------------------------------------------------------- /_pages/our-approach/structure-the-content.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Structure the content 3 | permalink: /our-approach/structure-the-content/ 4 | sidenav: our-approach 5 | sticky_sidenav: true 6 | redirect_from: 7 | - /faqs 8 | - /how-users-read/ 9 | subnav: 10 | - text: Important information first 11 | href: '#important-information-first' 12 | - text: Short, punchy paragraphs 13 | href: '#short-punchy-paragraphs' 14 | - text: Descriptive headings 15 | href: '#descriptive-headings' 16 | - text: Heading tags 17 | href: '#heading-tags' 18 | - text: Lists 19 | href: '#lists' 20 | - text: Tables 21 | href: '#tables' 22 | - text: "Don’t use FAQs" 23 | href: '#dont-use-faqs' 24 | --- 25 | 26 | It can be a little confusing when we talk about the structure of content: most writers think of the structure of their writing along the lines of chapters, sections, headings and paragraphs. But we know that people read web content a little differently than, for example, a magazine essay. And HTML gives us tools to build pages that support readers, especially those who use assistive technologies. 27 | 28 | In this section, we will explain how to make it easier for all users to read your content. 29 | 30 | Reams of research tell us that people don’t read web pages; they scan them. It’s understandable — most often, people are trying to accomplish a task when they visit your site, rather than trying to educate themselves about the mission of your organization. 31 | 32 | So how do you support users that are just trying to get something done? 33 | 34 | ## Important information first 35 | Online, people tend to scan text until they find the information they need. No matter how carefully you craft your content, most people will only read 25 percent of it. This statistic isn’t meant to dishearten; rather, we believe it underscores the importance of getting content right. 36 | 37 | We recommend using the “inverted pyramid” style, putting the most important information at the beginning, and the second most important second, until the very least important information is delivered in the last thought. Hopefully you will have the research you need about your users to tell you what’s most important to them. Plan for user testing after launch to make sure you’ve got it right. 38 | 39 | ## Short, punchy paragraphs 40 | You might think of webpages as a series of little inverted pyramids, so that, as the reader’s eye lands on a particular chunk of text, they see the information that (we believe) is most important to them. 41 | 42 | ## Descriptive headings 43 | When readers are scanning your short paragraphs, it’s helpful for them to see a header that lets them know what they will find there. It’s better to be clear than clever here; your readers will be grateful that you saved them time by showing them where to find the thing they were looking for. 44 | 45 | ## Heading tags 46 | HTML offers critical help in guiding users to the information they are looking for. Heading tags, such as ``, ``, and so forth, allow you to describe a hierarchy of information on the page; these tags should be used for the descriptive headings you’ll want to use to introduce short and punchy paragraphs. Designers can assign visual styling to these headings, and people who use assistive technologies can skip from heading to heading as a kind of table of contents to find the thing they are looking for.
47 |
48 | ## Lists
49 | If you find yourself using several commas in a paragraph to separate items in a list, or if you repeat the same phrase over and over in a paragraph, you should probably use a bulleted list instead. Lists are easily scannable, and [studies have shown that our eyes naturally gravitate to list items](https://www.nngroup.com/articles/f-shaped-pattern-reading-web-content-discovered/). Assistive technologies, such as screen readers, will identify list items and read out the number of items in a list before reading out the list itself. If you’re listing several items, using an unordered (``) or ordered (``) list will benefit all users.
50 |
51 | That said, try to keep your lists as simple as possible. If you have several levels in your list, the complexity might overwhelm the benefits of using a bulleted list. If that’s the case, try using a table instead.
52 |
53 | ## Tables
54 | If you’re wrangling a lot of data, tables can help you visually organize that content. Long paragraphs cluttered with numbers or dates are more difficult to scan than, for example:
55 |
56 |
57 |
58 |
59 | Report type
60 | Dates covered
61 | Due
62 |
63 |
64 |
65 |
66 | Quarterly (Form 3, 3Z, 3L)
67 | January 1–March 31
68 | April 15
69 |
70 |
71 | April 1–June 30
72 | July 15
73 |
74 |
75 | July 1–September 30
76 | October 15
77 |
78 |
79 | October 1–December 31
80 | January 31
81 |
82 |
83 |
84 |
85 | ## Don’t use FAQs
86 |
87 | Like our peers at GDS, we [strongly discourage writing FAQs](https://www.gov.uk/guidance/content-design/writing-for-gov-uk#do-not-use-faqs), or Frequently Asked Questions.
88 |
89 | FAQs:
90 |
91 | * Are hard to read and search for
92 | * Duplicate other content on your site
93 | * Are usually not questions asked by the public
94 | * Mean that content is not where people expect to find it—it needs to be in context
95 |
96 | If you’re thinking about posting FAQs, review the related content on your site and look for ways to improve it. Take the necessary steps to [give users the best possible experience](http://alistapart.com/article/no-more-faqs-create-purposeful-information-for-a-more-effective-user-experi#section3).
97 |
98 | Ask yourself:
99 |
100 | * Is the content organized in a logical way?
101 | * Can you group similar topics together?
102 | * Is it easy to find the right answer?
103 | * Is it clear and up-to-date?
104 |
105 | If people are asking similar questions, the existing content isn’t meeting their needs. Perhaps you need to rewrite it or combine several pieces of content. Pay attention to what users are asking for and find the best way to guide them through the process.
106 |
--------------------------------------------------------------------------------
/_pages/our-style/abbreviations-and-acronyms.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Abbreviations and acronyms
3 | permalink: /our-style/abbreviations-and-acronyms/
4 | sidenav: our-style
5 | sticky_sidenav: true
6 | redirect_from:
7 | - /faqs
8 | - /how-users-read/
9 | ---
10 |
11 | Abbreviations are any shortened or contracted word or phrase. For example, writing *St.* instead of *Street*, or *Rx* for *prescription*, or *DC* for *District of Columbia*.
12 |
13 | Acronyms are a *type* of abbreviation. They shorten phrases in a specific way— using parts of the initial word or phrase (usually letters) to form an abbreviation. For example, *DIY* or *ASAP*.
14 |
15 | In the most technical sense, there is a difference between acronyms (abbreviations pronounced as words, like *NASA*) and initialisms (abbreviations pronounced as letters, like *FBI*). For simplicity, our content guide refers to both as acronyms. The readability issues that acronyms and initialisms create tend to be similar, and “acronym” is the more common term.
16 |
17 | **Acronyms often confuse readers. Avoid them whenever possible.**
18 |
19 | If an acronym is necessary for future reference, spell the full word and follow with the acronym in parentheses on the first reference. For example, *The General Services Administration (GSA)*.
20 |
21 | Some acronyms are more recognizable than their full spellings. For example, *NASA*, *NAACP*, *FBI*. In such instances, the acronym is always acceptable, at the writer’s discretion.
22 |
23 | At the writer’s discretion, refer to organizations on second reference with a shortened name instead of an acronym. For example, use *Labor* in place of *Department of Labor*, rather than *DOL.*
24 |
--------------------------------------------------------------------------------
/_pages/our-style/active-voice.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Active voice
3 | permalink: /our-style/active-voice/
4 | sidenav: our-style
5 | sticky_sidenav: true
6 | subnav:
7 | - text: How to recognize the passive voice
8 | href: '#how-to-recognize-the-passive-voice'
9 | - text: When to use the passive voice
10 | href: '#when-to-use-the-passive-voice'
11 | ---
12 |
13 | Our writing should be concise and direct. We prefer the active voice because it supports brevity and makes written content more engaging, too.
14 |
15 | The active voice helps the reader identify the subject of the sentence. In the following example, the person who submits the form is essential information. Omitting that leads to a confusing and impersonal sentence.
16 |
17 | **Passive**: _The request form must be submitted to the approving official._
18 | **Active**: _You must submit the request form to the approving official._
19 |
20 | Along with deemphasizing who should take an action, the passive voice is usually longer, too. Wordy instructions are harder to follow.
21 |
22 | **Passive**: _The case number should be saved in your records. It will be required for future inquiries._
23 | **Active**: _Save the case number in your records. You will need it for future inquiries._
24 |
25 | When in doubt, cut directly to the verb and give the reader clear directions.
26 |
27 | ## How to recognize the passive voice
28 |
29 | Use of the passive voice is common enough that many people don’t notice when they use it. Here’s a simple way to recognize it, [courtesy of Dr. Rebecca Johnson](https://twitter.com/johnsonr/status/259012668298506240): If you insert “by zombies” after the verb and the sentence still makes sense, you’re using the passive voice.
30 |
31 | ## When to use the passive voice
32 |
33 | Never use the passive voice in a way that makes actions seem like they happen without anyone doing them.
34 |
35 | You may occasionally need to use the passive voice to soften an error message or make something easier to understand.
36 |
37 | Rewording either of these sentences to use the active voice would complicate the sentence or pull focus away from its main point:
38 |
39 | > Forms __issued by the Office of Government Ethics__ include the OGE-450 and the OGE-278.
40 |
41 | > The agency __is required__ to respond to requests within 20 working days.
42 |
--------------------------------------------------------------------------------
/_pages/our-style/capitalization.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Capitalization
3 | permalink: /our-style/capitalization/
4 | sidenav: our-style
5 | sticky_sidenav: true
6 | subnav:
7 | - text: Personal titles
8 | href: '#personal-titles'
9 | - text: Headings
10 | href: '#headings'
11 | ---
12 |
13 | Follow a consistent capitalization scheme.
14 |
15 | Creating trustworthy internal and external communications relies, to a large extent, on the content’s consistency. Inconsistent spellings and capitalizations undermine your narrative authority. We follow these capitalization guidelines:
16 |
17 | - Do capitalize proper nouns, including names of individuals, places, and agencies
18 | - Don't capitalize _agile,_ unless it is the first word of a sentence
19 | - Don't capitalize _open source,_ unless it is the first word of a sentence
20 | - Don't capitalize _federal_ or _government_
21 |
22 | When you're deciding whether to capitalize noun phrases, keep in mind that in English, title case is often a marker of formality. Using it judiciously can help clarify that you're speaking about a specific, official thing (such as a form, office, or person). Overuse can cause users stress by implying formality or officialness where it doesn't exist. For instance:
23 |
24 | - It makes sense to capitalize the phrase _Form 1040, U.S. Individual Income Tax Return_ because you want users to know the exact, official title of that specific form.
25 | - It could confuse users to capitalize _income taxes_ or _income tax forms_, because those phrases could refer to any number of possible forms.
26 |
27 | See additional capitalization rules in the [specific words and phrases]({{ "/our-style/specific-words-and-phrases/" | relative_url }})
28 | section.
29 |
30 | ## Personal titles
31 |
32 | Don’t capitalize personal titles unless they precede a name. For example, *the director got approval* or *Director Lopez got approval*. Whenever possible, keep titles gender neutral. For example, we prefer *firefighter* to *fireman* and *chairperson* to *chairman*.
33 |
34 | ## Headings
35 |
36 | Headlines, page titles, subheads and similar content should follow sentence case, and should not include a trailing colon. For example:
37 |
38 | > _Making sense of Washington’s tech landscape_
39 |
40 | > _Privileges and responsibilities_
--------------------------------------------------------------------------------
/_pages/our-style/inclusive-language.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Inclusive language
3 | permalink: /our-style/inclusive-language/
4 | sidenav: our-style
5 | sticky_sidenav: true
6 | subnav:
7 | - text: Ability and disability
8 | href: '#ability-and-disability'
9 | - text: Age
10 | href: '#age'
11 | - text: Gender and sexuality
12 | href: '#gender-and-sexuality'
13 | - text: Nationality
14 | href: '#nationality'
15 | - text: Race, ethnicity, and religion
16 | href: '#race-ethnicity-and-religion'
17 | redirect_from:
18 | - /conscious-style/
19 | ---
20 | The words we use can make the difference between forging positive connections or creating distance in our personal and professional lives. Particularly in writing, impact is more important than intent.
21 |
22 | As we build government services, we want to ensure they are accessible and welcoming to everyone who needs to use them. Inclusive language helps us to be more accurate and build trust with our users.
23 |
24 | This guidance is influenced by the [Conscious Style Guide](http://consciousstyleguide.com/), which is an excellent resource for learning more about the conversations behind terms, categories, and concepts. Other resources we used:
25 |
26 | - [Diversity Style Guide](http://www.diversitystyleguide.com/)
27 | - [Disability Language Style Guide](http://ncdj.org/style-guide/)
28 | - [Associated Press Stylebook](http://www.apstylebook.com/)
29 | - [Syracuse University Disability Cultural Center Language Guide](http://sudcc.syr.edu/resources/language-guide.html)
30 |
31 | This page is not exhaustive, but aims to provide principles, resources, and specific suggestions for writing and talking about diverse groups of people.
32 |
33 | ## Ability and disability
34 |
35 | Every person is a whole person — no matter how they interact with the world. Focus on what they need to do, what tools they use, and avoid making assumptions. If a person’s situation, medical condition, illness, or injury is relevant to the content, be as specific as possible and avoid inserting value judgements about their circumstance (for example, use _has multiple sclerosis_, not _is afflicted with_ or _suffers from_).
36 |
37 | Just like with language around race, gender, or other identities, it’s always best to ask people how they identify rather than assuming. For help finding appropriate or accurate language, see the [Disability Language Style Guide](http://ncdj.org/style-guide/) from the National Center on Disability and Journalism.
38 |
39 | - Avoid describing people as _disabled_, _handicapped_, or _confined to a wheelchair_.
40 | - Avoid terms that contribute to stigmas around disability or mental illness: _crazy_, _dumb_, _lame_, _insane_, _psycho_, _schizophrenic_, or _stupid_.
41 | - Avoid terms that contribute to stigmas around sensory disabilities: _blind spot_ or _tone deaf_.
42 |
43 | ## Age
44 |
45 | Avoid referring to someone’s age, unless it’s relevant to what you're writing about (for example, when referring to benefits that are available to people of certain ages).
46 |
47 | - Don’t use women or older relatives as substitute for _novice_ or _beginner_. For example, don’t say something is [so simple your mother can use it](http://geekfeminism.wikia.com/wiki/So_simple,_your_mother_could_do_it).
48 | - We prefer _older person_ or _senior_ to _elderly_.
49 |
50 | ## Gender and sexuality
51 |
52 | Make content gender neutral wherever possible, and strive to write in a [gender-fair](http://www.ncte.org/positions/statements/genderfairuseoflang) way. If you’re writing about a hypothetical person or if you’re unsure of the person’s pronouns, use _they_ or _them_ instead of _he/she_.
53 |
54 | Avoid words and phrases that indicate gender bias, such as irrelevant descriptions of appearance.
55 |
56 | Use descriptors of gender identity or sexual orientation as modifiers, not as nouns (for example, _transgender person_, _cisgender person_, or _lesbian woman_). Avoid guessing sex, gender identity, or sexual orientation. When in doubt, either reconsider the need to include this information or ask the person you’re referring to how they identify and what terms they prefer.
57 |
58 | - Use _different sex_ instead of _opposite sex_ (because this recognizes gender as a spectrum, rather than a binary).
59 | - We support using _they_ or _their_ as singular pronouns.
60 | - Avoid _guys_ as a way to refer to mixed-gender groups.
61 | - Don't make assumptions about marital or family relationships (for example, use _spouse_ or _partner_ instead of _husband_ and _wife_; use _parent_ instead of _mother_ and _father_).
62 |
63 | For more detailed guidance, see the [National Lesbian and Gay Journalists Association Style Guide](http://www.nlgja.org/stylebook/terminology/) or the [GLAAD Media Reference Guide](https://www.glaad.org/reference/).
64 |
65 | ## Nationality
66 |
67 | Avoid using _citizen_ as a generic term for people who live in the United States. Many government programs serve non-citizens and individuals with a wide range of immigration and visa statuses.
68 |
69 | - How you refer to the public is largely dependent on context. Feel free to choose from any of these words: _people_, _the public_, _users_, or _folks_.
70 |
71 | - Be as specific as possible. Depending on the situation, you may want to say something like _people who need healthcare_ or _people who need to access government services online_.
72 |
73 | - Use _citizens_ for information related to U.S. citizenship, for example, when describing who is eligible to vote in federal elections.
74 |
75 | - Be careful with _Americans_ or _the American public_. These terms are [ambiguous](https://en.wikipedia.org/wiki/Names_for_United_States_citizens) and are often used as synonyms for _citizens_. In most cases, _the public_ is equally clear and more inclusive. That said, referring to _Americans_ or _the American people_ can be useful if you want to inspire readers or take a more patriotic tone.
76 |
77 | ## Race, ethnicity, and religion
78 |
79 | Avoid using words, images, or situations that reinforce racial, ethnic, or religious stereotypes (even stereotypes that may appear to be positive). Avoid the term _non-white_, or other terms that treat whiteness as a default.
80 |
81 | Don’t make assumptions: ask how people identify themselves, and be aware of complexities within racial, ethnic, and religious identities. For example, not all Arabs are Muslim, and many nationalities and ethnicities include various religious practices and traditions.
82 |
83 | When referring to a person’s race or ethnicity, use adjectives, not nouns (for example, _a Hispanic person_, not _a Hispanic_).
84 |
85 | ### Media style guides for race, ethnicity, and religion
86 |
87 | - [National Association of Black Journalists Style Guide](http://www.nabj.org/?styleguide)
88 | - [Guidance from the Asian American Journalists Association](https://www.aaja.org/news-and-resources/guidances/)
89 | - [Native American Journalists Association Reporter's Indigenous Terminology Guide](https://najanewsroom.com/wp-content/uploads/2018/11/NAJA_Reporting_and_Indigenous_Terminology_Guide.pdf)
90 | - [Religion Newswriters Association's Religion Stylebook](http://religionstylebook.com/)
91 |
--------------------------------------------------------------------------------
/_pages/our-style/index.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Our style
3 | permalink: /our-style/
4 | sidenav: our-style
5 | sticky_sidenav: true
6 | ---
7 |
8 | By giving writers rules, whether they are about how to use punctuation or how to present your brand or agency, a style guide helps your users understand what you are trying to say. By promoting consistency, you avoid making users reinterpret your words over and over.
9 |
10 | Some style guidelines are arbitrary, while others reflect proven best practices. Either way, they help an organization produce consistently effective content. We provide guidelines that reflect best practices as we know them here at 18F. Writing for other audiences might require different rules, but we hope our suggestions can be a good starting point for your organization.
--------------------------------------------------------------------------------
/_pages/our-style/names.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Names
3 | permalink: /our-style/names/
4 | sidenav: our-style
5 | sticky_sidenav: true
6 | subnav:
7 | - text: Personal names
8 | href: '#personal-names'
9 | - text: State names
10 | href: '#state-names'
11 | ---
12 |
13 | ## Personal names
14 |
15 | Use full names on first reference. On second reference, use first names when writing about our teams or our work, and otherwise follow AP style (which is to mostly use last names on second reference).
16 |
17 | If the context means that there’s a chance of confusion on second reference when using only first or last names, use full names.
18 |
19 | ## State names
20 |
21 | - Spell out state names, such as _Mississippi_.
22 | - When referring to a number of states, “state” should be lowercase. For example, _All 50 states responded._
23 | - When used with a city, spell out the name of the state. For example, _Atlanta, Georgia_.
24 |
--------------------------------------------------------------------------------
/_pages/our-style/numbers-and-percentages.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Numbers, percentages, and dates
3 | permalink: /our-style/numbers-and-percentages/
4 | sidenav: our-style
5 | sticky_sidenav: true
6 | subnav:
7 | - text: Numbers
8 | href: '#numbers'
9 | - text: Percentages
10 | href: '#percentages'
11 | - text: Dates
12 | href: '#dates'
13 |
14 | ---
15 |
16 | ## Numbers
17 |
18 | Generally speaking, we follow the guidelines outlined in the [AP Stylebook](https://www.apstylebook.com/). In body copy, we prefer to spell out numbers *one* through *nine*, and use numerals for numbers 10 and greater. This is true of ordinal numbers, as well. Spell out *first* to *ninth*, and capture *10th* or greater with numerals.
19 |
20 | Sometimes the government writes about very large numbers: millions, billions, even trillions. We express these numbers with a numeral and a word. For example, *1.6 million people*. When referring to amounts of money in cents or greater than $1 million, we use numerals followed by words: *5 cents* or *$2.7 million*. For amounts of money less than $1 million, we use the dollar sign: *$17*.
21 |
22 | In titles, subheadings, and interface labels, we use numerals instead of spelling out numbers. For example, *10 digital tech leaders you should know now* or *6 ways to incorporate plain-language strategies*. We do this to promote ease of reading and scannability — in titles and headings, it’s easier for readers to scan numerals than it is for them to scan written-out numbers.
23 |
24 | ### Ranges
25 |
26 | For ranges of numbers, see [Punctuation > Dashes](https://content-guide.18f.gov/our-style/punctuation/#dashes).
27 |
28 | ## Percentages
29 |
30 | In keeping with AP style, we spell out *percent* in most cases, with a few exceptions. We use the percent sign (%) in these circumstances:
31 |
32 | * **Tables and in technical or scientific writing**. For example: *60% of participants reported experiencing negative side effects*.
33 | * **Headings and subheadings**. For example: *Candidate Woof takes 7% lead in the election for best dog*.
34 | * **Interface labels**
35 | * **Captions and infographics**
36 |
37 | We choose to use the percent sign in these cases to improve content’s scannability, allowing readers to digest the content more quickly.
38 |
39 |
40 | ## Dates
41 |
42 | To avoid confusion, we spell out specific dates such as "October 22, 2005," rather than abbreviating the month or using numbers as in "10/22/2005." Use the full, four-digit year. For informal writing, it's okay to use an abbreviated form. For example, *We're thankful web design isn't stuck in the '90s.*
43 |
--------------------------------------------------------------------------------
/_pages/our-style/punctuation.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Punctuation
3 | permalink: /our-style/punctuation/
4 | sidenav: our-style
5 | sticky_sidenav: true
6 | subnav:
7 | - text: Bulleted lists
8 | href: '#bulleted-lists'
9 | - text: Colons
10 | href: '#colons'
11 | - text: Commas
12 | href: '#commas'
13 | - text: Dashes
14 | href: '#dashes'
15 | - text: Quotes
16 | href: '#quotes'
17 | - text: Spaces
18 | href: '#spaces'
19 | - text: Ampersands or plus signs
20 | href: '#ampersands-or-plus-signs'
21 | - text: Slashes
22 | href: '#slashes'
23 | ---
24 |
25 | ## Bulleted lists
26 |
27 | Capitalize the first word of every bullet. Don't use semicolons after points in a bulleted list. Include a period at the end of the bullet only if that point is a complete sentence. For example:
28 |
29 | *When you go to the store, please buy:*
30 |
31 | - *Apples*
32 | - *Bananas*
33 | - *Naan chips*
34 |
35 | *When you leave the house:*
36 |
37 | - *Please buy apples, bananas, and naan chips.*
38 | - *Fill the car with gas.*
39 |
40 | ## Colons
41 |
42 | Capitalize the first word after a colon, only if what follows is a complete sentence. For example:
43 |
44 | > I have several favorite foods: apples, bananas, and naan chips.
45 |
46 | > I have several favorite foods: Apples were my first favorite snack, but naan chips
47 | are a rising star in my life.
48 |
49 | ## Commas
50 |
51 | We use the serial comma (sometimes called the Oxford comma). In a list of three or more, include a comma before the conjunction. For example: *Please buy apples, bananas, and naan chips.*
52 |
53 | ## Dashes
54 |
55 | When offsetting a phrase with dashes you should use the longer em dash (—), which is `Option + Shift + -` on Macs, with a space on either side of the dash. For example:
56 |
57 | > We emphasize open, digital record keeping, and — whenever possible — we illuminate our processes.
58 |
59 | Although we advocate using words rather than symbols, in some contexts you may use an en dash to convey a range of numbers. For example, both *10–20 students* and *10 to 20 students* are acceptable options. En dash is `Option + -` on Macs.
60 |
61 | > We assign 2–3 people to each development team.
62 |
63 | ## Quotes
64 |
65 | These quotations are correctly punctuated:
66 |
67 | > “Would you like a banana?” he asked.
68 |
69 | > “I hate bananas,” she said. “You know I hate bananas.”
70 |
71 | > He paused before saying “bananas are not something people should hate.”
72 |
73 | ## Spaces
74 |
75 | Sentences should always be separated by a single space. Never two spaces.
76 |
77 | ## Ampersands or plus signs
78 |
79 | Use _and_ instead of an ampersand or plus sign, unless they’re part of an official title or company name. For example, *D.C. Tech Lady Hackathon + Training Day*
80 |
81 | ## Slashes
82 |
83 | Avoid using the slash `/` symbol. Replace it with words or commas as appropriate.
84 |
--------------------------------------------------------------------------------
/_pages/our-style/specific-words-and-phrases.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Specific words and phrases
3 | permalink: /our-style/specific-words-and-phrases/
4 | sidenav: our-style
5 | sticky_sidenav: true
6 | ---
7 |
8 | Below are rules for how we use common words and phrases. The bold term shows the accepted form (capitalization, hyphenation, punctuation), with accompanying text explaining usage.
9 |
10 | - **18F employees**, **18F team members**, or **18F staffers**. Avoid all iterations of _18F-r_.
11 | - **ages**, avoid hyphens in ages unless it clarifies the text. For example, _a group of 10 18-year-old White House tourists_.
12 | - **agile**
13 | - **a.m.**
14 | - **back end**, **back-end development**
15 | - **Congress** refers to the U.S. Senate and House of Representatives.
16 | - **congressional** is lowercase unless part of a proper name. For example, _Congressional Record_
17 | - **DC**, not D.C.
18 | - **DevOps**
19 | - **digital coalition**
20 | - **drop-down** when used as an adjective. For example, _drop-down menu._ **drop down** when used as a noun. For example, _an option from the drop down_. Never _dropdown_.
21 | - **email**, not e-mail
22 | - **executive branch**
23 | - **federal**, unless part of a proper noun. For example, _Federal Bureau of Investigation_
24 | - **federal government**, not Federal Government or Federal government
25 | - **fiscal year** is lowercase. It’s okay to abbreviate as _FY_ on the second reference.
26 | - **front end**, **front-end developer**
27 | - **GitHub**
28 | - **government**, unless part of a proper noun. For example, _Government Printing Office_
29 | - **homepage**
30 | - **human-centered design**, often used interchangeably with user-centered design. We prefer user-centered design to describe 18F's principles and work to emphasize our focus on those those who are _using_ a service/product (rather than those making it or humans in general)
31 | - **info** is an acceptable shortening of _information_. In formal situations, use the full word.
32 | - **internet**
33 | - **JavaScript**
34 | - **kanban**
35 | - **login** when used as noun, for example, _I forgot my login name and password_, or when used as an adjective, for example _Make sure the login page is 508 complaint._ **log in** when used as a verb, for example, _Log in to access your calendar._
36 | - **open source**, **open source software**
37 | - **percent** is preferred more than the % symbol. For example, _10 percent of respondents_.
38 | - **p.m.**
39 | - **README**
40 | - **Scrum** should be used to refer to the set of practices for the agile method. We don't use that term for the daily meetings and instead use _daily standup_.
41 | - **single sign-on**
42 | - **sitemap**
43 | - **startup**
44 | - **tech** is an acceptable shortening of _technology_. In formal situations, use the full word.
45 | - **to do** (noun) and **to-do** (adjective). For example, _your to dos_ or _your to-do list_.
46 | - **United States government** or **U.S. government**, not U.S. Government
47 | - URLs should be lowercase, even when they appear at the start of a sentence. For example, _notalone.gov launched today._
48 | - **U.S.**, not US or USA
49 | - **user-centered design**, often used interchangeably with human-centered design. We prefer user-centered design to describe 18F's principles and work to emphasize our focus on those those who are _using_ a service/product (rather than those making it or humans in general)
50 | - **U.S. Web Design System** on first use and **Design System** on subsequent references
51 | - **Wi-Fi**
52 |
--------------------------------------------------------------------------------
/_pages/our-style/style-guides.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Style guides
3 | permalink: /our-style/style-guides/
4 | sidenav: our-style
5 | sticky_sidenav: true
6 | subnav:
7 | - text: Guidelines
8 | href: '#guidelines'
9 | - text: Examples
10 | href: '#examples'
11 | ---
12 |
13 | We often develop project-specific style guides to support our partners and their audiences. We usually call these documents _content guides_, because most of our partners already follow a style guide like [AP](https://www.apstylebook.com/), [GPO](https://www.govinfo.gov/app/details/GPO-STYLEMANUAL-2016), or [Chicago](http://www.chicagomanualofstyle.org/home.html).
14 |
15 | ## Guidelines
16 |
17 | Here are a few things to keep in mind when you’re developing style guides:
18 |
19 | **Respect the partner’s existing style.** Assume that your partner has an agency-level style guide and ask about it.
20 |
21 | - If they don’t have a style guide, start with [AP](https://www.apstylebook.com/) since we’re most familiar with it and many of our partners use it.
22 | - If any of the existing style guidelines inhibit clarity or usability, talk with the partner about it, backing up your recommendations with insights from user research.
23 |
24 | **Keep it brief.** Don’t try to document every possible grammatical or style issue. Keep your guide short and sweet so it’s easy for people to reference. Most of our guides include:
25 |
26 | - High-level notes about voice and tone
27 | - Usage guidelines
28 | - Acronyms and abbreviations
29 | - Capitalization
30 | - Numbers
31 | - Punctuation
32 | - Web styling, such as headers or glossary terms
33 | - Specific words and phrases
34 |
35 | **Focus on what’s new or particularly unique.** If you’re using sentence case or avoiding acronyms, for example, call that out and include inline examples. If you need to use specific terms or technical jargon with users, include suggested phrasing to help other writers follow along.
36 |
37 | **Share and refine it.** Post the guide on a wiki or in a pattern library with other project documentation — don’t bury it in a PDF. Make it easy for people to find and update the guidelines as questions come up.
38 |
39 | ## Examples
40 |
41 | - [cloud.gov](https://github.com/18F/cg-product/blob/master/ContentGuide.md)
42 | - [FBI Crime Data Explorer](https://github.com/18F/crime-data-explorer/wiki/Content-Guide)
43 | - [Natural Resources Revenue Data](https://github.com/ONRR/nrrd/wiki/Content-style-guide)
44 |
--------------------------------------------------------------------------------
/_pages/our-style/technical-and-interface-writing.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Technical and interface writing
3 | permalink: /our-style/technical-and-interface-writing/
4 | sidenav: our-style
5 | sticky_sidenav: true
6 | subnav:
7 | - text: Basics
8 | href: '#basics'
9 | - text: Guidelines
10 | href: '#guidelines'
11 | ---
12 |
13 | At 18F, we often write technical documentation, guides, forms, and interface messages. In most of these cases, it’s safe to say the reader is learning something new or troubleshooting. These guidelines will help you write clear, concise instructions, which will provide your reader with the best possible experience.
14 |
15 | ## Basics
16 |
17 | ### Do the hard work to make it simple
18 |
19 | Help the reader follow along. Break instructions or processes down into individual steps. Use short, simple sentences with words people use in everyday conversation.
20 |
21 | Refer to navigation labels, buttons, and menus as they appear in the app or website. Verify the spelling and capitalization as you write. Be specific.
22 |
23 | Instead of:
24 |
25 | > Open a new meeting invitation.
26 |
27 | Use:
28 |
29 | > In Google Calendar, click **Create**.
30 |
31 | ### Direct the reader
32 |
33 | Start your sentences with active verbs or clear objectives.
34 |
35 | Instead of:
36 |
37 | > Help us understand what kind of help you need by [creating an issue in GitHub](https://github.com/18F/content-guide/issues/new/).
38 |
39 | Use:
40 |
41 | > [Create an issue](https://github.com/18F/content-guide/issues/new/) with details about your request.
42 |
43 | Or:
44 |
45 | > To get started, [create an issue](https://github.com/18F/content-guide/issues/new/) in GitHub with details about your request.
46 |
47 | Focus on what the reader can do rather than what they can’t. (This is known as using positive language.)
48 |
49 | Instead of:
50 |
51 | > You cannot continue without signing in.
52 |
53 | Use:
54 |
55 | > Sign in to continue.
56 |
57 | ## Guidelines
58 |
59 | ### Titles and headings
60 |
61 | Be consistent with how you phrase titles. If your guide or tutorial has several pages, stick to the same naming convention for scannability, such as:
62 |
63 | * Nouns: _Policies_, _Teams_, _Offices_
64 | * Verbs: _Create an account_, _File a report_, _Download our data_
65 |
66 | [Use sentence case]({{ "/our-style/capitalization#headings" | relative_url }}) for headings. (If you’re writing articles for the 18F Handbook or 18F Pages, the table of contents will auto-generate based on your ``, ``, and `` tags or Markdown headings.)
67 |
68 | ### Introduction
69 |
70 | Include a short two- or three-sentence summary about the document to help the reader confirm whether they’re in the right place, and improve search engine indexing.
71 |
72 | ### Code
73 |
74 | Use [backticks](https://help.github.com/articles/basic-writing-and-formatting-syntax/#quoting-code) to style text and code snippets readers may want to copy and paste. For example:
75 |
76 | > Use the `legend` element to offer a label within each form element.
77 |
78 | > Copy and paste `mkdir /home/foo/doc/bar && cd $_` into Terminal.
79 |
80 | In the first example, `legend` is an HTML element and should be styled as code. “Element” is a technical concept and shouldn't be marked up as code. “Label” is both a concept and an HTML element but is used here in the former sense and should not be styled as code.
81 |
82 | Do not capitalize code elements, even at the start of a sentence, unless the term is capitalized in the code itself.
83 |
84 | Use [fenced code blocks](https://help.github.com/articles/creating-and-highlighting-code-blocks/) for multi-line code snippets, and specify the language to enable [syntax highlighting on GitHub](https://help.github.com/articles/creating-and-highlighting-code-blocks/#syntax-highlighting):
85 |
86 | > In JavaScript, to get the current value of a `select` element with an `id` of `mySelect`, use this:
87 | >
88 | > ```javascript
89 | > var el = document.getElementById("mySelect");
90 | > var value = el.options[el.selectedIndex].value;
91 | > ```
92 |
93 | Use [straight quotes](http://smartquotesforsmartpeople.com/) within code blocks rather than curly (or smart) quotes.
94 |
95 | #### Code-like elements
96 |
97 | The same rules apply to pieces of text that must be used exactly as presented, such as passwords or Wi-Fi network names:
98 |
99 | > `someCl3v3rN4me` is the name of our Wi-Fi network.
100 | > Your password is `PleaseChangeMeSoon`.
101 |
102 | ### Interface elements
103 |
104 | Use clear verbs to tell readers how to interact with interface elements:
105 |
106 | * _Choose_ from drop-down menus.
107 | * _Select_ or _deselect_ checkboxes and radio buttons.
108 | * _Click_ or _tap_ buttons.
109 | * _Follow_ or _open_ links.
110 |
111 | In the 18F Handbook, we emphasize the name of the interface label like so:
112 |
113 | > 1. In the **File** menu, choose **Save**.
114 | > 2. Select **I agree**.
115 | > 3. Click **Continue**.
116 |
117 | ### Tables
118 |
119 | Tables are generally suitable only for data: two or more “objects” (rows) that share two or more “values” (columns). In tables, column widths are the same for all rows, which can make them easier to scan visually. Tables are [easily navigable for sightless users](http://webaim.org/techniques/tables/) so long as the content is organized in a logical way. Here are some other guidelines to consider:
120 |
121 | * When listing numbers, it’s good practice to align them to the right of their cell, with the same decimal precision (“40.50” and “1.00”) so that the numbers are easier to compare while scanning.
122 | * Always align column headings up with the values in the columns. For example, numeric column headings should be aligned right if the values are, too.
123 |
124 | ### Links and additional resources
125 |
126 | It’s rare that a document lives on its own. Tell people where to go for help if they have questions.
127 |
128 | For documentation and guides, you might say:
129 |
130 | > For more information, see the [18F Code of Conduct](https://github.com/18F/code-of-conduct).
131 |
132 | To refer the reader to a Slack channel, follow this format from the 18F Handbook:
133 |
134 | > Still have questions? Ask in [#newcomers](https://18f.slack.com/archives/newcomers).
135 |
136 | If your work relates to several other documents, pick the most important ones or gather the links in a section at the bottom.
137 |
--------------------------------------------------------------------------------
/_pages/our-style/trademarks-and-brands.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Trademarks and brands
3 | permalink: /our-style/trademarks-and-brands/
4 | sidenav: our-style
5 | sticky_sidenav: true
6 | subnav:
7 | - text: Common trademarked words
8 | href: '#common-trademarked-words-with-alternative-terms'
9 | - text: Guidelines
10 | href: '#guidelines'
11 | ---
12 | Avoid using a trademark unless you’re referring to a specific product.
13 |
14 | This can be tricky when a trademarked name, like Kleenex, has become synonymous with an entire family of products. Try to use a generic word — like *tissue* — instead of a brand name.
15 |
16 | ## Common trademarked words (with alternative terms)
17 |
18 | - Band-Aid (adhesive bandage, bandage)
19 | - Bubble Wrap (packaging bubbles)
20 | - Chapstick (lip balm)
21 | - Crayola (crayons)
22 | - Dumpster (waste container, trash container)
23 | - Hi-Liter (highlighting marker)
24 | - iPod (MP3 player)
25 | - Kleenex (tissue)
26 | - Plexiglas (plastic glass)
27 | - Post-it note (adhesive note)
28 | - Q-Tips (cotton swabs)
29 | - Scotch tape (transparent tape)
30 | - Styrofoam (plastic foam)
31 | - Taser (stun gun)
32 | - Xerox (photocopy, copy)
33 |
34 | ## Guidelines
35 |
36 | Careful use of trademarked names and brands is important because the government shouldn’t endorse specific brands or products. When writing about corporate brands or products to illustrate a point, mention a range of related companies instead of a single provider. For example:
37 |
38 | > Twitter, Facebook, and YouTube can help you connect with users.
39 |
40 | Avoid linking to products or services, because people can see it as an endorsement. The same rule applies to the brands and products of individuals, such as personal websites or websites where you can buy their book. Do link to useful resources, like slide decks or how-to guides, from private individuals or companies. If you mention a trademark, capitalize and punctuate it in the trademark holder’s preferred style.
41 |
--------------------------------------------------------------------------------
/_pages/our-style/urls-and-filenames.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: URLs and filenames
3 | permalink: /our-style/urls-and-filenames/
4 | sidenav: our-style
5 | sticky_sidenav: true
6 | subnav:
7 | - text: Creating URLs
8 | href: '#creating-urls'
9 | - text: Creating filenames
10 | href: '#creating-filenames'
11 | - text: Presenting URLs and filenames in text
12 | href: '#presenting-urls-and-filenames-in-text'
13 | - text: Link text
14 | href: '#link-text'
15 | - text: Screen reader-only text
16 | href: '#screen-reader-only-text'
17 | - text: Additional resources
18 | href: '#additional-resources'
19 | ---
20 |
21 | ## Creating URLs
22 |
23 | URLs should be short, memorable, easy to type, and well-structured.
24 | Your control over your URL may be limited, but you should do what you can
25 | with the pieces you can control.
26 |
27 | In the vast majority of cases, everything a user can reach on your site
28 | should have a distinct URL that a user can bookmark and use later to
29 | reach that same location.
30 |
31 | When creating URLs, use dashes to separate words, omit articles
32 | (a/an/the), use the stems of verbs (`/make-thing/` rather than
33 | `/making-thing/`), and avoid extraneous terms.
34 |
35 |
36 | ### Domains
37 |
38 | Domains should reflect the user’s needs and not those of the
39 | organization. If your department is several layers deep in terms of
40 | bureaucratic structure, it’s unlikely that this is important to users,
41 | and there is likely minimal cost associated with using a more shallow
42 | domain.
43 |
44 | It’s not necessary to have `www.` at the start of a domain. This is a
45 | holdover from the early internet. Any domain that has a `www` level
46 | should also work if that level is omitted.
47 |
48 | Domains should not be more than three levels deep in most cases:
49 | `18f.gsa.gov` is fine, but `content-guide.guides.18f.gsa.gov` would not
50 | be. It’s rare that more than four levels is justifiable.
51 |
52 | At the same time, it’s not necessary to have a two-level domain for
53 | everything.
54 |
55 | Domain names should be short, using abbreviations unless those are
56 | likely to be meaningless to users.
57 |
58 | If a domain level has more than one word, you should strongly consider
59 | separating the words with dashes to make sure users read them the way
60 | you intend. If 18F had a project called EARS that for some reason needed
61 | a two-level domain, that domain should be `18f-ears.gov` and not
62 | `18fears.gov` (`ears.18f.gov` would probably be the ideal).
63 |
64 | Domains are case-insensitive. They should be written as lowercase.
65 |
66 | ### Paths
67 |
68 | Again, the shorter the better, but long paths are more excusable than
69 | long domains.
70 |
71 | Paths are typically understood as hierarchies that become increasingly
72 | specific: `/our-style/urls-and-filenames/` reflects that
73 | urls-and-filenames is part of our-style. If this were a much larger
74 | guide, it’s possible that it could be divided further, for example
75 | `/our-style/urls-and-filenames/creating-urls/`.
76 |
77 | Each level of a path should make it possible to find the content beneath
78 | it:
79 |
80 | - The content at the root level should reflect that `/our-style/`
81 | is present.
82 | - `/our-style/` should make it easy to find `urls-and-filenames/`.
83 |
84 | Conversely, the user should be able to remove a level from the path and
85 | end up at the parent of the original content.
86 |
87 | Paths should be designed to be sensible for the user, not to reflect
88 | internal technical or bureaucratic structure. For example, filename
89 | extensions like `.php` should be avoided as they reflect the internal
90 | technology used on the server (and will not reflect even that if the
91 | site later changes to a different technology).
92 |
93 | When separating words in a path, use hyphens. Hyphens are commonly
94 | understood by search engines to indicate word breaks (whereas other
95 | separators, like underscores, are not).
96 |
97 | Paths are case-sensitive. They should be lowercase, regardless of what
98 | they contain, as uppercase letters make them more difficult to type (and
99 | to remember).
100 |
101 | ### Examples
102 |
103 | #### Domain names
104 |
105 | - **Starting point**:
106 | `www.longnamecreationservice.departmentoflongnames.bureauofnames.gov`.
107 | - **Slight improvement**:
108 | `longnamecreationservice.departmentoflongnames.bureauofnames.gov`.
109 |
110 | **Rationale**: `www` is unnecessary and omitting it makes the URL easier to type.
111 |
112 | - **Very slight improvement**:
113 | `long-name-creation-service.departmentoflongnames.bureauofnames.gov`.
114 |
115 | **Rationale**: Hyphens make the URL easier to read. The same would
116 | be true for the other levels of the domain, but we're assuming you
117 | don't have control over those in these examples.
118 |
119 | - **Improvement**: `long-name-creation-service.bureauofnames.gov`.
120 |
121 | **Rationale**: The user doesn’t need the URL to reflect that the
122 | service belongs to the Department of Long Names.
123 |
124 | - **Better**: `lncs.bureauofnames.gov`.
125 |
126 | **Rationale**: This is shorter and easier to type. However, it
127 | relies on users thinking of the service by that abbreviation.
128 |
129 | - **Better**: `make-long-names.bureauofnames.gov`.
130 |
131 | **Rationale**: If the users aren’t familiar with that abbreviation,
132 | a shorter description of what the service does is better to have as
133 | the lowest level of the domain.
134 |
135 | #### Paths
136 |
137 | - **Starting point**:
138 | `/services/default/php/forms/departmentoflongnames/longnamecreationservice/index.php?action=create`.
139 | - **Slight improvement**:
140 | `/services/default/php/forms/departmentoflongnames/longnamecreationservice/index.php`.
141 |
142 | **Rationale**: Assuming that creation is the most likely action
143 | users will want to take, make it the default and strip the
144 | requirement for the query string.
145 |
146 | - **Slight improvement**:
147 | `/services/default/php/forms/departmentoflongnames/longnamecreationservice/`.
148 |
149 | **Rationale**: The default page should be delivered automatically,
150 | making the inclusion of `index.php` unnecessary. Also, hide the
151 | technical details (`.php`).
152 |
153 | - **Improvement**: `/departmentoflongnames/longnamecreationservice/`.
154 |
155 | **Rationale**: Users don’t need to know the technical setup of
156 | the site.
157 |
158 | - **Improvement**:
159 | `/department-of-long-names/long-name-creation-service/`.
160 |
161 | **Rationale**: Words should be separated with hyphens.
162 |
163 | - **Better**: `/department-of-long-names/lncs/`.
164 |
165 | **Rationale**: As above, if the users are familiar with the
166 | abbreviation, use it to make the path shorter.
167 |
168 | - **Better**: `/department-of-long-names/make-long-names/`.
169 |
170 | **Rationale**: As above, if they aren’t familiar with the
171 | abbreviation, use a shorter description of what the server does.
172 |
173 | #### Both
174 |
175 | - **Starting point**:
176 | `www.longnamecreationservice.departmentoflongnames.bureauofnames.gov/services/default/php/forms/departmentoflongnames/longnamecreationservice/index.php?action=create`.
177 | - **Improvement**:
178 | `make-long-names.bureauofnames.gov/department-of-long-names/make-long-names/`.
179 |
180 | **Rationale**: This combines the suggestions from the previous
181 | two sections.
182 |
183 | - **Better**: `make-long-names.bureauofnames.gov`.
184 |
185 | **Rationale**: This is reasonable if the Department of Long Names
186 | has only a couple of services that might be popular enough to
187 | warrant their own subdomains, particularly if they don’t necessarily
188 | fit cleanly into other content and stand alone.
189 |
190 | - **Better**: `bureauofnames.gov/department-of-long-names/make-long-names/`.
191 |
192 | **Rationale**: This is reasonable if the Long Name Creation Service is
193 | one of many related services that the Department of Long Names provides.
194 |
195 | ## Maintaining URLs
196 |
197 | Users constantly bookmark and share web pages, making the maintenance of
198 | permanent and long-lasting URLs an important piece of content management.
199 | Broken links obscure the internet landscape.
200 |
201 | URLs should never stop working.
202 |
203 | This is not as technically challenging as it sounds. If the domain — the
204 | high-level domain, not subdomains — is lost, the URLs will be lost, but
205 | otherwise it’s entirely possible to keep them working. Planning for them
206 | to continue working is the first step in any process that involves new
207 | URLs.
208 |
209 | Whenever possible, maintain original URLs.
210 | In all other cases, set up a redirect for outdated URLs and links;
211 | this is almost always a painless task for web managers. There are a variety
212 | of ways to accomplish this, some of them requiring more
213 | technical work than others. It’s most difficult to accomplish when
214 | moving from URLs that include query parameters, as some early website
215 | systems did. Sensibly-constructed URLs are easier to migrate.
216 |
217 | Some examples:
218 |
219 | ### Changing subdomains
220 |
221 | If we changed our name from 18F to 19G, we would change our domain, so
222 | this page would be located at
223 | `https://pages.19g.gov/content-guide/urls-and-filenames/`. We would keep
224 | the `18f.gov` domain running, but all it would do would redirect
225 | everything to `19g.gov`. Users who entered the old URL would be
226 | redirected and might not even notice the URL change.
227 |
228 | If we decide to eliminate the pages subdomain and put this directly on
229 | `18f.gov`, we would do essentially the same thing, keeping this
230 | subdomain and adding a rule to redirect to the same path on `18f.gov`.
231 |
232 | ### Changing paths
233 |
234 | If we produce lots and lots of content in the future, it might become
235 | sensible to change our path to reflect this, and we might want to have a
236 | guides level, so that the new URL for this page would be:
237 | `https://pages.18f.gov/guides/content-guide/urls-and-filenames/`. In
238 | this case, we would add a rule that redirects everything starting with
239 | `/content-guide/` to `/guides/content-guide/`.
240 |
241 | This also means that URLs, and parts of URLs, should not be re-used.
242 | Once we use `/content-guide/` to refer to this guide, we can no longer
243 | decide in future to use `/content-guide/` as the location for something
244 | else, even if we later change the URL for this guide.
245 |
246 | ## Creating filenames
247 |
248 | Use hyphens to separate words, just as with URLs.
249 |
250 | Lowercase is better, because it’s easier to type and to remember.
251 |
252 | Use the right extension — PDFs should have `.pdf` at the end, JPGs
253 | should have `.jpg` at the end, etc.
254 |
255 | Shorter is better, but the content should be descriptive to the user,
256 | and it’s better to have long descriptive filenames than short obscure
257 | ones. `summary-of-pay-gap-findings.pdf` is better than `paygap.pdf` or
258 | `smmrypgpfnds.pdf`.
259 |
260 | If the file content is based on a date or time, include that: the 1998
261 | report for an organization should have `1998` in the filename, a
262 | February issue of a magazine should have the year and the month, and a
263 | PDF of a daily newspaper should have year, month, and date. When
264 | including dates, use the `YYYY-MM-DD` format, i.e. `2015-10-13`.
265 |
266 | Avoid the use of special characters beyond the hyphen and period, unless
267 | absolutely necessary. Do not include spaces (use hyphens in their
268 | place).
269 |
270 | ## Presenting URLs and filenames in text
271 |
272 | Whether beginning with the protocol or not, always lowercase URLs in
273 | text. Paths are case-sensitive, however, so their casing must be
274 | preserved.
275 |
276 | In interactive contexts, particularly web pages, URLs (except when used
277 | as examples, as throughout this document) should always be active links.
278 | When they’re active links, do not include the protocol in the link text.
279 |
280 | In non-interactive contexts, such as print, the protocol can be omitted,
281 | assuming `http://` and `https://` both work and bring the user to the
282 | same place.
283 |
284 | There are occasions where URLs should be delimited; use `<` and `>` for
285 | this. This is not normally necessary in interactive contexts where the
286 | link is clearly defined, but is most often relevant in email, where the
287 | writer may have to guess at what their email program will turn into a
288 | link. This is particularly true when URL contains spaces.
289 |
290 | Filenames are case-sensitive, and their case should be preserved when
291 | they are referred to in text; do not capitalize if beginning a sentence
292 | with a filename that begins with a lowercase letter. Filenames may need
293 | to be delimited in the same way as URLs.
294 |
295 | ### Examples
296 |
297 | Capitalization on a web page:
298 |
299 | > [gsa.gov](https://gsa.gov) is the General Services Administration
300 | > site.
301 |
302 | Capitalization in print:
303 |
304 | > gsa.gov is the General Services Administration site.
305 |
306 | Delimiting an awkward URL in email:
307 |
308 | > When you get the chance, could you redirect <example.com/spaces in
309 | > URLs are bad/> to <example.com/spaces-in-urls-are-bad/>, as
310 | > per our guidelines, and make the latter the definitive URL for the
311 | > page?
312 |
313 | ### URL Structure
314 |
315 | 1. **The protocol.** For example `https://`, `http://`, or `ftp://`.
316 | The `://` is always present.
317 | 2. **The domain.** For example `18f.gsa.gov`. This is “where on the
318 | internet” the URL is referring to. Also called:
319 | - site
320 | - domain name
321 | - server
322 |
323 | 3. **Optional: the port.** A number specifying how to access the
324 | content on this particular domain. Not normally used on
325 | production sites. Follows the domain, separated by a colon, for
326 | example `http://dev.example.com:8080`.
327 | 4. **The path:** what resource on the domain the URL is referring to.
328 | If omitted, defaults to `/`, the “root level” of the domain. Always
329 | starts with a slash, and different levels of resources are separated
330 | by slashes. For example: `/content-guide/` is the path in
331 | `https://pages.18f.gov/content-guide/`.
332 | 5. **Optional: the query string.** Normally contains parameters that
333 | have been submitted to the site, for example with searches.
334 | `?q=18f+content+guide` is the query string in
335 | `https://www.google.com/search?q=18f+content+guide`.
336 | 6. **Optional: the fragment.** Normally this indicates a specific
337 | section of a page, but can also be used for other things by
338 | web applications. `#main` is the fragment in
339 | `https://pages.18f.gov/content-guide/specific-words-and-phrases/#main`.
340 |
341 | The protocol should almost always be `https://` unless you’re forced to
342 | use `http://`. Users entering `http://` as the protocol should be
343 | redirected to `https://`. If at all possible, your URL should not
344 | contain a port. Query strings should also be avoided. Fragments can be
345 | used as a helper for the user, but should not be necessary for the user
346 | to find the relevant content.
347 |
348 | ## Link text
349 |
350 | It’s important to remember that users of screen readers will often [skip from one link to another][link-to-link], skipping the text in between, as a way of skimming for the content they need.
351 |
352 | This ultimately means that link text should be understandable independent of the text surrounding it. Avoid ambiguous link text like *click here*, *here*, or *learn more* whenever possible.
353 |
354 | For example, instead of:
355 |
356 | > [Click here][CoC] for more information about our Code of Conduct.
357 |
358 | Use:
359 |
360 | > For more information, see the [18F Code of Conduct][CoC].
361 |
362 | This has an added benefit of improving search results for sighted users.
363 |
364 | [CoC]: https://github.com/18F/code-of-conduct
365 | [link-to-link]: http://webaim.org/techniques/hypertext/#link_to_link
366 |
367 | ## Screen reader-only text
368 |
369 | In some situations, descriptive links may be overly verbose or redundant for
370 | sighted users. Here’s an example from the [betaFEC site][]:
371 |
372 | [![Screenshot of Federal Election Commission website, with Candidates and committees highlighted under who can register and report, with a prominent button-style link at the bottom that says learn more]({{ "/images/betaFEC.png" | relative_url }})]({{ "/images/betaFEC.png" | relative_url }})
373 |
374 | Here the *Learn more* link is appropriate for sighted users, but it may be confusing to screen reader users. In such situations, it’s possible to add [invisible text just for screen reader users][sr-only]. For example, the U.S. Web Design Standards has a special CSS class called `usa-sr-only` for this purpose. Using this class, the aforementioned *Learn more* link might be written in HTML like so:
375 |
376 | ```html
377 |
378 | Learn more
379 |
380 | about candidate and candidate committees
381 |
382 |
383 | ```
384 |
385 | This would keep the link concise for sighted users, while also providing
386 | important context for screen reader users.
387 |
388 | If you want to use text intended only for screen readers on your project but
389 | are unfamiliar with CSS, ask your project’s front end developer for help. They
390 | can create a CSS class for you if one doesn’t already exist. Alternatively,
391 | reach out to [#g-accessibility][] or [#g-frontend][] in Slack!
392 |
393 | [#g-accessibility]: https://18f.slack.com/archives/g-accessibility
394 | [#g-frontend]: https://18f.slack.com/archives/g-frontend
395 | [sr-only]: http://webaim.org/techniques/css/invisiblecontent/
396 | [betaFEC site]: https://beta.fec.gov/registration-and-reporting/
397 |
398 | ## Additional resources
399 |
400 | * [WebAIM: Links and Hypertext](http://webaim.org/techniques/hypertext/)
401 | * [W3C: Don’t Use “Click Here” as Link Text](https://www.w3.org/QA/Tips/noClickHere)
402 | * [Stop Clicking Here! 7 Superior SEO Alternatives to Generic Links](https://moz.com/blog/click-here-seo)
403 | * [18F Accessibility Guide](https://pages.18f.gov/accessibility/links/)
404 | * [GSA Linking Policy](https://www.gsa.gov/website-information/website-policies#linking)
405 |
--------------------------------------------------------------------------------
/_pages/our-style/voice-and-tone.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Voice and tone
3 | permalink: /our-style/voice-and-tone/
4 | sidenav: our-style
5 | sticky_sidenav: true
6 | subnav:
7 | - text: The difference between voice and tone
8 | href: '#the-difference-between-voice-and-tone'
9 | - text: Our voice
10 | href: '#our-voice'
11 | - text: Establish your own voice
12 | href: '#establishing-your-own-voice'
13 | - text: Further reading
14 | href: '#further-reading'
15 | ---
16 |
17 | If you’re like many folks, you might not be sure of the difference between voice and tone. Maybe you’ve never deliberately crafted a voice and don’t know where to start. Not to fret! In this section, we’ll discuss the differences between voice and tone, how we describe our organizational voice, how to establish your own voice, and how to choose a tone that’s appropriate for whatever you’re writing.
18 |
19 | ## The difference between voice and tone
20 |
21 | It’s a common question and one that writers might ask themselves: What’s the difference between voice and tone?
22 |
23 | Our **voice** is our unique personality. It can be helpful to think of voice as analogous to a person’s voice. Just as you can identify your best friend in a crowd as soon as you hear her distinctive laugh, you can use an author’s or organization’s voice to identify a piece of writing even if you haven’t seen the byline. A well-crafted voice communicates personality and values — it’s a distilled representation of an author or organization.
24 |
25 | **Tone** is more like attitude — the emotional context of a piece. It can be helpful to think of authorial tone as analogous to a person’s tone of voice. Just as a person would use a somber, sympathetic tone of voice to console a friend about the loss of a pet, an author writing a story about a natural disaster would most likely use a somber, serious tone. Conversely, an author writing a blog post about the launch of a new product might use an enthusiastic, upbeat tone.
26 |
27 | ## Our voice
28 |
29 | At 18F, we like to communicate in a friendly, straightforward way. We consider our voice to be:
30 |
31 | * Authoritative
32 | * Conversational
33 | * Friendly
34 | * Instructive
35 | * Welcoming to all audiences
36 |
37 | We believe that government communication can — and should — be fun and easy to read, and our voice represents this.
38 |
39 | Here are a few sentences, taken from this guide, that exemplify our voice:
40 |
41 | > We created this guide for reference on an as-needed basis. It’s here when you’re wondering whether to capitalize the word _federal_, for instance, or when you’re wondering how to create a friendly, informational tone.
42 |
43 | ### Use contractions
44 |
45 | In all of the communication we produce, we want to create a strong connection with our users. We want to get them the information they need in a straightforward way and show that we know what’s important to them. As a government organization, we need to sound somewhat official; we also recognize that official doesn’t need to translate to stuffy, archaic, or aloof.
46 |
47 | For this reason, we use contractions in the writing we create for our site. We also encourage clients to consider using contractions, too, though we recognize this may not be the right choice for all contexts.
48 |
49 | The government is run by people for the benefit of people, and we never want users to forget that 18F is a group of enthusiastic, dedicated, hardworking (and friendly) folks. This desire informs how we craft our voice.
50 |
51 | ## Establishing your own voice
52 |
53 | Whether you realize it or not, you already have a unique voice; the tricky part can be classifying it and pinning it down.
54 |
55 | To describe your voice — which, in turn, will allow you to diagram it, create guidelines around it, and make it reproducible — you’ll need to do some investigation and self reflection. Ask yourself these questions:
56 |
57 | **What are my core values?** Your voice is a reflection of your core values. Before you craft a voice, consider the values your organization represents and how you can translate these into stylistic patterns. If you’re part of a young organization that hasn’t yet codified its values, you might use this opportunity to start that conversation. Crafting a voice before you’ve determined your organization’s values can be dangerous — your voice might not reflect what you eventually decide on. Along the same lines, if your organization is undergoing a large-scale values overhaul, you’ll want to make sure your organizational voice reflects your new values.
58 |
59 | **Who is my audience?** In writing, as elsewhere, your audience is paramount — without them, you’d have no reason to write. Put yourself in their situation and think about the stylistic traits that might appeal to them. Remember, your voice doesn’t need to appeal to everyone (and, in fact, shouldn’t — cure-alls cure nothing, as the old saying goes).
60 |
61 | Use your answers to these questions to craft a description of your voice. Once you’ve come up with your description, look it over and identify any contradictions or holes (never a good thing). While voices should be nuanced, they should also be cohesive.
62 |
63 | ### Choosing a tone
64 |
65 | As we mentioned earlier, your voice is a constant, but your tone is a variable. Consider the following: If you’re having an irredeemably terrible day, you might get peeved at a store associate who chirpily (and repeatedly) asks if they can help you with anything. While the associate maintained a helpful voice, they failed to shift from an energetic to a restrained tone based on your mood. As a result, their message (however valuable or well-intended) is lost on you.
66 |
67 | To avoid going the way of the associate, think about your users’ needs in different situations. Use these needs to determine your tone.
68 |
69 | Let’s consider three examples that target three different reader groups. Obituaries, technical blog posts, and marketing emails targeted at newly engaged couples have vastly different tones. Why? The three types of writing correspond to audiences in three highly different emotional states.
70 |
71 |
72 |
73 | Type of writing
74 | Intended readership
75 | Tone
76 | Example
77 |
78 |
79 | Obituary of a prominent community member
80 | People who knew (or knew of) the deceased
81 | Respectful, reverent, somber
82 | “Professor Pelham was respected by his colleagues and revered by students, many of whom would wake before dawn on registration day to ensure gaining entry to his classes. His wit, gentle humor, and compassion left their mark on everyone he talked to.”
83 |
84 |
85 | Blog post announcing open source documentation guide
86 | Developers and other readers with a strong tech background
87 | Direct, impartial
88 | “The Open Source Style Guide is a comprehensive handbook for writing clear, accessible, and user-friendly documentation so that your open source code repositories are accessible both internally and externally."
89 |
90 |
91 | Marketing email from the boutique bridal department of a well-known clothing company
92 | Newly engaged women (ages 28 through 33)
93 | Enthusiastic, earnest, bubbly
94 | “Say ‘I do!’ to 25% off. Now through July 3rd, take an additional 25% off all bridal wear and accessories. Celebrate your big day in style (and get a jumpstart on your honeymoon fund!).”
95 |
96 |
97 |
98 | If you’re having trouble finding an appropriate tone, try reframing the situation: How would you talk to a friend who’s in the same situation as your target user? Remembering that written communication is a conversation can help you settle on the best tone for your purpose.
99 |
100 | ## Further reading
101 |
102 | * [Intuit’s voice and tone guide](https://contentdesign.intuit.com/voice-tone/)
103 | * [Jeff Goins’s voice activities](https://goinswriter.com/writing-voice/)
104 | * [Wheaton College guide to style, diction, tone, and voice](https://www.wheaton.edu/Academics/Services/Writing-Center/Writing-Resources/Style-Diction-Tone-and-Voice)
105 |
--------------------------------------------------------------------------------
/_pages/redirects/content-types/forms.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Forms
3 | permalink: /forms/
4 | layout: redirect
5 | redirect: /our-style/
6 | ---
7 |
--------------------------------------------------------------------------------
/_pages/redirects/content-types/headings-and-titles.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Headings and titles
3 | permalink: /headings-and-titles/
4 | layout: redirect
5 | redirect: /our-style/
6 | ---
--------------------------------------------------------------------------------
/_pages/redirects/content-types/images.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Images
3 | permalink: /images/
4 | layout: redirect
5 | redirect: /our-style/
6 | ---
--------------------------------------------------------------------------------
/_pages/redirects/introduction/how-to-use-this-guide.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: How to use this guide
3 | permalink: /how-to-use-this-guide/
4 | layout: redirect
5 | redirect: /
6 | ---
--------------------------------------------------------------------------------
/_pages/redirects/our-approach/address-the-user.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Address the user
3 | permalink: /address-the-user/
4 | layout: redirect
5 | redirect: /our-approach/address-the-user/
6 | ---
7 |
--------------------------------------------------------------------------------
/_pages/redirects/our-approach/avoid-duplication.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Avoid duplication
3 | permalink: /avoid-duplication/
4 | layout: redirect
5 | redirect: /our-approach/avoid-duplication/
6 | ---
--------------------------------------------------------------------------------
/_pages/redirects/our-approach/be-concise.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Be concise
3 | permalink: /be-concise/
4 | layout: redirect
5 | redirect: /our-approach/be-concise/
6 | ---
--------------------------------------------------------------------------------
/_pages/redirects/our-approach/content-principles-2.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Content principles
3 | permalink: /our-approach/content-principles/
4 | layout: redirect
5 | redirect: /our-approach/
6 | ---
--------------------------------------------------------------------------------
/_pages/redirects/our-approach/content-principles.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Content principles
3 | permalink: /content-principles/
4 | layout: redirect
5 | redirect: /our-approach/
6 | ---
--------------------------------------------------------------------------------
/_pages/redirects/our-approach/giving-and-receiving-feedback.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Giving and receiving feedback
3 | permalink: /giving-and-receiving-feedback/
4 | layout: redirect
5 | redirect: /our-approach/gather-feedback/
6 | ---
--------------------------------------------------------------------------------
/_pages/redirects/our-approach/keep-refining.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Keep refining
3 | permalink: /keep-refining/
4 | layout: redirect
5 | redirect: /our-approach/keep-refining/
6 | ---
--------------------------------------------------------------------------------
/_pages/redirects/our-approach/make-content-web-friendly.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Make content web-friendly
3 | permalink: /make-content-web-friendly/
4 | layout: redirect
5 | redirect: /our-approach/make-content-web-friendly/
6 | ---
--------------------------------------------------------------------------------
/_pages/redirects/our-approach/plain-language.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Use plain language
3 | permalink: /plain-language/
4 | layout: redirect
5 | redirect: /our-approach/plain-language/
6 | ---
--------------------------------------------------------------------------------
/_pages/redirects/our-approach/structure-the-content.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Structure the content
3 | permalink: /structure-the-content/
4 | layout: redirect
5 | redirect: /our-approach/structure-the-content/
6 | ---
--------------------------------------------------------------------------------
/_pages/redirects/our-style/abbreviations-and-acronyms.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Abbreviations and acronyms
3 | permalink: /abbreviations-and-acronyms/
4 | layout: redirect
5 | redirect: /our-style/abbreviations-and-acronyms/
6 | ---
--------------------------------------------------------------------------------
/_pages/redirects/our-style/active-voice.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Active voice
3 | permalink: /active-voice/
4 | layout: redirect
5 | redirect: /our-style/active-voice/
6 | ---
--------------------------------------------------------------------------------
/_pages/redirects/our-style/capitalization.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Capitalization
3 | permalink: /capitalization/
4 | layout: redirect
5 | redirect: /our-style/capitalization/
6 | ---
--------------------------------------------------------------------------------
/_pages/redirects/our-style/inclusive-language.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Inclusive language
3 | permalink: /inclusive-language/
4 | layout: redirect
5 | redirect: /our-style/inclusive-language/
6 | ---
--------------------------------------------------------------------------------
/_pages/redirects/our-style/names.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Names
3 | permalink: /names/
4 | layout: redirect
5 | redirect: /our-style/names/
6 | ---
--------------------------------------------------------------------------------
/_pages/redirects/our-style/numbers-and-percentages.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Numbers and percentages
3 | permalink: /numbers-and-percentages/
4 | layout: redirect
5 | redirect: /our-style/numbers-and-percentages/
6 | ---
--------------------------------------------------------------------------------
/_pages/redirects/our-style/punctuation.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Punctuation
3 | permalink: /punctuation/
4 | layout: redirect
5 | redirect: /our-style/punctuation/
6 | ---
--------------------------------------------------------------------------------
/_pages/redirects/our-style/specific-words-and-phrases.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Specific words and phrases
3 | permalink: /specific-words-and-phrases/
4 | layout: redirect
5 | redirect: /our-style/specific-words-and-phrases/
6 | ---
--------------------------------------------------------------------------------
/_pages/redirects/our-style/style-guides.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Style guides
3 | permalink: /style-guides/
4 | layout: redirect
5 | redirect: /our-style/style-guides/
6 | ---
--------------------------------------------------------------------------------
/_pages/redirects/our-style/technical-and-interface-writing.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Technical and interface writing
3 | permalink: /technical-and-interface-writing/
4 | layout: redirect
5 | redirect: /our-style/technical-and-interface-writing/
6 | ---
--------------------------------------------------------------------------------
/_pages/redirects/our-style/trademarks-and-brands.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Trademarks and brands
3 | permalink: /trademarks-and-brands/
4 | layout: redirect
5 | redirect: /our-style/trademarks-and-brands/
6 | ---
--------------------------------------------------------------------------------
/_pages/redirects/our-style/urls-and-filenames.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: URLs and filenames
3 | permalink: /urls-and-filenames/
4 | layout: redirect
5 | redirect: /our-style/urls-and-filenames/
6 | ---
--------------------------------------------------------------------------------
/_pages/redirects/our-style/voice-and-tone.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Voice and tone
3 | permalink: /voice-and-tone/
4 | layout: redirect
5 | redirect: /our-style/voice-and-tone/
6 | ---
--------------------------------------------------------------------------------
/_pages/resources.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Resources
3 | permalink: /resources/
4 | sidenav: overview
5 | sticky_sidenav: true
6 | subnav:
7 | - text: Style guides
8 | href: "#style-guides"
9 | - text: Related links
10 | href: "#related-links"
11 | ---
12 |
13 | We adapted this guide from [GOV.UK’s work](https://www.gov.uk/guidance/content-design), and we’d like to thank their content team for championing plain language and information accessibility.
14 |
15 | ## Style guides
16 |
17 | We generally follow [AP style](https://www.apstylebook.com/) unless otherwise noted.
18 |
19 | As we created this guide, we also referred to these resources:
20 |
21 | * [The U.S. Government Publishing Office](https://www.gpo.gov/)
22 | * [Conscious Style Guide](http://consciousstyleguide.com/)
23 | * [Plain Language Action and Information Network](http://www.plainlanguage.gov/)
24 | * [USAGov Bilingual Style Guide](https://www.usa.gov/style-guide/table-of-contents)
25 | * [Disability Language Style Guide](http://ncdj.org/style-guide/)
26 | * [Diversity Style Guide](http://www.diversitystyleguide.com/)
27 | * [GLAAD Media Reference Guide](http://www.glaad.org/reference)
28 | * [MailChimp Content Style Guide](http://styleguide.mailchimp.com/)
29 |
30 | ## Related links
31 |
32 | * [18F Accessibility Guide](https://accessibility.18f.gov/)
33 | * [18F Visual Identity Guide](https://brand.18f.gov/)
34 | * [U.S. Web Design System](https://designsystem.digital.gov/)
35 | * [18F Blog: Content Design](https://18f.gsa.gov/tags/content-design/)
36 | * [DigitalGov: Style Guides by Government Agencies](https://www.digitalgov.gov/resources/style-guides-by-government-agencies/)
--------------------------------------------------------------------------------
/_sass/_usa_anchor.scss:
--------------------------------------------------------------------------------
1 | // Anchor component - - - - - - - - - - - - - - -
2 | // Using the USWDS Design Tokens
3 | .anchor{
4 | display: flex;
5 | flex-direction: column;
6 | justify-content: flex-end;
7 | flex: 1;
8 | }
9 |
10 |
11 | .component-anchor{
12 | background-color: $color-dark;
13 | @include u-text('white');
14 |
15 | h3{
16 | @include u-font('sans', 'md');
17 | }
18 |
19 | .org-short{
20 | @include u-padding-y(3);
21 | @include u-display('block');
22 | @include at-media('tablet') {
23 | @include u-display('flex');
24 | @include u-flex('align-center');
25 | @include u-flex('justify');
26 | }
27 | .org-copy{
28 | @include u-display('flex');
29 | @include u-flex('align-start');
30 | @include at-media('tablet'){
31 | @include u-flex('align-center');
32 | }
33 | p{
34 | @include u-margin(0);
35 | @include at-media('tablet'){
36 | @include u-measure(5);
37 | }
38 | }
39 | .org-img{
40 | @include u-margin-right(2);
41 | @include u-maxw(7);
42 | @include u-minw(7);
43 | @include at-media('tablet') {
44 | @include u-maxw(6);
45 | @include u-minw(6);
46 | }
47 | }
48 | }
49 | }
50 |
51 | .org-copy{
52 | @include u-font('sans', 'xs');
53 | @include u-line-height('sans', 3);
54 | @include u-text('white');
55 | @include at-media('tablet') {
56 | @include u-font('sans', 'sm');
57 | }
58 | p{
59 | a{
60 | @include u-text('white');
61 | }
62 | .more{
63 | @include u-text('underline');
64 | }
65 | }
66 |
67 | }
68 |
69 | .org-expanded{
70 | .org-copy{
71 | @include u-margin-bottom(2);
72 | }
73 | .org-links{
74 | @include u-margin-bottom(2);
75 | @include u-padding-x(2);
76 | @include u-padding-right(1);
77 | @include u-padding-top('105');
78 | @include u-padding-bottom(2);
79 | @include u-bg('primary-dark');
80 | @include u-font('sans', '2xs');
81 | @include u-text('base-lightest');
82 | ul{
83 | @include u-padding-left('205');
84 | li{
85 | @include u-margin-bottom('05');
86 | a{
87 | @include u-text('no-underline');
88 | @include u-border-bottom('1px', 'solid', 'white');
89 | &:hover{
90 | @include u-text('white');
91 | @include u-border-bottom('2px', 'solid', 'white');
92 | }
93 | }
94 | }
95 | }
96 | a{
97 | @include u-text('base-lightest');
98 | &:hover{
99 | @include u-text('white');
100 | @include u-border-bottom('2px', 'solid', 'white');
101 | }
102 | }
103 | }
104 | }
105 |
106 | button.btn-learn-more{
107 | @include u-text('white');
108 | @include u-border('1px', 'solid', 'white');
109 | @include u-radius('md');
110 | background: none;
111 | box-shadow: none;
112 | @include u-width('auto');
113 |
114 | @include u-margin(0);
115 | @include u-margin-top(1);
116 | @include u-padding-y('05');
117 | @include u-padding-left('105');
118 | @include u-padding-right(4);
119 | @include u-font('sans', '2xs');
120 | @include at-media('tablet') {
121 | @include u-margin-top(0);
122 | @include u-margin-left(2);
123 | @include u-padding-y(1);
124 | @include u-float('right');
125 | @include u-font('sans', 'xs');
126 | }
127 | @include at-media('desktop') {
128 | @include u-font('sans', 'sm');
129 | }
130 | &:hover{
131 | box-shadow: none;
132 | }
133 | }
134 | .usa-accordion__button[aria-expanded=false]{
135 | background-image: url('../../images/angle-arrow-down-white.svg'),-webkit-gradient(linear,left top,left bottom,from(transparent),to(transparent));
136 | background-size: .85rem;
137 | background-repeat: no-repeat;
138 | background-position: 6.65em center;
139 | }
140 | .usa-accordion__button[aria-expanded=true]{
141 | background-image: url('../../images/angle-arrow-up-white.svg'),-webkit-gradient(linear,left top,left bottom,from(transparent),to(transparent));
142 | background-size: .85rem;
143 | background-repeat: no-repeat;
144 | background-position: 6.65em center;
145 | }
146 | }
147 |
148 | .component-anchor-support{
149 | @include u-bg('black');
150 | @include u-text('white');
151 | .usagov{
152 | @include u-padding-y(1);
153 | @include u-display('block');
154 | @include at-media('tablet') {
155 | @include u-display('flex');
156 | @include u-font('sans', 'sm');
157 | @include u-flex('align-center');
158 | @include u-flex('justify-start');
159 | }
160 | p{
161 | @include u-margin-y('05');
162 | @include u-flex('align-center');
163 | @include u-line-height('sans', 2);
164 | @include u-font('sans', 'xs');
165 | @include at-media('tablet') {
166 | @include u-font('sans', 'sm');
167 | }
168 | i{
169 | @include u-margin-right('105');
170 | font-size:1.25rem;
171 | @include u-maxw(3);
172 | @include u-minw(3);
173 | @include at-media('tablet') {
174 | @include u-maxw(3);
175 | @include u-minw(3);
176 | }
177 | }
178 | }
179 | .usagov__link{
180 | @include u-margin(0);
181 | @include u-margin-top(1);
182 | @include u-margin-bottom(2);
183 | @include u-padding-y(1);
184 | @include u-text('white');
185 | white-space: nowrap;
186 | @include u-font('sans', 'sm');
187 | @include at-media('tablet') {
188 | @include u-margin(0);
189 | @include u-margin-left('105');
190 | @include u-font('sans', 'xs');
191 | }
192 | @include at-media('tablet-lg') {
193 | @include u-font('sans', 'sm');
194 | }
195 | }
196 | }
197 | }
198 |
199 |
200 | .usa-button-sm{
201 | @include u-margin-x('05');
202 | @include u-padding-y('05');
203 | @include u-padding-x('105');
204 | }
205 | .arrow-down{
206 | @include u-margin-left('105');
207 | @include u-width('105');
208 | }
209 |
--------------------------------------------------------------------------------
/_sass/_uswds-theme-custom-styles.scss:
--------------------------------------------------------------------------------
1 |
2 | //// 18F styles
3 |
4 | // Color
5 | $color-light: color("cyan-10v"); // was #b3efff
6 | $color-bright: color("cyan-30v"); // was #00cfff
7 | $color-medium: color("primary");
8 | $color-dark: color("primary-dark"); // was #1C304A
9 | $color-base: color("primary-dark"); // was #1F2E4A
10 | $color-black: color("black");
11 | $color-inverse: color("white");
12 |
13 | $color-bright-hover: color("accent-cool-dark");
14 | $color-medium-hover: color("blue-60");
15 |
16 | $color-gray-lightest: color("base-lightest"); // Adding bc used in our $border-light in this file.
17 | $color-gray-hover: color("gray-2");
18 | $color-gray-divider: color("gray-20");
19 |
20 | $color-gray-border: color("base-dark");
21 |
22 | $logo-size-lg: 3rem;
23 | $logo-size-md: 2rem;
24 |
25 | // Typography
26 | .usa-prose{
27 | h1,h2,h3,h4,h5,h6 {
28 | color: $color-dark;
29 | }
30 |
31 | p, li {
32 | color: $color-base;
33 | }
34 | }
35 | .usa-list li,
36 | .usa-prose>ul li,
37 | .usa-prose>ol li {
38 | margin-bottom: units(0.5);
39 | }
40 | .usa-prose>ul li>ul,
41 | .usa-prose>ul li>ol,
42 | .usa-prose>ol li>ul,
43 | .usa-prose>ol li>ol {
44 | margin-top: units(1.5);
45 | }
46 |
47 | // Links
48 | a {
49 | color: $color-medium;
50 | }
51 |
52 | a:hover {
53 | color: $color-medium-hover;
54 | }
55 |
56 | // Header
57 | .usa-nav .usa-current::after,
58 | .usa-header--extended .usa-current:hover::after,
59 | .usa-nav__primary>.usa-nav__primary-item > .usa-current:hover::after {
60 | background-color: $color-bright;
61 | height: units(0.5);
62 | }
63 |
64 | .usa-nav__primary>.usa-nav__primary-item > .usa-current,
65 | .usa-nav__primary>.usa-nav__primary-item > a:hover {
66 | color: $color-black;
67 | }
68 |
69 | .usa-nav__primary>.usa-nav__primary-item > a:hover {
70 | background-color: $color-gray-lightest;
71 | }
72 |
73 | .usa-nav__primary>.usa-nav__primary-item > a:hover::after {
74 | height: 0;
75 | }
76 |
77 | .usa-nav__secondary-links {
78 | display: none;
79 | }
80 |
81 | .usa-header.usa-header--extended .usa-logo-img {
82 | height: $logo-size-md;
83 | }
84 |
85 | .usa-logo__text {
86 | line-height: $logo-size-md;
87 | }
88 |
89 |
90 | @include at-media('desktop') {
91 | .usa-header.usa-header--extended .usa-logo-img {
92 | height: $logo-size-lg;
93 | }
94 |
95 | .usa-logo__text {
96 | line-height: $logo-size-lg;
97 | }
98 | }
99 |
100 | // usa-sidenav
101 |
102 | .usa-sidenav a {
103 | color: $color-base;
104 | }
105 |
106 | .usa-sidenav > .usa-sidenav__item {
107 | padding-left: 0;
108 | }
109 |
110 | .usa-sidenav .usa-current {
111 | color: $color-dark;
112 | }
113 |
114 | .usa-sidenav .usa-current::after {
115 | background-color: $color-bright;
116 | border-radius: 0;
117 | width: units(1);
118 | top: 0;
119 | bottom: 0;
120 | }
121 |
122 | .usa-sidenav a:hover {
123 | color: inherit;
124 | background-color: $color-gray-lightest;
125 | }
126 |
127 | //// Customization
128 |
129 | // Set max-width on container to contain lines
130 | .usa-layout-docs__main {
131 | max-width: units("tablet");
132 | }
133 |
134 | // Set line-height to specify distance between lines of text
135 | .usa-prose > h1,
136 | .usa-prose > h2,
137 | .usa-prose > h3,
138 | .usa-prose > h4,
139 | .usa-prose > h5,
140 | .usa-prose > h6 {
141 | @include u-line-height("heading", 3);
142 | }
143 |
144 | // Set property values for code block
145 | pre {
146 | white-space: pre-wrap;
147 | }
148 |
149 | // Breaks urls at container width
150 | code {
151 | overflow-wrap: break-word;
152 | word-wrap: break-word;
153 | }
154 |
155 | // Show Slack icon before Slack Links
156 | a[href^="https://gsa-tts.slack.com"]::before {
157 | content: "";
158 | $size: units(4);
159 | width: $size;
160 | height: $size;
161 | display: inline-block;
162 | vertical-align: middle;
163 | margin: units(-2px) units(-0.5) 0;
164 | background-size: 100%;
165 | background-repeat: no-repeat;
166 | background-image: url("../../images/Slack_Mark.svg");
167 | }
168 | .usa-prose>ul.list-item--margin-bottom-extra>li,
169 | .usa-prose>ol.list-item--margin-bottom-extra>li {
170 | @include u-margin-bottom(1.5);
171 | }
172 |
173 | @include at-media("desktop") {
174 | .usa-header--extended .usa-logo {
175 | max-width: none;
176 | }
177 |
178 | .usa-nav__primary>.usa-nav__primary-item {
179 | @include u-font("ui", "xs");
180 | }
181 |
182 | .usa-header--extended .usa-nav__primary-item>.usa-current::after {
183 | background-color: $color-bright;
184 | }
185 |
186 | .usa-header--extended .usa-nav__primary-item>.usa-nav__link:not(.usa-current):hover::after {
187 | display: none;
188 | }
189 | }
190 |
191 | .usa-layout-docs__sidenav {
192 | overflow: visible;
193 | order: 0;
194 | margin-bottom: units(3);
195 | padding-top: 0;
196 | position: relative;
197 | }
198 |
199 | .usa-header .usa-logo a {
200 | display: inline-block;
201 | }
202 |
203 | @include at-media("desktop") {
204 | .usa-layout-docs__sidenav {
205 | @include grid-col(3);
206 | position: sticky;
207 | }
208 |
209 | .usa-layout-docs__main {
210 | @include u-flex("fill");
211 | }
212 | }
213 |
214 |
215 | //// Footer (usa-anchor styles)
216 |
217 | // Fixing footer anchor to bottom
218 | @include at-media("desktop") {
219 | body {
220 | display: flex;
221 | flex-direction: column;
222 | min-height: 100vh;
223 | }
224 | }
225 |
226 | @import '_usa_anchor';
--------------------------------------------------------------------------------
/_sass/_uswds-theme-settings.scss:
--------------------------------------------------------------------------------
1 | // Just put any changed settings in here!
2 |
3 | $theme-show-notifications: false;
4 | $theme-font-type-sans: "helvetica";
5 | $theme-font-role-heading: "sans";
6 |
7 | $theme-color-primary-dark: "blue-80v";
8 | $theme-color-primary-darker: "blue-90";
9 | $theme-type-scale-sm: 6;
10 | $theme-type-scale-md: 7;
11 |
--------------------------------------------------------------------------------
/docker-compose.yml:
--------------------------------------------------------------------------------
1 | version: "3"
2 | services:
3 | web:
4 | build: .
5 | ports:
6 | - "4000:4000"
7 | volumes:
8 | - .:/usr/src/app
9 |
--------------------------------------------------------------------------------
/favicon-16x16.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/18F/content-guide/1b1723d3d5b8f91d92c16487c88b56265dc0ec3a/favicon-16x16.png
--------------------------------------------------------------------------------
/favicon-32x32.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/18F/content-guide/1b1723d3d5b8f91d92c16487c88b56265dc0ec3a/favicon-32x32.png
--------------------------------------------------------------------------------
/favicon.ico:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/18F/content-guide/1b1723d3d5b8f91d92c16487c88b56265dc0ec3a/favicon.ico
--------------------------------------------------------------------------------
/images/18f-logo-black.svg:
--------------------------------------------------------------------------------
1 |
2 |
3 |
16 |
--------------------------------------------------------------------------------
/images/18f-logo-blue.svg:
--------------------------------------------------------------------------------
1 |
2 |
--------------------------------------------------------------------------------
/images/Slack_Mark.svg:
--------------------------------------------------------------------------------
1 |
2 |
3 |
34 |
--------------------------------------------------------------------------------
/images/angle-arrow-down-white.svg:
--------------------------------------------------------------------------------
1 |
--------------------------------------------------------------------------------
/images/angle-arrow-up-white.svg:
--------------------------------------------------------------------------------
1 |
--------------------------------------------------------------------------------
/images/betaFEC.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/18F/content-guide/1b1723d3d5b8f91d92c16487c88b56265dc0ec3a/images/betaFEC.png
--------------------------------------------------------------------------------
/images/gsa-logo-blue.svg:
--------------------------------------------------------------------------------
1 |
2 |
--------------------------------------------------------------------------------
/images/gsa-logo-w100.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/18F/content-guide/1b1723d3d5b8f91d92c16487c88b56265dc0ec3a/images/gsa-logo-w100.png
--------------------------------------------------------------------------------
/images/iterative-design.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/18F/content-guide/1b1723d3d5b8f91d92c16487c88b56265dc0ec3a/images/iterative-design.png
--------------------------------------------------------------------------------
/index.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: About this guide
3 | permalink: /
4 | sidenav: overview
5 | sticky_sidenav: true
6 | subnav:
7 | - text: If you work at 18F
8 | href: '#if-you-work-at-18f'
9 | - text: If you work at another organization
10 | href: '#if-you-work-at-another-organization'
11 | ---
12 |
13 | At [18F](https://18f.gsa.gov/), we believe that good government content is the same as good content anywhere else: it is easy to understand, and it helps users do what they want to do.
14 |
15 | The question we want to answer with this guide is: how do we get there?
16 |
17 | We hope that by using this guide, you can learn how to make use of the best practices we’ve developed, incorporate user feedback into the editorial process, and build trust with your users.
18 |
19 | ## If you work at 18F
20 |
21 | We created this guide for reference on an as-needed basis. It’s here when you’re wondering whether to capitalize the word federal, for instance, or when you’re wondering how to create a friendly, informational tone.
22 |
23 | To this end, we’ve structured the guide into descriptively named sections. Find the topic you’re looking for in our table of contents, or search by keyword. We aren’t opposed if you’d like to read this guide start to finish, of course.
24 |
25 | ## If you work at another organization
26 |
27 | As a work of the federal 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.
28 |
29 | We encourage you to make a copy of this guide and adapt it to your organizational needs. This guide is just that: a guide. It’s not meant to provide the final opinion on any of the topics discussed. If a certain section isn’t relevant to you and your team, delete it. And if you feel the guide is missing a section, by all means, add it. This guide is yours to use, and we trust you’ll update it in the ways that best suit you.
30 |
--------------------------------------------------------------------------------
/javascripts/application.js:
--------------------------------------------------------------------------------
1 | document.addEventListener('DOMContentLoaded', function() {
2 | PrivateEye({
3 | defaultMessage: "This link is private to GSA.",
4 | ignoreUrls: [
5 | 'gsa-tts.slack.com',
6 | 'anywhere.gsa.gov',
7 | 'bookit.gsa.gov',
8 | 'calendar.gsa.gov',
9 | 'connect.gsa.gov',
10 | 'docs.google.com',
11 | 'drive.google.com',
12 | 'ea.gsa.gov',
13 | 'email.gsa.gov',
14 | 'gcims.gsa.gov',
15 | 'github.com/18F/Accessibility_Reviews',
16 | 'github.com/18F/blog-drafts',
17 | 'github.com/18F/codereviews',
18 | 'github.com/18F/DevOps',
19 | 'github.com/18F/Infrastructure',
20 | 'github.com/18F/security-incidents',
21 | 'github.com/18F/staffing-and-resources',
22 | 'github.com/18F/team-api.18f.gov',
23 | 'github.com/18F/writing-lab',
24 | 'gkey.gsa.gov',
25 | 'gsa-tts.slack.com',
26 | 'gsa.my.salesforce.com',
27 | 'gsaolu.gsa.gov',
28 | 'hrprod.hr.gsa.gov',
29 | 'insite.gsa.gov',
30 | 'mail.gsa.gov',
31 | 'meet.gsa.gov',
32 | 'pages-internal.18f.gov',
33 | 'tock.18f.gov'
34 | ]
35 | });
36 | }, false );
37 |
--------------------------------------------------------------------------------
/javascripts/private-eye.js:
--------------------------------------------------------------------------------
1 | // https://github.com/18F/private-eye
2 | (function() {
3 | 'use strict';
4 |
5 | var STYLES = 'a.private-link::after { content: "\\1F512"; font-size: 0.75em; vertical-align: baseline; padding-left:2px; }';
6 | var STYLES_ID = '_privateEye-styles';
7 |
8 | var DEFAULT_OPTIONS = {
9 | defaultMessage: 'This is a link to a private site, which may or may not be accessible to you.',
10 | wrapper: ''
11 | };
12 |
13 | var isString = function(str) { return !!str && typeof str === 'string'; };
14 | var isArray = function(arr) { return !!arr && arr.length; };
15 |
16 | var optionValidators = {
17 | defaultMessage: isString,
18 | wrapper: isString,
19 | ignoreUrls: isArray,
20 | };
21 |
22 | function setStyles() {
23 | var styles = document.createElement('style');
24 | styles.innerHTML = STYLES;
25 | styles.id = STYLES_ID;
26 | document.body.appendChild(styles);
27 | }
28 |
29 | function getOptions(opts) {
30 | var newObj = {};
31 |
32 | for (var prop in DEFAULT_OPTIONS) {
33 | newObj[prop] = DEFAULT_OPTIONS[prop];
34 | }
35 |
36 | for (var prop in opts) {
37 | var val = opts[prop];
38 |
39 | if (optionValidators[prop](val)) {
40 | newObj[prop] = val;
41 | }
42 | }
43 |
44 | return newObj;
45 | }
46 |
47 | var PrivateEye = function(opts) {
48 | // The old docs recommend calling this as a function. This is here to detect
49 | // those cases and make sure backward compatibility stays intact now that the
50 | // new syntax is preferred.
51 | if (!(this instanceof PrivateEye)) {
52 | return new PrivateEye(opts);
53 | }
54 |
55 | // Don't add the styles to the page more than once.
56 | if (!document.getElementById(STYLES_ID)) {
57 | setStyles();
58 | }
59 |
60 | this.opts = getOptions(opts);
61 |
62 | this.checkLinks();
63 | };
64 |
65 | PrivateEye.prototype.checkLinks = function() {
66 | var self = this;
67 |
68 | this.opts.ignoreUrls.forEach(function(url) {
69 | var hrefValue;
70 | var titleValue;
71 |
72 | // If the `url` is an Object, then parse the properties `message` & `url`
73 | if (url === Object(url)) {
74 | titleValue = url.message;
75 | hrefValue = url.url;
76 | } else {
77 | hrefValue = url;
78 | titleValue = self.opts.defaultMessage;
79 | }
80 |
81 | var wrapper = self.opts.wrapper.length ? self.opts.wrapper + ' ' : '';
82 | var selector = wrapper + 'a';
83 | var anchors = document.querySelectorAll(selector);
84 |
85 | Array.prototype.forEach.call(anchors, function(anchor) {
86 | var anchorHref = anchor.href.toLowerCase().trim();
87 |
88 | if (anchorHref.indexOf(hrefValue.toLowerCase()) !== -1) {
89 | anchor.className += ' private-link';
90 | }
91 | });
92 | });
93 | }
94 |
95 | if (typeof module === 'object' && typeof module.exports === 'object') {
96 | module.exports = PrivateEye;
97 | } else {
98 | window.PrivateEye = PrivateEye;
99 | }
100 | })();
101 |
--------------------------------------------------------------------------------
/site/.gitignore:
--------------------------------------------------------------------------------
1 | _site
2 | .sass-cache
3 | .jekyll-metadata
4 |
--------------------------------------------------------------------------------
- `) or ordered (`
- `) list will benefit all users.
50 |
51 | That said, try to keep your lists as simple as possible. If you have several levels in your list, the complexity might overwhelm the benefits of using a bulleted list. If that’s the case, try using a table instead.
52 |
53 | ## Tables
54 | If you’re wrangling a lot of data, tables can help you visually organize that content. Long paragraphs cluttered with numbers or dates are more difficult to scan than, for example:
55 |
56 |
| Report type | 60 |Dates covered | 61 |Due | 62 |
|---|---|---|
| Quarterly (Form 3, 3Z, 3L) | 67 |January 1–March 31 | 68 |April 15 | 69 |
| April 1–June 30 | 72 |July 15 | 73 ||
| July 1–September 30 | 76 |October 15 | 77 ||
| October 1–December 31 | 80 |January 31 | 81 |
`, ``, and `` tags or Markdown headings.)
67 |
68 | ### Introduction
69 |
70 | Include a short two- or three-sentence summary about the document to help the reader confirm whether they’re in the right place, and improve search engine indexing.
71 |
72 | ### Code
73 |
74 | Use [backticks](https://help.github.com/articles/basic-writing-and-formatting-syntax/#quoting-code) to style text and code snippets readers may want to copy and paste. For example:
75 |
76 | > Use the `legend` element to offer a label within each form element.
77 |
78 | > Copy and paste `mkdir /home/foo/doc/bar && cd $_` into Terminal.
79 |
80 | In the first example, `legend` is an HTML element and should be styled as code. “Element” is a technical concept and shouldn't be marked up as code. “Label” is both a concept and an HTML element but is used here in the former sense and should not be styled as code.
81 |
82 | Do not capitalize code elements, even at the start of a sentence, unless the term is capitalized in the code itself.
83 |
84 | Use [fenced code blocks](https://help.github.com/articles/creating-and-highlighting-code-blocks/) for multi-line code snippets, and specify the language to enable [syntax highlighting on GitHub](https://help.github.com/articles/creating-and-highlighting-code-blocks/#syntax-highlighting):
85 |
86 | > In JavaScript, to get the current value of a `select` element with an `id` of `mySelect`, use this:
87 | >
88 | > ```javascript
89 | > var el = document.getElementById("mySelect");
90 | > var value = el.options[el.selectedIndex].value;
91 | > ```
92 |
93 | Use [straight quotes](http://smartquotesforsmartpeople.com/) within code blocks rather than curly (or smart) quotes.
94 |
95 | #### Code-like elements
96 |
97 | The same rules apply to pieces of text that must be used exactly as presented, such as passwords or Wi-Fi network names:
98 |
99 | > `someCl3v3rN4me` is the name of our Wi-Fi network.
100 | > Your password is `PleaseChangeMeSoon`.
101 |
102 | ### Interface elements
103 |
104 | Use clear verbs to tell readers how to interact with interface elements:
105 |
106 | * _Choose_ from drop-down menus.
107 | * _Select_ or _deselect_ checkboxes and radio buttons.
108 | * _Click_ or _tap_ buttons.
109 | * _Follow_ or _open_ links.
110 |
111 | In the 18F Handbook, we emphasize the name of the interface label like so:
112 |
113 | > 1. In the **File** menu, choose **Save**.
114 | > 2. Select **I agree**.
115 | > 3. Click **Continue**.
116 |
117 | ### Tables
118 |
119 | Tables are generally suitable only for data: two or more “objects” (rows) that share two or more “values” (columns). In tables, column widths are the same for all rows, which can make them easier to scan visually. Tables are [easily navigable for sightless users](http://webaim.org/techniques/tables/) so long as the content is organized in a logical way. Here are some other guidelines to consider:
120 |
121 | * When listing numbers, it’s good practice to align them to the right of their cell, with the same decimal precision (“40.50” and “1.00”) so that the numbers are easier to compare while scanning.
122 | * Always align column headings up with the values in the columns. For example, numeric column headings should be aligned right if the values are, too.
123 |
124 | ### Links and additional resources
125 |
126 | It’s rare that a document lives on its own. Tell people where to go for help if they have questions.
127 |
128 | For documentation and guides, you might say:
129 |
130 | > For more information, see the [18F Code of Conduct](https://github.com/18F/code-of-conduct).
131 |
132 | To refer the reader to a Slack channel, follow this format from the 18F Handbook:
133 |
134 | > Still have questions? Ask in [#newcomers](https://18f.slack.com/archives/newcomers).
135 |
136 | If your work relates to several other documents, pick the most important ones or gather the links in a section at the bottom.
137 |
--------------------------------------------------------------------------------
/_pages/our-style/trademarks-and-brands.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Trademarks and brands
3 | permalink: /our-style/trademarks-and-brands/
4 | sidenav: our-style
5 | sticky_sidenav: true
6 | subnav:
7 | - text: Common trademarked words
8 | href: '#common-trademarked-words-with-alternative-terms'
9 | - text: Guidelines
10 | href: '#guidelines'
11 | ---
12 | Avoid using a trademark unless you’re referring to a specific product.
13 |
14 | This can be tricky when a trademarked name, like Kleenex, has become synonymous with an entire family of products. Try to use a generic word — like *tissue* — instead of a brand name.
15 |
16 | ## Common trademarked words (with alternative terms)
17 |
18 | - Band-Aid (adhesive bandage, bandage)
19 | - Bubble Wrap (packaging bubbles)
20 | - Chapstick (lip balm)
21 | - Crayola (crayons)
22 | - Dumpster (waste container, trash container)
23 | - Hi-Liter (highlighting marker)
24 | - iPod (MP3 player)
25 | - Kleenex (tissue)
26 | - Plexiglas (plastic glass)
27 | - Post-it note (adhesive note)
28 | - Q-Tips (cotton swabs)
29 | - Scotch tape (transparent tape)
30 | - Styrofoam (plastic foam)
31 | - Taser (stun gun)
32 | - Xerox (photocopy, copy)
33 |
34 | ## Guidelines
35 |
36 | Careful use of trademarked names and brands is important because the government shouldn’t endorse specific brands or products. When writing about corporate brands or products to illustrate a point, mention a range of related companies instead of a single provider. For example:
37 |
38 | > Twitter, Facebook, and YouTube can help you connect with users.
39 |
40 | Avoid linking to products or services, because people can see it as an endorsement. The same rule applies to the brands and products of individuals, such as personal websites or websites where you can buy their book. Do link to useful resources, like slide decks or how-to guides, from private individuals or companies. If you mention a trademark, capitalize and punctuate it in the trademark holder’s preferred style.
41 |
--------------------------------------------------------------------------------
/_pages/our-style/urls-and-filenames.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: URLs and filenames
3 | permalink: /our-style/urls-and-filenames/
4 | sidenav: our-style
5 | sticky_sidenav: true
6 | subnav:
7 | - text: Creating URLs
8 | href: '#creating-urls'
9 | - text: Creating filenames
10 | href: '#creating-filenames'
11 | - text: Presenting URLs and filenames in text
12 | href: '#presenting-urls-and-filenames-in-text'
13 | - text: Link text
14 | href: '#link-text'
15 | - text: Screen reader-only text
16 | href: '#screen-reader-only-text'
17 | - text: Additional resources
18 | href: '#additional-resources'
19 | ---
20 |
21 | ## Creating URLs
22 |
23 | URLs should be short, memorable, easy to type, and well-structured.
24 | Your control over your URL may be limited, but you should do what you can
25 | with the pieces you can control.
26 |
27 | In the vast majority of cases, everything a user can reach on your site
28 | should have a distinct URL that a user can bookmark and use later to
29 | reach that same location.
30 |
31 | When creating URLs, use dashes to separate words, omit articles
32 | (a/an/the), use the stems of verbs (`/make-thing/` rather than
33 | `/making-thing/`), and avoid extraneous terms.
34 |
35 |
36 | ### Domains
37 |
38 | Domains should reflect the user’s needs and not those of the
39 | organization. If your department is several layers deep in terms of
40 | bureaucratic structure, it’s unlikely that this is important to users,
41 | and there is likely minimal cost associated with using a more shallow
42 | domain.
43 |
44 | It’s not necessary to have `www.` at the start of a domain. This is a
45 | holdover from the early internet. Any domain that has a `www` level
46 | should also work if that level is omitted.
47 |
48 | Domains should not be more than three levels deep in most cases:
49 | `18f.gsa.gov` is fine, but `content-guide.guides.18f.gsa.gov` would not
50 | be. It’s rare that more than four levels is justifiable.
51 |
52 | At the same time, it’s not necessary to have a two-level domain for
53 | everything.
54 |
55 | Domain names should be short, using abbreviations unless those are
56 | likely to be meaningless to users.
57 |
58 | If a domain level has more than one word, you should strongly consider
59 | separating the words with dashes to make sure users read them the way
60 | you intend. If 18F had a project called EARS that for some reason needed
61 | a two-level domain, that domain should be `18f-ears.gov` and not
62 | `18fears.gov` (`ears.18f.gov` would probably be the ideal).
63 |
64 | Domains are case-insensitive. They should be written as lowercase.
65 |
66 | ### Paths
67 |
68 | Again, the shorter the better, but long paths are more excusable than
69 | long domains.
70 |
71 | Paths are typically understood as hierarchies that become increasingly
72 | specific: `/our-style/urls-and-filenames/` reflects that
73 | urls-and-filenames is part of our-style. If this were a much larger
74 | guide, it’s possible that it could be divided further, for example
75 | `/our-style/urls-and-filenames/creating-urls/`.
76 |
77 | Each level of a path should make it possible to find the content beneath
78 | it:
79 |
80 | - The content at the root level should reflect that `/our-style/`
81 | is present.
82 | - `/our-style/` should make it easy to find `urls-and-filenames/`.
83 |
84 | Conversely, the user should be able to remove a level from the path and
85 | end up at the parent of the original content.
86 |
87 | Paths should be designed to be sensible for the user, not to reflect
88 | internal technical or bureaucratic structure. For example, filename
89 | extensions like `.php` should be avoided as they reflect the internal
90 | technology used on the server (and will not reflect even that if the
91 | site later changes to a different technology).
92 |
93 | When separating words in a path, use hyphens. Hyphens are commonly
94 | understood by search engines to indicate word breaks (whereas other
95 | separators, like underscores, are not).
96 |
97 | Paths are case-sensitive. They should be lowercase, regardless of what
98 | they contain, as uppercase letters make them more difficult to type (and
99 | to remember).
100 |
101 | ### Examples
102 |
103 | #### Domain names
104 |
105 | - **Starting point**:
106 | `www.longnamecreationservice.departmentoflongnames.bureauofnames.gov`.
107 | - **Slight improvement**:
108 | `longnamecreationservice.departmentoflongnames.bureauofnames.gov`.
109 |
110 | **Rationale**: `www` is unnecessary and omitting it makes the URL easier to type.
111 |
112 | - **Very slight improvement**:
113 | `long-name-creation-service.departmentoflongnames.bureauofnames.gov`.
114 |
115 | **Rationale**: Hyphens make the URL easier to read. The same would
116 | be true for the other levels of the domain, but we're assuming you
117 | don't have control over those in these examples.
118 |
119 | - **Improvement**: `long-name-creation-service.bureauofnames.gov`.
120 |
121 | **Rationale**: The user doesn’t need the URL to reflect that the
122 | service belongs to the Department of Long Names.
123 |
124 | - **Better**: `lncs.bureauofnames.gov`.
125 |
126 | **Rationale**: This is shorter and easier to type. However, it
127 | relies on users thinking of the service by that abbreviation.
128 |
129 | - **Better**: `make-long-names.bureauofnames.gov`.
130 |
131 | **Rationale**: If the users aren’t familiar with that abbreviation,
132 | a shorter description of what the service does is better to have as
133 | the lowest level of the domain.
134 |
135 | #### Paths
136 |
137 | - **Starting point**:
138 | `/services/default/php/forms/departmentoflongnames/longnamecreationservice/index.php?action=create`.
139 | - **Slight improvement**:
140 | `/services/default/php/forms/departmentoflongnames/longnamecreationservice/index.php`.
141 |
142 | **Rationale**: Assuming that creation is the most likely action
143 | users will want to take, make it the default and strip the
144 | requirement for the query string.
145 |
146 | - **Slight improvement**:
147 | `/services/default/php/forms/departmentoflongnames/longnamecreationservice/`.
148 |
149 | **Rationale**: The default page should be delivered automatically,
150 | making the inclusion of `index.php` unnecessary. Also, hide the
151 | technical details (`.php`).
152 |
153 | - **Improvement**: `/departmentoflongnames/longnamecreationservice/`.
154 |
155 | **Rationale**: Users don’t need to know the technical setup of
156 | the site.
157 |
158 | - **Improvement**:
159 | `/department-of-long-names/long-name-creation-service/`.
160 |
161 | **Rationale**: Words should be separated with hyphens.
162 |
163 | - **Better**: `/department-of-long-names/lncs/`.
164 |
165 | **Rationale**: As above, if the users are familiar with the
166 | abbreviation, use it to make the path shorter.
167 |
168 | - **Better**: `/department-of-long-names/make-long-names/`.
169 |
170 | **Rationale**: As above, if they aren’t familiar with the
171 | abbreviation, use a shorter description of what the server does.
172 |
173 | #### Both
174 |
175 | - **Starting point**:
176 | `www.longnamecreationservice.departmentoflongnames.bureauofnames.gov/services/default/php/forms/departmentoflongnames/longnamecreationservice/index.php?action=create`.
177 | - **Improvement**:
178 | `make-long-names.bureauofnames.gov/department-of-long-names/make-long-names/`.
179 |
180 | **Rationale**: This combines the suggestions from the previous
181 | two sections.
182 |
183 | - **Better**: `make-long-names.bureauofnames.gov`.
184 |
185 | **Rationale**: This is reasonable if the Department of Long Names
186 | has only a couple of services that might be popular enough to
187 | warrant their own subdomains, particularly if they don’t necessarily
188 | fit cleanly into other content and stand alone.
189 |
190 | - **Better**: `bureauofnames.gov/department-of-long-names/make-long-names/`.
191 |
192 | **Rationale**: This is reasonable if the Long Name Creation Service is
193 | one of many related services that the Department of Long Names provides.
194 |
195 | ## Maintaining URLs
196 |
197 | Users constantly bookmark and share web pages, making the maintenance of
198 | permanent and long-lasting URLs an important piece of content management.
199 | Broken links obscure the internet landscape.
200 |
201 | URLs should never stop working.
202 |
203 | This is not as technically challenging as it sounds. If the domain — the
204 | high-level domain, not subdomains — is lost, the URLs will be lost, but
205 | otherwise it’s entirely possible to keep them working. Planning for them
206 | to continue working is the first step in any process that involves new
207 | URLs.
208 |
209 | Whenever possible, maintain original URLs.
210 | In all other cases, set up a redirect for outdated URLs and links;
211 | this is almost always a painless task for web managers. There are a variety
212 | of ways to accomplish this, some of them requiring more
213 | technical work than others. It’s most difficult to accomplish when
214 | moving from URLs that include query parameters, as some early website
215 | systems did. Sensibly-constructed URLs are easier to migrate.
216 |
217 | Some examples:
218 |
219 | ### Changing subdomains
220 |
221 | If we changed our name from 18F to 19G, we would change our domain, so
222 | this page would be located at
223 | `https://pages.19g.gov/content-guide/urls-and-filenames/`. We would keep
224 | the `18f.gov` domain running, but all it would do would redirect
225 | everything to `19g.gov`. Users who entered the old URL would be
226 | redirected and might not even notice the URL change.
227 |
228 | If we decide to eliminate the pages subdomain and put this directly on
229 | `18f.gov`, we would do essentially the same thing, keeping this
230 | subdomain and adding a rule to redirect to the same path on `18f.gov`.
231 |
232 | ### Changing paths
233 |
234 | If we produce lots and lots of content in the future, it might become
235 | sensible to change our path to reflect this, and we might want to have a
236 | guides level, so that the new URL for this page would be:
237 | `https://pages.18f.gov/guides/content-guide/urls-and-filenames/`. In
238 | this case, we would add a rule that redirects everything starting with
239 | `/content-guide/` to `/guides/content-guide/`.
240 |
241 | This also means that URLs, and parts of URLs, should not be re-used.
242 | Once we use `/content-guide/` to refer to this guide, we can no longer
243 | decide in future to use `/content-guide/` as the location for something
244 | else, even if we later change the URL for this guide.
245 |
246 | ## Creating filenames
247 |
248 | Use hyphens to separate words, just as with URLs.
249 |
250 | Lowercase is better, because it’s easier to type and to remember.
251 |
252 | Use the right extension — PDFs should have `.pdf` at the end, JPGs
253 | should have `.jpg` at the end, etc.
254 |
255 | Shorter is better, but the content should be descriptive to the user,
256 | and it’s better to have long descriptive filenames than short obscure
257 | ones. `summary-of-pay-gap-findings.pdf` is better than `paygap.pdf` or
258 | `smmrypgpfnds.pdf`.
259 |
260 | If the file content is based on a date or time, include that: the 1998
261 | report for an organization should have `1998` in the filename, a
262 | February issue of a magazine should have the year and the month, and a
263 | PDF of a daily newspaper should have year, month, and date. When
264 | including dates, use the `YYYY-MM-DD` format, i.e. `2015-10-13`.
265 |
266 | Avoid the use of special characters beyond the hyphen and period, unless
267 | absolutely necessary. Do not include spaces (use hyphens in their
268 | place).
269 |
270 | ## Presenting URLs and filenames in text
271 |
272 | Whether beginning with the protocol or not, always lowercase URLs in
273 | text. Paths are case-sensitive, however, so their casing must be
274 | preserved.
275 |
276 | In interactive contexts, particularly web pages, URLs (except when used
277 | as examples, as throughout this document) should always be active links.
278 | When they’re active links, do not include the protocol in the link text.
279 |
280 | In non-interactive contexts, such as print, the protocol can be omitted,
281 | assuming `http://` and `https://` both work and bring the user to the
282 | same place.
283 |
284 | There are occasions where URLs should be delimited; use `<` and `>` for
285 | this. This is not normally necessary in interactive contexts where the
286 | link is clearly defined, but is most often relevant in email, where the
287 | writer may have to guess at what their email program will turn into a
288 | link. This is particularly true when URL contains spaces.
289 |
290 | Filenames are case-sensitive, and their case should be preserved when
291 | they are referred to in text; do not capitalize if beginning a sentence
292 | with a filename that begins with a lowercase letter. Filenames may need
293 | to be delimited in the same way as URLs.
294 |
295 | ### Examples
296 |
297 | Capitalization on a web page:
298 |
299 | > [gsa.gov](https://gsa.gov) is the General Services Administration
300 | > site.
301 |
302 | Capitalization in print:
303 |
304 | > gsa.gov is the General Services Administration site.
305 |
306 | Delimiting an awkward URL in email:
307 |
308 | > When you get the chance, could you redirect <example.com/spaces in
309 | > URLs are bad/> to <example.com/spaces-in-urls-are-bad/>, as
310 | > per our guidelines, and make the latter the definitive URL for the
311 | > page?
312 |
313 | ### URL Structure
314 |
315 | 1. **The protocol.** For example `https://`, `http://`, or `ftp://`.
316 | The `://` is always present.
317 | 2. **The domain.** For example `18f.gsa.gov`. This is “where on the
318 | internet” the URL is referring to. Also called:
319 | - site
320 | - domain name
321 | - server
322 |
323 | 3. **Optional: the port.** A number specifying how to access the
324 | content on this particular domain. Not normally used on
325 | production sites. Follows the domain, separated by a colon, for
326 | example `http://dev.example.com:8080`.
327 | 4. **The path:** what resource on the domain the URL is referring to.
328 | If omitted, defaults to `/`, the “root level” of the domain. Always
329 | starts with a slash, and different levels of resources are separated
330 | by slashes. For example: `/content-guide/` is the path in
331 | `https://pages.18f.gov/content-guide/`.
332 | 5. **Optional: the query string.** Normally contains parameters that
333 | have been submitted to the site, for example with searches.
334 | `?q=18f+content+guide` is the query string in
335 | `https://www.google.com/search?q=18f+content+guide`.
336 | 6. **Optional: the fragment.** Normally this indicates a specific
337 | section of a page, but can also be used for other things by
338 | web applications. `#main` is the fragment in
339 | `https://pages.18f.gov/content-guide/specific-words-and-phrases/#main`.
340 |
341 | The protocol should almost always be `https://` unless you’re forced to
342 | use `http://`. Users entering `http://` as the protocol should be
343 | redirected to `https://`. If at all possible, your URL should not
344 | contain a port. Query strings should also be avoided. Fragments can be
345 | used as a helper for the user, but should not be necessary for the user
346 | to find the relevant content.
347 |
348 | ## Link text
349 |
350 | It’s important to remember that users of screen readers will often [skip from one link to another][link-to-link], skipping the text in between, as a way of skimming for the content they need.
351 |
352 | This ultimately means that link text should be understandable independent of the text surrounding it. Avoid ambiguous link text like *click here*, *here*, or *learn more* whenever possible.
353 |
354 | For example, instead of:
355 |
356 | > [Click here][CoC] for more information about our Code of Conduct.
357 |
358 | Use:
359 |
360 | > For more information, see the [18F Code of Conduct][CoC].
361 |
362 | This has an added benefit of improving search results for sighted users.
363 |
364 | [CoC]: https://github.com/18F/code-of-conduct
365 | [link-to-link]: http://webaim.org/techniques/hypertext/#link_to_link
366 |
367 | ## Screen reader-only text
368 |
369 | In some situations, descriptive links may be overly verbose or redundant for
370 | sighted users. Here’s an example from the [betaFEC site][]:
371 |
372 | [![Screenshot of Federal Election Commission website, with Candidates and committees highlighted under who can register and report, with a prominent button-style link at the bottom that says learn more]({{ "/images/betaFEC.png" | relative_url }})]({{ "/images/betaFEC.png" | relative_url }})
373 |
374 | Here the *Learn more* link is appropriate for sighted users, but it may be confusing to screen reader users. In such situations, it’s possible to add [invisible text just for screen reader users][sr-only]. For example, the U.S. Web Design Standards has a special CSS class called `usa-sr-only` for this purpose. Using this class, the aforementioned *Learn more* link might be written in HTML like so:
375 |
376 | ```html
377 |
378 | Learn more
379 |
380 | about candidate and candidate committees
381 |
382 |
383 | ```
384 |
385 | This would keep the link concise for sighted users, while also providing
386 | important context for screen reader users.
387 |
388 | If you want to use text intended only for screen readers on your project but
389 | are unfamiliar with CSS, ask your project’s front end developer for help. They
390 | can create a CSS class for you if one doesn’t already exist. Alternatively,
391 | reach out to [#g-accessibility][] or [#g-frontend][] in Slack!
392 |
393 | [#g-accessibility]: https://18f.slack.com/archives/g-accessibility
394 | [#g-frontend]: https://18f.slack.com/archives/g-frontend
395 | [sr-only]: http://webaim.org/techniques/css/invisiblecontent/
396 | [betaFEC site]: https://beta.fec.gov/registration-and-reporting/
397 |
398 | ## Additional resources
399 |
400 | * [WebAIM: Links and Hypertext](http://webaim.org/techniques/hypertext/)
401 | * [W3C: Don’t Use “Click Here” as Link Text](https://www.w3.org/QA/Tips/noClickHere)
402 | * [Stop Clicking Here! 7 Superior SEO Alternatives to Generic Links](https://moz.com/blog/click-here-seo)
403 | * [18F Accessibility Guide](https://pages.18f.gov/accessibility/links/)
404 | * [GSA Linking Policy](https://www.gsa.gov/website-information/website-policies#linking)
405 |
--------------------------------------------------------------------------------
/_pages/our-style/voice-and-tone.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Voice and tone
3 | permalink: /our-style/voice-and-tone/
4 | sidenav: our-style
5 | sticky_sidenav: true
6 | subnav:
7 | - text: The difference between voice and tone
8 | href: '#the-difference-between-voice-and-tone'
9 | - text: Our voice
10 | href: '#our-voice'
11 | - text: Establish your own voice
12 | href: '#establishing-your-own-voice'
13 | - text: Further reading
14 | href: '#further-reading'
15 | ---
16 |
17 | If you’re like many folks, you might not be sure of the difference between voice and tone. Maybe you’ve never deliberately crafted a voice and don’t know where to start. Not to fret! In this section, we’ll discuss the differences between voice and tone, how we describe our organizational voice, how to establish your own voice, and how to choose a tone that’s appropriate for whatever you’re writing.
18 |
19 | ## The difference between voice and tone
20 |
21 | It’s a common question and one that writers might ask themselves: What’s the difference between voice and tone?
22 |
23 | Our **voice** is our unique personality. It can be helpful to think of voice as analogous to a person’s voice. Just as you can identify your best friend in a crowd as soon as you hear her distinctive laugh, you can use an author’s or organization’s voice to identify a piece of writing even if you haven’t seen the byline. A well-crafted voice communicates personality and values — it’s a distilled representation of an author or organization.
24 |
25 | **Tone** is more like attitude — the emotional context of a piece. It can be helpful to think of authorial tone as analogous to a person’s tone of voice. Just as a person would use a somber, sympathetic tone of voice to console a friend about the loss of a pet, an author writing a story about a natural disaster would most likely use a somber, serious tone. Conversely, an author writing a blog post about the launch of a new product might use an enthusiastic, upbeat tone.
26 |
27 | ## Our voice
28 |
29 | At 18F, we like to communicate in a friendly, straightforward way. We consider our voice to be:
30 |
31 | * Authoritative
32 | * Conversational
33 | * Friendly
34 | * Instructive
35 | * Welcoming to all audiences
36 |
37 | We believe that government communication can — and should — be fun and easy to read, and our voice represents this.
38 |
39 | Here are a few sentences, taken from this guide, that exemplify our voice:
40 |
41 | > We created this guide for reference on an as-needed basis. It’s here when you’re wondering whether to capitalize the word _federal_, for instance, or when you’re wondering how to create a friendly, informational tone.
42 |
43 | ### Use contractions
44 |
45 | In all of the communication we produce, we want to create a strong connection with our users. We want to get them the information they need in a straightforward way and show that we know what’s important to them. As a government organization, we need to sound somewhat official; we also recognize that official doesn’t need to translate to stuffy, archaic, or aloof.
46 |
47 | For this reason, we use contractions in the writing we create for our site. We also encourage clients to consider using contractions, too, though we recognize this may not be the right choice for all contexts.
48 |
49 | The government is run by people for the benefit of people, and we never want users to forget that 18F is a group of enthusiastic, dedicated, hardworking (and friendly) folks. This desire informs how we craft our voice.
50 |
51 | ## Establishing your own voice
52 |
53 | Whether you realize it or not, you already have a unique voice; the tricky part can be classifying it and pinning it down.
54 |
55 | To describe your voice — which, in turn, will allow you to diagram it, create guidelines around it, and make it reproducible — you’ll need to do some investigation and self reflection. Ask yourself these questions:
56 |
57 | **What are my core values?** Your voice is a reflection of your core values. Before you craft a voice, consider the values your organization represents and how you can translate these into stylistic patterns. If you’re part of a young organization that hasn’t yet codified its values, you might use this opportunity to start that conversation. Crafting a voice before you’ve determined your organization’s values can be dangerous — your voice might not reflect what you eventually decide on. Along the same lines, if your organization is undergoing a large-scale values overhaul, you’ll want to make sure your organizational voice reflects your new values.
58 |
59 | **Who is my audience?** In writing, as elsewhere, your audience is paramount — without them, you’d have no reason to write. Put yourself in their situation and think about the stylistic traits that might appeal to them. Remember, your voice doesn’t need to appeal to everyone (and, in fact, shouldn’t — cure-alls cure nothing, as the old saying goes).
60 |
61 | Use your answers to these questions to craft a description of your voice. Once you’ve come up with your description, look it over and identify any contradictions or holes (never a good thing). While voices should be nuanced, they should also be cohesive.
62 |
63 | ### Choosing a tone
64 |
65 | As we mentioned earlier, your voice is a constant, but your tone is a variable. Consider the following: If you’re having an irredeemably terrible day, you might get peeved at a store associate who chirpily (and repeatedly) asks if they can help you with anything. While the associate maintained a helpful voice, they failed to shift from an energetic to a restrained tone based on your mood. As a result, their message (however valuable or well-intended) is lost on you.
66 |
67 | To avoid going the way of the associate, think about your users’ needs in different situations. Use these needs to determine your tone.
68 |
69 | Let’s consider three examples that target three different reader groups. Obituaries, technical blog posts, and marketing emails targeted at newly engaged couples have vastly different tones. Why? The three types of writing correspond to audiences in three highly different emotional states.
70 |
71 |
` tags or Markdown headings.) 67 | 68 | ### Introduction 69 | 70 | Include a short two- or three-sentence summary about the document to help the reader confirm whether they’re in the right place, and improve search engine indexing. 71 | 72 | ### Code 73 | 74 | Use [backticks](https://help.github.com/articles/basic-writing-and-formatting-syntax/#quoting-code) to style text and code snippets readers may want to copy and paste. For example: 75 | 76 | > Use the `legend` element to offer a label within each form element. 77 | 78 | > Copy and paste `mkdir /home/foo/doc/bar && cd $_` into Terminal. 79 | 80 | In the first example, `legend` is an HTML element and should be styled as code. “Element” is a technical concept and shouldn't be marked up as code. “Label” is both a concept and an HTML element but is used here in the former sense and should not be styled as code. 81 | 82 | Do not capitalize code elements, even at the start of a sentence, unless the term is capitalized in the code itself. 83 | 84 | Use [fenced code blocks](https://help.github.com/articles/creating-and-highlighting-code-blocks/) for multi-line code snippets, and specify the language to enable [syntax highlighting on GitHub](https://help.github.com/articles/creating-and-highlighting-code-blocks/#syntax-highlighting): 85 | 86 | > In JavaScript, to get the current value of a `select` element with an `id` of `mySelect`, use this: 87 | > 88 | > ```javascript 89 | > var el = document.getElementById("mySelect"); 90 | > var value = el.options[el.selectedIndex].value; 91 | > ``` 92 | 93 | Use [straight quotes](http://smartquotesforsmartpeople.com/) within code blocks rather than curly (or smart) quotes. 94 | 95 | #### Code-like elements 96 | 97 | The same rules apply to pieces of text that must be used exactly as presented, such as passwords or Wi-Fi network names: 98 | 99 | > `someCl3v3rN4me` is the name of our Wi-Fi network. 100 | > Your password is `PleaseChangeMeSoon`. 101 | 102 | ### Interface elements 103 | 104 | Use clear verbs to tell readers how to interact with interface elements: 105 | 106 | * _Choose_ from drop-down menus. 107 | * _Select_ or _deselect_ checkboxes and radio buttons. 108 | * _Click_ or _tap_ buttons. 109 | * _Follow_ or _open_ links. 110 | 111 | In the 18F Handbook, we emphasize the name of the interface label like so: 112 | 113 | > 1. In the **File** menu, choose **Save**. 114 | > 2. Select **I agree**. 115 | > 3. Click **Continue**. 116 | 117 | ### Tables 118 | 119 | Tables are generally suitable only for data: two or more “objects” (rows) that share two or more “values” (columns). In tables, column widths are the same for all rows, which can make them easier to scan visually. Tables are [easily navigable for sightless users](http://webaim.org/techniques/tables/) so long as the content is organized in a logical way. Here are some other guidelines to consider: 120 | 121 | * When listing numbers, it’s good practice to align them to the right of their cell, with the same decimal precision (“40.50” and “1.00”) so that the numbers are easier to compare while scanning. 122 | * Always align column headings up with the values in the columns. For example, numeric column headings should be aligned right if the values are, too. 123 | 124 | ### Links and additional resources 125 | 126 | It’s rare that a document lives on its own. Tell people where to go for help if they have questions. 127 | 128 | For documentation and guides, you might say: 129 | 130 | > For more information, see the [18F Code of Conduct](https://github.com/18F/code-of-conduct). 131 | 132 | To refer the reader to a Slack channel, follow this format from the 18F Handbook: 133 | 134 | > Still have questions? Ask in [#newcomers](https://18f.slack.com/archives/newcomers). 135 | 136 | If your work relates to several other documents, pick the most important ones or gather the links in a section at the bottom. 137 | -------------------------------------------------------------------------------- /_pages/our-style/trademarks-and-brands.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Trademarks and brands 3 | permalink: /our-style/trademarks-and-brands/ 4 | sidenav: our-style 5 | sticky_sidenav: true 6 | subnav: 7 | - text: Common trademarked words 8 | href: '#common-trademarked-words-with-alternative-terms' 9 | - text: Guidelines 10 | href: '#guidelines' 11 | --- 12 | Avoid using a trademark unless you’re referring to a specific product. 13 | 14 | This can be tricky when a trademarked name, like Kleenex, has become synonymous with an entire family of products. Try to use a generic word — like *tissue* — instead of a brand name. 15 | 16 | ## Common trademarked words (with alternative terms) 17 | 18 | - Band-Aid (adhesive bandage, bandage) 19 | - Bubble Wrap (packaging bubbles) 20 | - Chapstick (lip balm) 21 | - Crayola (crayons) 22 | - Dumpster (waste container, trash container) 23 | - Hi-Liter (highlighting marker) 24 | - iPod (MP3 player) 25 | - Kleenex (tissue) 26 | - Plexiglas (plastic glass) 27 | - Post-it note (adhesive note) 28 | - Q-Tips (cotton swabs) 29 | - Scotch tape (transparent tape) 30 | - Styrofoam (plastic foam) 31 | - Taser (stun gun) 32 | - Xerox (photocopy, copy) 33 | 34 | ## Guidelines 35 | 36 | Careful use of trademarked names and brands is important because the government shouldn’t endorse specific brands or products. When writing about corporate brands or products to illustrate a point, mention a range of related companies instead of a single provider. For example: 37 | 38 | > Twitter, Facebook, and YouTube can help you connect with users. 39 | 40 | Avoid linking to products or services, because people can see it as an endorsement. The same rule applies to the brands and products of individuals, such as personal websites or websites where you can buy their book. Do link to useful resources, like slide decks or how-to guides, from private individuals or companies. If you mention a trademark, capitalize and punctuate it in the trademark holder’s preferred style. 41 | -------------------------------------------------------------------------------- /_pages/our-style/urls-and-filenames.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: URLs and filenames 3 | permalink: /our-style/urls-and-filenames/ 4 | sidenav: our-style 5 | sticky_sidenav: true 6 | subnav: 7 | - text: Creating URLs 8 | href: '#creating-urls' 9 | - text: Creating filenames 10 | href: '#creating-filenames' 11 | - text: Presenting URLs and filenames in text 12 | href: '#presenting-urls-and-filenames-in-text' 13 | - text: Link text 14 | href: '#link-text' 15 | - text: Screen reader-only text 16 | href: '#screen-reader-only-text' 17 | - text: Additional resources 18 | href: '#additional-resources' 19 | --- 20 | 21 | ## Creating URLs 22 | 23 | URLs should be short, memorable, easy to type, and well-structured. 24 | Your control over your URL may be limited, but you should do what you can 25 | with the pieces you can control. 26 | 27 | In the vast majority of cases, everything a user can reach on your site 28 | should have a distinct URL that a user can bookmark and use later to 29 | reach that same location. 30 | 31 | When creating URLs, use dashes to separate words, omit articles 32 | (a/an/the), use the stems of verbs (`/make-thing/` rather than 33 | `/making-thing/`), and avoid extraneous terms. 34 | 35 | 36 | ### Domains 37 | 38 | Domains should reflect the user’s needs and not those of the 39 | organization. If your department is several layers deep in terms of 40 | bureaucratic structure, it’s unlikely that this is important to users, 41 | and there is likely minimal cost associated with using a more shallow 42 | domain. 43 | 44 | It’s not necessary to have `www.` at the start of a domain. This is a 45 | holdover from the early internet. Any domain that has a `www` level 46 | should also work if that level is omitted. 47 | 48 | Domains should not be more than three levels deep in most cases: 49 | `18f.gsa.gov` is fine, but `content-guide.guides.18f.gsa.gov` would not 50 | be. It’s rare that more than four levels is justifiable. 51 | 52 | At the same time, it’s not necessary to have a two-level domain for 53 | everything. 54 | 55 | Domain names should be short, using abbreviations unless those are 56 | likely to be meaningless to users. 57 | 58 | If a domain level has more than one word, you should strongly consider 59 | separating the words with dashes to make sure users read them the way 60 | you intend. If 18F had a project called EARS that for some reason needed 61 | a two-level domain, that domain should be `18f-ears.gov` and not 62 | `18fears.gov` (`ears.18f.gov` would probably be the ideal). 63 | 64 | Domains are case-insensitive. They should be written as lowercase. 65 | 66 | ### Paths 67 | 68 | Again, the shorter the better, but long paths are more excusable than 69 | long domains. 70 | 71 | Paths are typically understood as hierarchies that become increasingly 72 | specific: `/our-style/urls-and-filenames/` reflects that 73 | urls-and-filenames is part of our-style. If this were a much larger 74 | guide, it’s possible that it could be divided further, for example 75 | `/our-style/urls-and-filenames/creating-urls/`. 76 | 77 | Each level of a path should make it possible to find the content beneath 78 | it: 79 | 80 | - The content at the root level should reflect that `/our-style/` 81 | is present. 82 | - `/our-style/` should make it easy to find `urls-and-filenames/`. 83 | 84 | Conversely, the user should be able to remove a level from the path and 85 | end up at the parent of the original content. 86 | 87 | Paths should be designed to be sensible for the user, not to reflect 88 | internal technical or bureaucratic structure. For example, filename 89 | extensions like `.php` should be avoided as they reflect the internal 90 | technology used on the server (and will not reflect even that if the 91 | site later changes to a different technology). 92 | 93 | When separating words in a path, use hyphens. Hyphens are commonly 94 | understood by search engines to indicate word breaks (whereas other 95 | separators, like underscores, are not). 96 | 97 | Paths are case-sensitive. They should be lowercase, regardless of what 98 | they contain, as uppercase letters make them more difficult to type (and 99 | to remember). 100 | 101 | ### Examples 102 | 103 | #### Domain names 104 | 105 | - **Starting point**: 106 | `www.longnamecreationservice.departmentoflongnames.bureauofnames.gov`. 107 | - **Slight improvement**: 108 | `longnamecreationservice.departmentoflongnames.bureauofnames.gov`. 109 | 110 | **Rationale**: `www` is unnecessary and omitting it makes the URL easier to type. 111 | 112 | - **Very slight improvement**: 113 | `long-name-creation-service.departmentoflongnames.bureauofnames.gov`. 114 | 115 | **Rationale**: Hyphens make the URL easier to read. The same would 116 | be true for the other levels of the domain, but we're assuming you 117 | don't have control over those in these examples. 118 | 119 | - **Improvement**: `long-name-creation-service.bureauofnames.gov`. 120 | 121 | **Rationale**: The user doesn’t need the URL to reflect that the 122 | service belongs to the Department of Long Names. 123 | 124 | - **Better**: `lncs.bureauofnames.gov`. 125 | 126 | **Rationale**: This is shorter and easier to type. However, it 127 | relies on users thinking of the service by that abbreviation. 128 | 129 | - **Better**: `make-long-names.bureauofnames.gov`. 130 | 131 | **Rationale**: If the users aren’t familiar with that abbreviation, 132 | a shorter description of what the service does is better to have as 133 | the lowest level of the domain. 134 | 135 | #### Paths 136 | 137 | - **Starting point**: 138 | `/services/default/php/forms/departmentoflongnames/longnamecreationservice/index.php?action=create`. 139 | - **Slight improvement**: 140 | `/services/default/php/forms/departmentoflongnames/longnamecreationservice/index.php`. 141 | 142 | **Rationale**: Assuming that creation is the most likely action 143 | users will want to take, make it the default and strip the 144 | requirement for the query string. 145 | 146 | - **Slight improvement**: 147 | `/services/default/php/forms/departmentoflongnames/longnamecreationservice/`. 148 | 149 | **Rationale**: The default page should be delivered automatically, 150 | making the inclusion of `index.php` unnecessary. Also, hide the 151 | technical details (`.php`). 152 | 153 | - **Improvement**: `/departmentoflongnames/longnamecreationservice/`. 154 | 155 | **Rationale**: Users don’t need to know the technical setup of 156 | the site. 157 | 158 | - **Improvement**: 159 | `/department-of-long-names/long-name-creation-service/`. 160 | 161 | **Rationale**: Words should be separated with hyphens. 162 | 163 | - **Better**: `/department-of-long-names/lncs/`. 164 | 165 | **Rationale**: As above, if the users are familiar with the 166 | abbreviation, use it to make the path shorter. 167 | 168 | - **Better**: `/department-of-long-names/make-long-names/`. 169 | 170 | **Rationale**: As above, if they aren’t familiar with the 171 | abbreviation, use a shorter description of what the server does. 172 | 173 | #### Both 174 | 175 | - **Starting point**: 176 | `www.longnamecreationservice.departmentoflongnames.bureauofnames.gov/services/default/php/forms/departmentoflongnames/longnamecreationservice/index.php?action=create`. 177 | - **Improvement**: 178 | `make-long-names.bureauofnames.gov/department-of-long-names/make-long-names/`. 179 | 180 | **Rationale**: This combines the suggestions from the previous 181 | two sections. 182 | 183 | - **Better**: `make-long-names.bureauofnames.gov`. 184 | 185 | **Rationale**: This is reasonable if the Department of Long Names 186 | has only a couple of services that might be popular enough to 187 | warrant their own subdomains, particularly if they don’t necessarily 188 | fit cleanly into other content and stand alone. 189 | 190 | - **Better**: `bureauofnames.gov/department-of-long-names/make-long-names/`. 191 | 192 | **Rationale**: This is reasonable if the Long Name Creation Service is 193 | one of many related services that the Department of Long Names provides. 194 | 195 | ## Maintaining URLs 196 | 197 | Users constantly bookmark and share web pages, making the maintenance of 198 | permanent and long-lasting URLs an important piece of content management. 199 | Broken links obscure the internet landscape. 200 | 201 | URLs should never stop working. 202 | 203 | This is not as technically challenging as it sounds. If the domain — the 204 | high-level domain, not subdomains — is lost, the URLs will be lost, but 205 | otherwise it’s entirely possible to keep them working. Planning for them 206 | to continue working is the first step in any process that involves new 207 | URLs. 208 | 209 | Whenever possible, maintain original URLs. 210 | In all other cases, set up a redirect for outdated URLs and links; 211 | this is almost always a painless task for web managers. There are a variety 212 | of ways to accomplish this, some of them requiring more 213 | technical work than others. It’s most difficult to accomplish when 214 | moving from URLs that include query parameters, as some early website 215 | systems did. Sensibly-constructed URLs are easier to migrate. 216 | 217 | Some examples: 218 | 219 | ### Changing subdomains 220 | 221 | If we changed our name from 18F to 19G, we would change our domain, so 222 | this page would be located at 223 | `https://pages.19g.gov/content-guide/urls-and-filenames/`. We would keep 224 | the `18f.gov` domain running, but all it would do would redirect 225 | everything to `19g.gov`. Users who entered the old URL would be 226 | redirected and might not even notice the URL change. 227 | 228 | If we decide to eliminate the pages subdomain and put this directly on 229 | `18f.gov`, we would do essentially the same thing, keeping this 230 | subdomain and adding a rule to redirect to the same path on `18f.gov`. 231 | 232 | ### Changing paths 233 | 234 | If we produce lots and lots of content in the future, it might become 235 | sensible to change our path to reflect this, and we might want to have a 236 | guides level, so that the new URL for this page would be: 237 | `https://pages.18f.gov/guides/content-guide/urls-and-filenames/`. In 238 | this case, we would add a rule that redirects everything starting with 239 | `/content-guide/` to `/guides/content-guide/`. 240 | 241 | This also means that URLs, and parts of URLs, should not be re-used. 242 | Once we use `/content-guide/` to refer to this guide, we can no longer 243 | decide in future to use `/content-guide/` as the location for something 244 | else, even if we later change the URL for this guide. 245 | 246 | ## Creating filenames 247 | 248 | Use hyphens to separate words, just as with URLs. 249 | 250 | Lowercase is better, because it’s easier to type and to remember. 251 | 252 | Use the right extension — PDFs should have `.pdf` at the end, JPGs 253 | should have `.jpg` at the end, etc. 254 | 255 | Shorter is better, but the content should be descriptive to the user, 256 | and it’s better to have long descriptive filenames than short obscure 257 | ones. `summary-of-pay-gap-findings.pdf` is better than `paygap.pdf` or 258 | `smmrypgpfnds.pdf`. 259 | 260 | If the file content is based on a date or time, include that: the 1998 261 | report for an organization should have `1998` in the filename, a 262 | February issue of a magazine should have the year and the month, and a 263 | PDF of a daily newspaper should have year, month, and date. When 264 | including dates, use the `YYYY-MM-DD` format, i.e. `2015-10-13`. 265 | 266 | Avoid the use of special characters beyond the hyphen and period, unless 267 | absolutely necessary. Do not include spaces (use hyphens in their 268 | place). 269 | 270 | ## Presenting URLs and filenames in text 271 | 272 | Whether beginning with the protocol or not, always lowercase URLs in 273 | text. Paths are case-sensitive, however, so their casing must be 274 | preserved. 275 | 276 | In interactive contexts, particularly web pages, URLs (except when used 277 | as examples, as throughout this document) should always be active links. 278 | When they’re active links, do not include the protocol in the link text. 279 | 280 | In non-interactive contexts, such as print, the protocol can be omitted, 281 | assuming `http://` and `https://` both work and bring the user to the 282 | same place. 283 | 284 | There are occasions where URLs should be delimited; use `<` and `>` for 285 | this. This is not normally necessary in interactive contexts where the 286 | link is clearly defined, but is most often relevant in email, where the 287 | writer may have to guess at what their email program will turn into a 288 | link. This is particularly true when URL contains spaces. 289 | 290 | Filenames are case-sensitive, and their case should be preserved when 291 | they are referred to in text; do not capitalize if beginning a sentence 292 | with a filename that begins with a lowercase letter. Filenames may need 293 | to be delimited in the same way as URLs. 294 | 295 | ### Examples 296 | 297 | Capitalization on a web page: 298 | 299 | > [gsa.gov](https://gsa.gov) is the General Services Administration 300 | > site. 301 | 302 | Capitalization in print: 303 | 304 | > gsa.gov is the General Services Administration site. 305 | 306 | Delimiting an awkward URL in email: 307 | 308 | > When you get the chance, could you redirect <example.com/spaces in 309 | > URLs are bad/> to <example.com/spaces-in-urls-are-bad/>, as 310 | > per our guidelines, and make the latter the definitive URL for the 311 | > page? 312 | 313 | ### URL Structure 314 | 315 | 1. **The protocol.** For example `https://`, `http://`, or `ftp://`. 316 | The `://` is always present. 317 | 2. **The domain.** For example `18f.gsa.gov`. This is “where on the 318 | internet” the URL is referring to. Also called: 319 | - site 320 | - domain name 321 | - server 322 | 323 | 3. **Optional: the port.** A number specifying how to access the 324 | content on this particular domain. Not normally used on 325 | production sites. Follows the domain, separated by a colon, for 326 | example `http://dev.example.com:8080`. 327 | 4. **The path:** what resource on the domain the URL is referring to. 328 | If omitted, defaults to `/`, the “root level” of the domain. Always 329 | starts with a slash, and different levels of resources are separated 330 | by slashes. For example: `/content-guide/` is the path in 331 | `https://pages.18f.gov/content-guide/`. 332 | 5. **Optional: the query string.** Normally contains parameters that 333 | have been submitted to the site, for example with searches. 334 | `?q=18f+content+guide` is the query string in 335 | `https://www.google.com/search?q=18f+content+guide`. 336 | 6. **Optional: the fragment.** Normally this indicates a specific 337 | section of a page, but can also be used for other things by 338 | web applications. `#main` is the fragment in 339 | `https://pages.18f.gov/content-guide/specific-words-and-phrases/#main`. 340 | 341 | The protocol should almost always be `https://` unless you’re forced to 342 | use `http://`. Users entering `http://` as the protocol should be 343 | redirected to `https://`. If at all possible, your URL should not 344 | contain a port. Query strings should also be avoided. Fragments can be 345 | used as a helper for the user, but should not be necessary for the user 346 | to find the relevant content. 347 | 348 | ## Link text 349 | 350 | It’s important to remember that users of screen readers will often [skip from one link to another][link-to-link], skipping the text in between, as a way of skimming for the content they need. 351 | 352 | This ultimately means that link text should be understandable independent of the text surrounding it. Avoid ambiguous link text like *click here*, *here*, or *learn more* whenever possible. 353 | 354 | For example, instead of: 355 | 356 | > [Click here][CoC] for more information about our Code of Conduct. 357 | 358 | Use: 359 | 360 | > For more information, see the [18F Code of Conduct][CoC]. 361 | 362 | This has an added benefit of improving search results for sighted users. 363 | 364 | [CoC]: https://github.com/18F/code-of-conduct 365 | [link-to-link]: http://webaim.org/techniques/hypertext/#link_to_link 366 | 367 | ## Screen reader-only text 368 | 369 | In some situations, descriptive links may be overly verbose or redundant for 370 | sighted users. Here’s an example from the [betaFEC site][]: 371 | 372 | [![Screenshot of Federal Election Commission website, with Candidates and committees highlighted under who can register and report, with a prominent button-style link at the bottom that says learn more]({{ "/images/betaFEC.png" | relative_url }})]({{ "/images/betaFEC.png" | relative_url }}) 373 | 374 | Here the *Learn more* link is appropriate for sighted users, but it may be confusing to screen reader users. In such situations, it’s possible to add [invisible text just for screen reader users][sr-only]. For example, the U.S. Web Design Standards has a special CSS class called `usa-sr-only` for this purpose. Using this class, the aforementioned *Learn more* link might be written in HTML like so: 375 | 376 | ```html 377 | 378 | Learn more 379 | 380 | about candidate and candidate committees 381 | 382 | 383 | ``` 384 | 385 | This would keep the link concise for sighted users, while also providing 386 | important context for screen reader users. 387 | 388 | If you want to use text intended only for screen readers on your project but 389 | are unfamiliar with CSS, ask your project’s front end developer for help. They 390 | can create a CSS class for you if one doesn’t already exist. Alternatively, 391 | reach out to [#g-accessibility][] or [#g-frontend][] in Slack! 392 | 393 | [#g-accessibility]: https://18f.slack.com/archives/g-accessibility 394 | [#g-frontend]: https://18f.slack.com/archives/g-frontend 395 | [sr-only]: http://webaim.org/techniques/css/invisiblecontent/ 396 | [betaFEC site]: https://beta.fec.gov/registration-and-reporting/ 397 | 398 | ## Additional resources 399 | 400 | * [WebAIM: Links and Hypertext](http://webaim.org/techniques/hypertext/) 401 | * [W3C: Don’t Use “Click Here” as Link Text](https://www.w3.org/QA/Tips/noClickHere) 402 | * [Stop Clicking Here! 7 Superior SEO Alternatives to Generic Links](https://moz.com/blog/click-here-seo) 403 | * [18F Accessibility Guide](https://pages.18f.gov/accessibility/links/) 404 | * [GSA Linking Policy](https://www.gsa.gov/website-information/website-policies#linking) 405 | -------------------------------------------------------------------------------- /_pages/our-style/voice-and-tone.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Voice and tone 3 | permalink: /our-style/voice-and-tone/ 4 | sidenav: our-style 5 | sticky_sidenav: true 6 | subnav: 7 | - text: The difference between voice and tone 8 | href: '#the-difference-between-voice-and-tone' 9 | - text: Our voice 10 | href: '#our-voice' 11 | - text: Establish your own voice 12 | href: '#establishing-your-own-voice' 13 | - text: Further reading 14 | href: '#further-reading' 15 | --- 16 | 17 | If you’re like many folks, you might not be sure of the difference between voice and tone. Maybe you’ve never deliberately crafted a voice and don’t know where to start. Not to fret! In this section, we’ll discuss the differences between voice and tone, how we describe our organizational voice, how to establish your own voice, and how to choose a tone that’s appropriate for whatever you’re writing. 18 | 19 | ## The difference between voice and tone 20 | 21 | It’s a common question and one that writers might ask themselves: What’s the difference between voice and tone? 22 | 23 | Our **voice** is our unique personality. It can be helpful to think of voice as analogous to a person’s voice. Just as you can identify your best friend in a crowd as soon as you hear her distinctive laugh, you can use an author’s or organization’s voice to identify a piece of writing even if you haven’t seen the byline. A well-crafted voice communicates personality and values — it’s a distilled representation of an author or organization. 24 | 25 | **Tone** is more like attitude — the emotional context of a piece. It can be helpful to think of authorial tone as analogous to a person’s tone of voice. Just as a person would use a somber, sympathetic tone of voice to console a friend about the loss of a pet, an author writing a story about a natural disaster would most likely use a somber, serious tone. Conversely, an author writing a blog post about the launch of a new product might use an enthusiastic, upbeat tone. 26 | 27 | ## Our voice 28 | 29 | At 18F, we like to communicate in a friendly, straightforward way. We consider our voice to be: 30 | 31 | * Authoritative 32 | * Conversational 33 | * Friendly 34 | * Instructive 35 | * Welcoming to all audiences 36 | 37 | We believe that government communication can — and should — be fun and easy to read, and our voice represents this. 38 | 39 | Here are a few sentences, taken from this guide, that exemplify our voice: 40 | 41 | > We created this guide for reference on an as-needed basis. It’s here when you’re wondering whether to capitalize the word _federal_, for instance, or when you’re wondering how to create a friendly, informational tone. 42 | 43 | ### Use contractions 44 | 45 | In all of the communication we produce, we want to create a strong connection with our users. We want to get them the information they need in a straightforward way and show that we know what’s important to them. As a government organization, we need to sound somewhat official; we also recognize that official doesn’t need to translate to stuffy, archaic, or aloof. 46 | 47 | For this reason, we use contractions in the writing we create for our site. We also encourage clients to consider using contractions, too, though we recognize this may not be the right choice for all contexts. 48 | 49 | The government is run by people for the benefit of people, and we never want users to forget that 18F is a group of enthusiastic, dedicated, hardworking (and friendly) folks. This desire informs how we craft our voice. 50 | 51 | ## Establishing your own voice 52 | 53 | Whether you realize it or not, you already have a unique voice; the tricky part can be classifying it and pinning it down. 54 | 55 | To describe your voice — which, in turn, will allow you to diagram it, create guidelines around it, and make it reproducible — you’ll need to do some investigation and self reflection. Ask yourself these questions: 56 | 57 | **What are my core values?** Your voice is a reflection of your core values. Before you craft a voice, consider the values your organization represents and how you can translate these into stylistic patterns. If you’re part of a young organization that hasn’t yet codified its values, you might use this opportunity to start that conversation. Crafting a voice before you’ve determined your organization’s values can be dangerous — your voice might not reflect what you eventually decide on. Along the same lines, if your organization is undergoing a large-scale values overhaul, you’ll want to make sure your organizational voice reflects your new values. 58 | 59 | **Who is my audience?** In writing, as elsewhere, your audience is paramount — without them, you’d have no reason to write. Put yourself in their situation and think about the stylistic traits that might appeal to them. Remember, your voice doesn’t need to appeal to everyone (and, in fact, shouldn’t — cure-alls cure nothing, as the old saying goes). 60 | 61 | Use your answers to these questions to craft a description of your voice. Once you’ve come up with your description, look it over and identify any contradictions or holes (never a good thing). While voices should be nuanced, they should also be cohesive. 62 | 63 | ### Choosing a tone 64 | 65 | As we mentioned earlier, your voice is a constant, but your tone is a variable. Consider the following: If you’re having an irredeemably terrible day, you might get peeved at a store associate who chirpily (and repeatedly) asks if they can help you with anything. While the associate maintained a helpful voice, they failed to shift from an energetic to a restrained tone based on your mood. As a result, their message (however valuable or well-intended) is lost on you. 66 | 67 | To avoid going the way of the associate, think about your users’ needs in different situations. Use these needs to determine your tone. 68 | 69 | Let’s consider three examples that target three different reader groups. Obituaries, technical blog posts, and marketing emails targeted at newly engaged couples have vastly different tones. Why? The three types of writing correspond to audiences in three highly different emotional states. 70 | 71 |
| Type of writing | 74 |Intended readership | 75 |Tone | 76 |Example | 77 |
| Obituary of a prominent community member | 80 |People who knew (or knew of) the deceased | 81 |Respectful, reverent, somber | 82 |“Professor Pelham was respected by his colleagues and revered by students, many of whom would wake before dawn on registration day to ensure gaining entry to his classes. His wit, gentle humor, and compassion left their mark on everyone he talked to.” | 83 |
| Blog post announcing open source documentation guide | 86 |Developers and other readers with a strong tech background | 87 |Direct, impartial | 88 |“The Open Source Style Guide is a comprehensive handbook for writing clear, accessible, and user-friendly documentation so that your open source code repositories are accessible both internally and externally." | 89 |
| Marketing email from the boutique bridal department of a well-known clothing company | 92 |Newly engaged women (ages 28 through 33) | 93 |Enthusiastic, earnest, bubbly | 94 |“Say ‘I do!’ to 25% off. Now through July 3rd, take an additional 25% off all bridal wear and accessories. Celebrate your big day in style (and get a jumpstart on your honeymoon fund!).” | 95 |