Writing

As a remote company, written communication is often how people get to know us. Whether they’re federal employees, potential staff members, or folks interested in our work. As we scale and grow the breadth of our communication, we need a set of core guidelines and principles that define Ad Hoc’s writing style. These guidelines are intended to make our communications consistent, clear, and undoubtedly from Ad Hoc.

This guide is a companion to the Ad Hoc Brand Guidelines. This is a living document and is subject to change as Ad Hoc’s work changes. If you have questions for feedback, please contact Andre Francisco.

Content principles

  • Be consistent. Use words and style consistently to earn trust and confidence from our customers and the government technology community.

  • Know your audience. Write for a defined reader. Consider their background knowledge, the task they’re trying to complete, and what questions they may ask after reading your words. When possible, apply the same user-centered design techniques that you would to any project to your writing.

  • Write with a purpose. Have a clear goal in mind for everything you write. Use that goal to make decisions about tone, length, content, organization, and format. The better you know your audience and articulate your goal, the more effective your content will be.

  • Choose clarity over cleverness. From headlines to body copy to button text, be clear about the information you’re trying to convey. Use everyday human words, short sentences, and plain language.

  • Prioritize accessibility. Beyond meeting Section 508 accessibility rules, take extra steps to make your content broadly accessible and inclusive, including to people unfamiliar with the subject matter. Aim to write at a 9th grade reading level.

Scope

This style guide is designed to cover Ad Hoc’s official external and internal content and communications. If you’re writing content for a customer project, follow the guides for that agency. If your project or agency does not have a style guide, you can use this guide for broad principles and refer to the AP Style Guide and the Government Publishing Office Style Manual for specific usage.

This guide is designed to cover Ad Hoc’s:

  • Website

  • Blog

  • Internal communications

  • Memos

  • Handbook

  • The Hub

  • Other official written communications, both internal and external

Ad Hoc’s voice

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.

Inclusive language and accessible style

All Ad Hoc content should be both inclusive and accessible. 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 inclusive and accessible values.

By inclusive, we mean content that is welcoming to everyone who encounters it. Inclusive content uses respect and empathy as tools to help facilitate clear communication. When paired with accessible language, inclusive content seeks to bring everyone into the group of government technology.

By accessible, 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 best practices across our practice areas, we will update this guidance so that our content remains equally accessible.

If you have a question about the best way to use inclusive language and accessible style, there are people here to help. You can ask inclusive language questions in #diversity-tt and accessible style questions in #accessibility 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. More detailed usage guidelines from the National Center on Disability and Journalism.

  • 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.

  • Gender — Use gender neutral language whenever possible. When writing about hypothetical people, use they or them as singular pronouns instead of he/she. For specific people, use their correct pronouns. Avoid phrases that assume binary gender, such as ladies and gentlemen. Use general terms for professions that are often gendered, for example use server instead of waitress.

  • Guys — Use folks, team, y’all, or another non-gendered term when referring to a hypothetical or mixed gender group of people.

  • 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.”

  • Marginalized populations — When writing about people that have been systematically excluded from aspects of American life, be as specific as possible. Avoid generalizations about underrepresented groups, acknowledge that people are multidimensional, and allow individuals to choose how they would like to be identified. See the Conscious Style Guide for specific recommendations.

  • 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.

Ad Hoc’s style

  • Use sentence case capitalization for headlines and headings, the same way you would for body text.

  • Use active voice whenever possible.

  • Bulleted lists are your friends. Break up long lists into bullets to improve readability.

  • Reserve capitalization for proper nouns and the beginning of sentences. See below for specific examples.

  • Single space after a period, always.

  • Avoid abbreviations and acronyms whenever possible. Spell out full names and terms or provide plain language definitions in the text. When introducing an acronym, use the full name on first reference followed by the acronym. For example, Department of Veterans Affairs (VA). If you will only use an acronym once or twice, use the full name every time instead of requiring the reader to learn a new acronym.

  • Respect the capitalization style of website URLs unless the URL begins a sentence, then the first letter should be capitalized. See below for specific examples.

  • Use the serial, or Oxford comma, in lists of three or more items. Ad Hoc’s writing voice is experienced, optimistic, and respectful.

  • Use contractions such as they’re and we’ll. If your document is rigidly formal, you can avoid contractions to create a more conservative tone.

Specific usage

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

  • Accessibility Beyond Compliance

  • 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

  • MACFin

  • Search.gov

  • U.S., U.S. government

  • VA.gov

  • Veteran, capitalized so as to match VA style

  • Vets.gov

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. Andre Francisco can help you at any step of the writing process or you can poll the audience in #writing for quick questions.

  • If you have questions about the content of this guide or you see Ad Hoc content that you think does not follow this guide, please contact Andre on Slack.

Helpful references