Brand Toolkit: Writing

Part of creating a consistent style and strong brand is to use a single voice across Ad Hoc’s content and communications. Even across many authors and types of content, it’s best to use a single voice that is aligned with Ad Hoc’s brand values. Below are some attributes pulled from Ad Hoc’s Brand Guidelines that describe the written voice we’d like to achieve.

• Experienced

• Optimistic

• Respectful

• Authoritative

• Mission-driven

• Concise

• Aspirational

While this voice should remain consistent, you should adjust the tone of each piece of content to meet the needs of the audience and purpose of the content. Read the 18F Content Guide for a brief explanation of the difference between voice and tone. In addition, we value an authentic voice for content from individual team members, such as blog posts and conference talks. Ad Hoc editors and content strategists will work with you to strike a balance between following this guide and maintaining your voice for pieces of content with your name on them.

Welcoming language and approachable

All Ad Hoc content should be both welcoming and approachable. By being specific in your word choices and welcoming with your formatting and tone, you will better communicate your ideas and honor Ad Hoc’s values.

By welcoming, we mean content that is approachable to everyone who encounters it. Welcoming content uses respect and empathy as tools to help facilitate clear communication. Welcoming content seeks to bring everyone into the group of government technology.

By approachable, we mean both compliant with Section 508 requirements and easy-to-understand by a wide range of people. As Ad Hoc develops more guidance on accessibility compliance best practices across our practice areas, we will update this guidance so that our content remains equally easy to understand.

If you have a question about the best way to use welcoming language and approachable style, there are people here to help. For more, reach out to our #comms-marketing team on Slack.

Here are specific guidelines to consider when writing:

• Ability — Refer to a disability only when relevant. Avoid terms that contribute to stigma around disability or mental illness: blind spot, crazy, tone deaf, lame, insane, or psycho.

• Age — Refer to someone’s age only when relevant. We prefer older person or senior to elderly, and youth or children to boys and girls. Don’t use women or older people as substitute for novice or beginner. For example, don’t say it’s so simple your grandmother could use it.

• Alt text — Ensure all images, photographs, and graphics in your content have well-written alt attributes that describe the visual content on the page. This helps users with screen readers properly navigate and understand Ad Hoc’s content. Refer to the Indiana University overview on alt text or the WebAIM tutorial on alt text for more details.

• Citizenship — When talking about government services for people who live in the U.S., be careful about using citizen or Americans as a generic term. Be as specific as possible, and use public, people, or folks when talking about generic audiences.

• Headings — Use a consistent, logical sequence of headings when structuring your content. Begin with an h1 title and do not skip heading levels as you add more granular paragraphs. You may go back up from an h3 to an h2, but do not skip from an h2 to an h4. Refer to the WebAIM screen reader survey (finding information) for more details.

• Link text — Use descriptive words for link text. Avoid read more or click here. Descriptive links help both sighted users and people using screen readers understand where a link is going to take them. For example, “Read more about what the San Jose team learned during the workshop.”

• Native American or indigenous peoples terms — Avoid using terms from Native American and indigenous peoples culture out of context. For example, spirit animal comes from sacred traditions and should not be used casually. Try using fictional terms instead, like patronus. Avoid terms that contribute to stereotypes: powwow, off the reservation, circle the wagons, on the warpath.

• Plain language — Use simple, straightforward language whenever possible. Avoid using technical or government jargon when writing for a general audience.

• Sexual terms — Avoid using sexy, intimate, or other sexual terms to describe technology, projects, or our work. Use a more descriptive adjective that says exactly what you like about something.

• Violent terms — Some phrases and names have entered common usage that contain violent words or imagery. Avoid terms like slave repository, killing it, or strangler pattern. Use plain language or alternative terms instead.

The terms below are listed how they should be used, with additional explanation as appropriate.

• Ad Hoc

• adhoc.team

• Blue Button

• Centers for Medicare & Medicaid Services

• consumer, not private sector. Creating an experience on par with consumer internet services.

• customer, not client

• Department of Veterans Affairs

• DevOps

• digital services, not digital products

• federal, unless part of a proper noun such as the Federal Bureau of Investigation

• government technology, not civic tech

• government, unless part of a proper noun such as the Government Accountability Office

• HealthCare.gov

• human-centered design, preferred over user-centered design to describe Ad Hoc’s work

• Search.gov

• U.S., U.S. government

• VA.gov

• Veteran, capitalized so as to match VA style

Writing tips

• Once you have your audience and purpose in mind, start with an outline. Creating even a bare-bones structure for your content will help you organize your thoughts and begin writing. Stuck on how to start? Start in the middle: skip to a later section in your outline and return to the intro when you have something on the page.

• As much work happens in editing as in writing. Take a break from your words and come back with a fresh perspective. Read every word out loud. If a sentence is difficult to say or confusing to follow, give it an edit. Boldly change or remove sections that aren’t right for your audience or purpose, even if you like how they sound.

• When in doubt, narrow the scope of your content. You should aim to communicate one central idea in each piece of content. If a blog post begins to feel like a novel, break it into a series. Make it a priority to create content your audience can consume and understand in one sitting.

• Ask for help, the more specific the better. Let editors know what you’re struggling with and what type of feedback would be helpful. Do you need help ensuring every comma meets Ad Hoc style or are you concerned with the logical flow of the content? Setting expectations can help editors give you the feedback that will be most useful. For more help, Ad Hoc team members should join us in our #writing channel.

Helpful references

• Ad Hoc Brand Guidelines

• 18F Content Guide

• USA.gov Bilingual Content Guide

• VA Content Guide

• Government Publishing Office Style Manual