direct-file/docs/design/Direct File Content Style Guide.md

Direct File Content Style Guide

Use this content style guide to help ensure Direct File content is clear, consistent, and usable. Spanish-specific guidelines are included where needed. When questions of style come up that this content style guide doesn't address, refer to global IRS style guides.

Helpful Content Resources

Federal plain language guidelines: plainlanguage.gov
https://www.plainlanguage.gov/

Content design: planning, writing and managing content - Guidance - GOV.UK
https://www.gov.uk/guidance/content-design

Explore how people refer to tax/financial concepts with Google Trends
https://trends.google.com/trends/

Style guides by government agencies: Digital.gov
https://digital.gov/

W3C web accessibility: Writing for Web Accessibility
https://www.w3.org/WAI/tips/writing/

The A11y project: WCAG Compliance checklist
(https://www.a11yproject.com/checklist/)

Volunteer Income Tax Assistance (VITA) Intake Sheet: Form 13614-C (Rev, 10-2022) (https://www.irs.gov/pub/irs-pdf/f13614c.pdf)

Approach and General Guidelines

Gremlins Rules for Direct File Content

Absolutely, positively follow these rules to avoid any gremlins popping up!

1. Do have Chief Counsel review content. Small spelling corrections or capitalization for style can be done without Chief Counsel review. However, any tax law or solicitation of info from the taxpayer will need Subject Matter Expert (SME) review
2. Don't say "deleted" (instead say "removed"). Technically, if a person removes a Form W-2 or a draft federal tax return from Direct File, the information isn't deleted within the database. It's more accurate to say "removed"
3. Beware of the use of "process." Use the word "process" carefully. At the IRS, "processed" or "processing" refers to the last step, when a tax return is complete and a refund (if any) is issued. Avoid using the word "processing" to describe the period of time when a tax return is sent from Direct File to Modernized E-file (MeF) because this may be inaccurate
4. Use the terms and phrases on the Direct File Word choice list. These have been selected carefully based on IRS guidance, content best practices, and user research
5. Do remember that there are three PINs used in Direct File: Identity Protection (IP) PIN, Self-Select PIN, and third-party designee PIN. Consider carefully how those are referred to on each screen or flow since user research has shown it to be confusing to folks (especially, IP PIN and Self-Select PIN)
6. Do coordinate with IRS OLS about "meal" links to use. Don't use IRS website's newsroom links as "meal" links. IRS considers those as snapshots in time. OLS can share guidance on what's up to date or is available in Spanish
7. Don't rely solely on the Interactive Tax Assistant (ITA). You may find that information when search but the information is contextual based on certain responses. Going to one ITA page as a "meal" link would be dropping people into the experience that may not apply to their tax situation
8. Above all, don't have any personal identifiable information (PII) in text that might show up as a URL. Do not include PII in link text, button text, meta page titles, or accordion headers. Analytics use URLs in tracking stats. We cannot have PII showing up in analytics reports

Content Design Principles

✓ Use plain language

Plain language is the law. Using plain language will help ensure our content is easy to understand and welcoming to all taxpayers. Plain language isn’t just about communicating clearly, it also plays a major role in preventing mistakes, earning trust, building confidence, and reducing anxiety. And it makes translations easier and higher quality.

This will help the widest range of taxpayers, including those with low literacy, low tax literacy, limited English proficiency, who primarily use mobile devices or assistive technology, or are stressed and time pressed (i.e., EVERYONE).

• Use simple words and phrases. Select short words, when possible. An exception could be made when more or longer words may make the information clearer.
• Use words and terms taxpayers would use whenever possible. If legalese or jargon is so pervasive that removing it could cause confusion, try supplementing it with plain language (or lead with the plain language version and provide official term as secondary).
  • Avoid using quotation marks around IRS terms that can be confusing, like "standard deduction," but that we'll probably end up using. Quotation marks distance the user from the term or concept, and we should use them sparingly.
• Avoid homophones that may cause confusion with low literacy taxpayers (e.g., accept and except).
• For Spanish: Find substitutes for unclear wording, like manutención (cost of living/costos de vida). Keep copy as simple as possible, even if the translation needs to be slightly modified

Research insights for this decision

Research insight for this content decision: Use plain language to explain tax concepts in an accessible way. It helps taxpayers understand what's being asked and feel more confident in making a selection or a response.

Why: User research study F01 Feedback sessions IRS employees found that if language is hard to understand then a user won't feel like they can easily answer a question. Positive feedback on DF's use of plain language from a user research study: “It's much more basic, doesn't talk as technical. Some other programs think you know what you're talking about, but you might not. Clean, clear language. Hard to mess up.”

Research insight related to this content decision: Avoid cutesy language that can detract from plain language and clarity. Also, include plain language explanations for tax terms.

Why: User research S13 Touchpoints Free Text Synthesis Survey Research found that taxpayers are looking for a clear, authoritative voice for the content.

Research insight related to this content decision: If the translation needs to be slightly modified from English, use words that people understand better for the context of the question.

Why: User research Recco #10 found that the term “manutención” was either not recognizable or associated with child support. Participants were able to understand the question but struggled to choose an answer due to the inclusion of this word.

✓ Be concise

On average, users only read about 28% of words on a web page. Writing that’s concise, scannable, and objective can result in a 124% improvement in usability.

• Be direct.
• Use shorter sentences and paragraphs, use bulleted lists where it makes sense.
• For Spanish: Use simple, short translations, particularly for call to action buttons and headings.

Tip: even if you have the space, try re-writing as if you only had half the space — you'll be surprised how much you can trim out unnecessary words.

Research insights for this decision

Research insight related to this content decision: Easy to use and streamlined overall tool allowed users to focus more than other tools.

Why: User research S02 Usability Testing: "You and Your Household" Shared Custody found that concise language let users move quickly and easily through the questions.

✓ Use inclusive language

As an extension to doing plain language, we also aim to use language that resonates with all types of taxpayers.

• Don’t make assumptions about marital or family relationships.
• Use gender neutral language like "spouse" instead of "husband" or "wife" and "sibling" instead of "brother" or "sister." For Spanish: Use gender neutral words such as "cónyuge" instead of esposo(a), unless the context requires it. For example: ¿Tu cónyuge es ciego(a)?
• It’s ok to use singular they/them.
• Don't use figurative language like idioms, slang, and clichés for tasks or vital information. It may be appropriate to use some casual language like "Pick up where you left off" if followed by a more directly labeled action button/link (but these should be tested!).
• Use people-first language and avoid using circumstances or situations to define a person (ex: say "experiencing homelessness" rather than "homeless").
• Be mindful of non-citizens and individuals with a wide range of immigration and visa statuses.

Want more? See Guidelines for Writing About People With Disabilities (PDF) and Conscious Style Guide for more suggestions about writing about disabilities, age, gender, etc. and Mail Chimp Content Style Guide’s Writing for Translation for more suggestions for writing for an international audience.

✓ Write for action (when action is needed)

• Lead with action verbs.
• Use active voice, except when the law is the actor.

Meh 😑	Good 😀
Taxes can be filed...	You can file your taxes

✓ Be neutral

• Focus on facts.
• Avoid language that could feel like marketing, a slogan, or coercive.

✓ Speak directly to taxpayers and use personal context

• Use "you" instead of "my" as a modifier. Ex. "Your taxes" vs. "My taxes." We do this because “my” implies possession to an absolute degree which isn't a good fit for our current tool. "My" would be appropriate for something like a dashboard they are allowed to personalize.
• Once a taxpayer’s name is known, use it throughout the experience in addition to referring to "you."
• When explaining tallies and tax concepts, use real numbers and discuss in context of the taxpayer’s real situation to the extent possible. "What does this mean for me?"

Research insights for this decision

Research insight related to this content decision: We need to use examples that feel personal and relatable to taxpayers' personal situations. If the question and snack do not reflect people's real understanding of their custody situations, then they are guessing and may feel unsure.

Why: User research S02 Usability Testing: "You and Your Household" Shared Custody found that users will try to answer the question as best they can, but without a relatable example they aren't confident in their answer.

✓ Use an appropriate voice and tone

See voice and tone.

✓ Let complex information unfold

Taxpayers have different information needs depending on their tax situation, tax literacy, and where they are in the process. If we provide every detail at every step, we risk overwhelming many to serve a few.

We aim to provide just enough information on each question screen so ~80% of taxpayers can answer the question accurately and confidently based on the info given. For the other 20% who have more niche tax situations or want to understand intricacies, there's a path to a little more, then a little more.

Use progressive disclosure to focus attention on the current task and reduce confusion. Additional information or tasks can then unfold or a path to more detailed information provided when needed.

It can be helpful to think of this in terms of a:

• Bite = "just enough" information to clarify and help taxpayers act
• Snack = a bit more information to cover more complex needs
• Meal = full plate of information or access to a service that can provide one-on-one support

✓ Use language that gets to the point most directly

This often means focusing on what details are true, not the opposite. Asking/stating things in the negative can require extra brain power or feel like a double negative - especially when paired with yes/no answer options.

Meh 😑	Good 😀
A resident is someone... who does not intend to live there temporarily	A resident is someone...who intends to live there permanently

✓ For complex topics, break it down and explain

Be aware that tricky questions can come off as “trick questions” and erode trust or cause confusion.

Example: This question pair “Could someone claim you as a dependent?” and “Is someone claiming you as a dependent?” risk being misunderstood as trick questions.

Research insights for this decision

Research insight related to this content decision: If helpful to the taxpayer, consider a pattern of "slowing down" users more by breaking a question down into more questions. Also, any features that shift the burden of data entry from the taxpayer and put it on Direct File will help alleviate the cognitive burden of filing taxes. These features could include pre-filing, document scanning (Optical Character Recognition), decoding more technical questions into real-life situations, etc.

Why: User research S06 End to End Observation Federal + State Taxes Study General Public found many people breezed over questions they didn't necessarily understand (e.g., IP PIN, digital assets, fields missing from W-2s and 1099-INTs) and recoiled from investigating further or getting support. When inquired, there seemed to be an attitude of "if I don't understand something, it doesn't apply to me," paired with a certain level of exhaustion for going through the process.

Research insight related to this content decision: Iterating and having clearer content to explain the differences of deductions and credits, as well as having assertive language about what is a better fit for the taxpayers' filing situation helps to do the work for the taxpayer.

Why: User research Deductions and Credits found that the complexity of tax topics like deductions and credits were really hard for taxpayers to understand fully their differences and how they could impact the taxpayers' taxes. Clearly describing what Direct File does and doesn't support can help taxpayers understand if Direct File is the best filing method for their situation.

✓ Explain basic tax concepts

Don’t assume taxpayers know the basics. Define even the most simple term (e.g., standard vs. itemized deductions, filing status).

✓ Provide context to help make decisions

• When taxpayers have a choice to make, provide context or details to help them make the best decision.
• Explain the pros and cons of making certain choices.
• Provide supplemental guidance for choices “answer yes if…”
• When a question is especially complex, repeat key details in the answer selection.

✓ Show the math.

When displaying the outcome of any calculation, explain in human terms how we got that number. This will provide transparency, give taxpayers the chance to double check the work, build trust, raise tax literacy, and build confidence.

Meh 😑	Good 😀
You owe $1000	We started with your total income [value]. Then we subtracted your deductions [value] to get your Adjusted Gross Income (AGI) [value]...

Research insights for this decision

Research insight related to this content decision: For screens related to credits and deductions, it's helpful to explain the math -- for example, to describe what each credit means.

Why: User research S06 End to End Observation Federal + State Taxes Study General Public found that people appreciated reviewing the math screens' breakdown, even if they had questions about how the calculations were done.

✓ Don't make people do unnecessary math.

• When precise answers are needed, include helpful details that spell out specifics.
• When communicating ratios, put into terms that are easy to see yourself in. This sometimes means avoiding fractions or percentages.

Meh 😑	Good 😀
Did Maria live with you more than half the year during 2022?	How many months did Maria live with you in 2023? All year More than 6 months (183 days) but less than a year 6 months or less (182 days or less)
About 90% people take the standard deduction when filing their federal taxes.

Research insights for this decision

Research insight related to this content decision: Overwhelming a user with information can make it hard for them to understand what they need to know for their specific situation. Doing the math for them can help them better understand what they need to know at different points of the experience.

Why: User research S13 Touchpoints Free Text Synthesis Survey Research found that taxpayers expressed that they linked that the system did the calculations for them.

✓ When a conditional is involved, lead with the "if" statement

This helps taxpayers first assess if the scenario applies to them and then receive the relevant information.

Meh 😑	Good 😀
Someone can claim you as a dependent on their return if you lived with them most of the year.	If you lived most of the year with a family member who paid for most of your expenses, they could claim you as a dependent on their return.
Were you legally blind in 2022?	In 2022, were you legally blind?

✓ Find ways to minimize discomfort with sensitive questions

Some taxpayers may find it scary or uncomfortable to give certain kinds of data (SSN, information about citizenship status).

• Only ask these questions at the point where they're really needed — especially when other info might eliminate the need to ask the sensitive question.
• Use a snack to explain why the sensitive question is being asked or what we'll do with that information.
• Group sensitive questions with non-sensitive questions if the outcome for each is the same. Example: Ask about citizenship alongside other disqualifying statuses that are less sensitive [need more concrete example here]
• But sometimes it's better to be direct and avoid figurative language, even if it's uncomfortable.

Meh 😑	Good 😀
What year did your spouse pass away?	What year did your spouse die?

✓ Use future-friendly language

When it doesn’t add value, avoid language that we will need to update as policies evolve or that are tied to a specific event.

✓ Help taxpayers identify and resolve issues

Error and reject messages should be plain language, action-oriented (e.g., steps needed to fix the problem), and should never make taxpayers feel like it was their fault.

✓ Prevent dead-ends

Direct File doesn’t initially serve every taxpayer since it’s being built in phases over multiple years. When a taxpayer hits a point where they learn they aren’t eligible or have an unresolvable problem, it shouldn’t feel like a dead end.

We do this by providing a helpful off-ramp to other tax filing options or customer support services.

Research insights for this decision

Research insight related to this content decision: Alternative paths may allow taxpayers to resolve situations that they were earlier unaware of when first preparing their tax return. In some cases, that may be a knockout, and in other cases it's important to have editing capability and ways to resolve rejections.

Why: User research S07 Research: E2E Observation Federal Only Taxes Study General Public found that a participant who filed taxes for the first time in his life received a rejection code that he didn't understand. The person submitted using Direct File 3-4 days before the tax deadline and thought the Customer Support lines weren't available, so he searched online and found the rejection code referred to being claimed as a dependent by another taxpayer. He asked and confirmed that his parent had claimed him. He then went back into Direct File, fixed his responses, resubmitted and his tax return was accepted.

✓ Do not include PII in link text, button text, meta page titles, or accordion headers

Google Analytics will collect this data, so PII should not be included.

• Do not include PII in link text
  • This is the text that you would click on, so we can't have a link that says "Add Mary's IP PIN."
• Do not include PII in button text
• Do not include PII in meta page titles
  • Meta page titles appear in the browser window. They're not the H1 header.
• Do not include PII in accordion headers
  • GA event tracking includes the accordion header
• You can use PII (like "firstname" in data view sub-sub-section headings, but you'll need to indicate to engineering how to remove that PII in any errors or alerts that reference that sub-sub-section in a jumplink. (more in data view documentation)

✓ Use brand names sparingly

We don't often use brand names but sometimes it can be useful when taxpayers are more familiar with brands than their category or they need the extra context to understand.

Chief Counsel will always need to review the content.

• Company names should be used sparingly and only where content could adversely affect a user's experience. User research should inform this choice.

Meh 😑	Good 😀
You can use Direct File if you use an online peer-to-peer payment service...	You can use Direct File if you use an online peer-to-peer payment service such as Venmo, Paypal, or Zelle..

Research insights for this decision

Research insight for this content decision: When taxpayers' are not as familiar with term or phrase in terms of their tax return, it can be clearer to give examples or make the explanations more concrete by stating specific company names.

Why: User research studies (Box 14 and Income Bits Research Brief) uncovered that in certain places in the Direct File tool or Customer Support that people were looking for specific words like names of companies in order to understand terms like "digital assets." When those words weren't there, the users sometimes misinterpreted the content and didn't answer the study's question correctly easily. Users asked specifically about if those companies, demonstrating a mental model that associates those terms with companies.

✓ Use bold to signal answer selections

When referencing an answer selection option, put it in bold text with no quotation marks. Example "Because you answered that you are Single..."

Voice and Tone Guidelines

• Aim for “business casual” — direct, authoritative, and friendly but not trying to be their buddy. Taxpayers don’t want taxes to be fun, they just want to get the task done. We don’t write copy to be entertaining or use overly familiar language. Keep in mind some taxpayers may have gone through serious life events during the tax year (e.g., deaths in the family, divorce).
• Be authoritative and direct yet friendly, empathetic, trustworthy, and helpful.
• Conversational — write like you talk.
• Use present tense.
• Use pronouns with intention. Address the taxpayer as "you" and refer to the software/gov as "we/us".
• Use contractions in most cases. Exceptions can be made if we need to emphasize something.
• Avoid exclamation points.
• Be specific, when possible.
• For Spanish: Use the informal voice (tú)

Research insight related to this content decision: Users found Direct File's straightforward tone allows users to concentrate on the task at hand.

Why: User research S13 Touchpoints Free Text Synthesis Survey Research found Direct File to be simple and easy to use. They appreciated its straightforward tone. Research insight related to this content decision: Sometimes using more words will boost a user's confidence that they are making a correct selection for their tax situation. For example, instead of only saying "No" as an answer option when asking about specific codes for Box 14 on a Form W-2, instead say "No, but box 14 has different code(s)."

Why: User research Box 14 and Income Bits found that having the answer option phrased with specificity ("No, but I do have something else in Box 14" as opposed to only saying "No") increased taxpayer confidence that they were selecting the more accurate answer for their situation.

Voice & Tone for Error messages

• Use non-blaming language (Use "Your login and password don't match" instead of "You have entered an incorrect login or password"). Use "Your device isn’t online" instead of "You aren't online."
• Focus on how to fix the problem rather than explain what went wrong.
• Taxpayers should understand what buttons will do by reading their labels (Example: Do you want to remove [X]?)
• Use “Are you sure” selectively when getting it wrong would cause issues for taxpayers.

Research insight related to this content decision: Use error alerts as assertions.

Why: User research S13 Touchpoints Free Text Synthesis Survey Research found that participants used the alerts as helpful signposts.

How to deliver "Bad news"

• Have empathy: acknowledge that the bad news evokes feelings.
• Make space for reaction / understand that negative emotional responses can be distracting or derailing to a task.
  • Example: “We appreciate that you might have been expecting a [different outcome]. Here are some things to check/confirm. We can also help you find other resources/deductions/techniques to help you prepare for [this outcome]."
• Provide facts.
  • Example: “We recognize that nobody likes to [owe more money] on their taxes. Here is why [this outcome] has occurred: <FACT 1>, <FACT 2>."
• Offer context and resolution or actionable paths forward.
  • Example: “We appreciate that you might have been expecting a [different outcome]. Here are some things to check/confirm. We can also help you find other resources/deductions/techniques to help you prepare for this [outcome]."
  • Example: “Nothing on your taxes is final until you file your return. If you make adjustments, it could impact your refund or return. Here are [some resources] to learn why [this outcome] has occurred.”
  • Example (if this kind of service is available): “We offer live assistance to help you learn more about [scenario].”

Research insight related to this content decision: Explain clearly to users the context about why they can't move forward and any actions that they can take. Being upfront is clearer and kinder than being vague or non-assertive.

Why: User research F02 Suggestion box comments IRS employees found that taxpayers are willing to accept outcomes if the reasons are explained in a way that they understand.

Avoid

• Avoid using filler words like “unfortunately,” “please,” and “sorry.” These words don’t convey meaning and may distract from the messaging’s intent.
• Don't lead with the word “unfortunately,” because it adds a negative bias to the information that follows.
• When explaining an error or an outcome, don’t use the word “sorry.” Saying “sorry” can make an error or outcome seem more severe than it actually is.
• When asking for information, avoid the word “please.” Saying “please” can undermine the authority or impact of the messaging or lead people to think that required fields are optional.
• Don't use phrases like “that’s just tax policy” or “this is the law.”
• Don't miss opportunities to provide productive next steps, paths forward to their goal.
• Don't miss opportunities to put a "negative" in context. For example, remind taxpayers that [an interim negative outcome] is only for one step in the process, and that other steps may impact their outcome.

Spanish-specific guidelines

Direct File will be translated into Spanish. All content style guides for English apply to Spanish, in addition to the IRS Spanish Style Guide (PDF).

Other Spanish-specific guidelines include:

• Use the informal voice (tú)
• Use alpha characters to denote month (Ex.: 8 sept 2023) which eliminates any possible confusion that can be introduced by using numbers only in date formats. If numbers only must be used, ALWAYS show (MM/DD/YYY) in the entry fields (or MM/DD/AAAA for an SP version) to address any possible transpositions
• Use simple, short translations, particularly for call to action buttons and headings
• Use Spanish URLs for linked pages that have a Spanish version of the site.

For Spanish Translation Glossary see Spanish Glossary: DF_Glossary_and_TM-2-19-25.xlsx

Content Grammar and Mechanics

Abbreviations and acronyms

• First, a primer on acronyms and initialisms:
  • Initialisms are abbreviations where you pronounce each letter of it when you read it (e.g., PTC, IRS).
  • Acronyms are abbreviations that you pronounce as a word (e.g. UNESCO or NATO).
• Spell out uncommon abbreviations in all titles, headers, form labels, and links; otherwise just spell out uncommon abbreviations upon first reference per page
• Commonly recognized acronyms and initialisms (e.g., IRS) do not need to be spelled out.
• Use an article ("the" or "a/an") before initialisms when using them as a noun or modifier.
  • He got the PTC this year.
  • The PTC you received was less than the advanced payments made to lower your health insurance.
  • The IRS provided you with an IP PIN.
• Use "a" before an acronym or initialism that starts with a consonant sound. Use "an" for an acronym or initialism that starts with a vowel sound.
  • A USPS office
  • An IRS letter
  • Did you have an HSA?

Possessive construction

• For nouns that are singular and end in s and need to be made possessive, use 's. For example, IRS's policy, Massachusetts's filing deadline
  • In many cases, you can avoid the possessive construction and use IRS as a descriptive. Both of these are correct examples:
  • The IRS policy statements are in the IRM.
  • The IRS’s policy statements are in the IRM.

Content Elements Guidelines

Guidelines for writing content for different design elements or components in Direct File.

Bites, Snacks, Meals

• Edibles: Bites, snacks, and meals combine text, links, and modals to give the taxpayer additional context and provide hints and additional information for taxpayers. They help answer questions they may have about how to fill out Direct File.
  • Bites are 1-2 sentences of extra context that is always visible on the page. Bites sometimes live with a link to even more information in a snack or meal. Bites should generally come after the label, before the input in a form field, so taxpayers (especially those using screen readers) will be sure to see it
  • Snacks are medium to long-form content blocks that appear in modals, giving taxpayers more information than they would get in a bite, but less than a "meal" or fully external website.
  • In a snack, we can link to:
    • External websites (i.e. meals)
  • In a snack, we can't link to:
    • Other snacks
    • Other screens within Direct File
  • Meals are links to external websites that provide more information or context taxpayers might need that won't fit into a bite or modal.
• Note, if you have a use case where you need to send a taxpayer back to a previous screen to check something or make an edit then that's done with the alert and error system.
• Bites, snacks, and meals should be placed so that the flow of information is coherent and consistent. Generally, place bites, snacks, and meals after the text it supports, but before the choice or form field it supports.

Research insight for this content decision: Links for snacks should always be consistent in their locations and above (not below) input fields.

Why: A user research study (S02 Usability Testing: "You and Your Household" Shared Custody) showed that placing the links in different locations, such as after the input fields, made many users think these were additional questions.

Body copy

• Avoid using "directional" copy, like "Enter your W-2 information in the fields below..." or "See the instructions above...". Directional copy can feel complex if you're using a screen reader to navigate a page.
• When body copy refers to an answer option, use bold text without quotation marks for a suggested selection. Ex., "Answer No if they can't take care of their hygiene or nutritional needs, or require the full-time attention of another person."

Captions and alt text

• Write meaningful text alternative for images to give to developers.

Research insight related to this content decision: Make table titles descriptive and unique from table content.

Why: User research S08 Assistive Tech E2E Observation General Public found that on math screen tables, table titles, and content may be repetitive of one another.

Data View Content

Guidelines on how to write headings, questions, and answer content in data views so that we can take a consistent approach across Direct File. In general, the guiding principle is to preserve all the meaning and context of the original question and answer.

Quick terminology: Data views use terms from our information architecture. You can read more about these terms in the design system wiki, but here's a quick example:

• Section: You and your family
  • Subsection: About You
    • Sub-sub-section: Your basic information
      • Question: Name

How to write sub-section headings

• The sub-section heading is the name of the data view and sits at the top of the screen, uses an H1 heading style, and sentence case.
• The global data view design pattern includes the word “Review:” before the sub-section name e.g. “Review: About you” and is followed by one line of text: “Review your answers and edit if needed.”
• The sub-section name corresponds to the appropriate sub-section within Direct File.
• To reduce visual noise and keep data views easy to read, avoid using abbreviations in sub-section headings.
• Abbreviations can be introduced in sub-sub-section headings or in questions. Once introduced, an abbreviation can be used in all subsequent headings and questions.

How to write the sub-sub-section headings

• Data views are organized into sub-sub-sections or groupings of related questions that follow the order or flow of the question screens.
• Sub-sub-sections headings should be as concise as possible. Four words or fewer is ideal.
• Sub-sub-section headings use H2 heading style and sentence case.
• You can use dynamic text such as "FirstName" in the sub-sub-section headings.
• When MFJ spouses may have different sets of answers to a run of questions, the data view should have a different sub-sub-section for each spouse. For example, the HSA’s data view includes: “Taxpayer1’s coverage and contributions” and “Taxpayer2’s coverage and contributions”
• In the combined credits data view the name of each credit shows in an H2 heading style before the first sub-sub-section for that credit (which shows in an H3 heading style). To reduce visual noise and keep data views easy to read, the H2 heading for the credit name should not include abbreviations like “PTC” or “EITC”
• At the beginning of each sub-sub-section, design should indicate to engineering which screen the "edit" button should point the taxpayer to. Try to point taxpayers to the first question in a run, not to an informational or breather screen.
• At the end of each sub-sub-section, design should indicate to engineering which screen is the "last" screen in the data view sub-section.
• Abbreviations can be introduced in sub-sub-section headings or in questions. Once introduced, the abbreviation can be used for all subsequent headings and questions on the data view.
• A note about using "FirstName" or other Personally Identifying Information (PII) in sub-sub-sections headings:
  • The Direct File error system currently uses alerts with jump links that send the user to the sub-sub-section or collection hub item where an incomplete or error is.
  • If you use any Personal Identifying Information (PII) such as "FirstName" in an sub-sub-section heading you'll need to indicate to engineering how to remove that PII when referencing the sub-sub-section in alert jumplinks.
  • For example, if the sub-sub-section is <FirstName>'s basic information, in the errors and alerts, you'd want to remove the PII from the jumplink and just have it say "Basic information"

How to write questions and answers in data views

• For most questions and answers, write out the full-text of both the question and answer word-for-word in data the views. Why? Our hypotheses:
  • Improves usability and reduces cognitive load for the taxpayer who may be navigating between data views and screens.
  • Lighter lift for design and engineering - as we won’t have to try and rewrite or transpose tricky questions.
• If there's bold text in the original question or answer, do not include the bold text in the data view.
• There are question variations when you'll need to adjust the question text or use statements instead of questions in the data views. More details on those variations outlined below.

When to write statement-style questions in data views

• For screens that use statement formats, for example: “Enter your date of birth,” you can use the equivalent of a field label e.g. “Date of birth” in the data view.
• If a screen uses a statement format, but there’s no field label on the screen (this sometimes happens with radio buttons) use your best judgement to write the equivalent of a field label in the data view.
• When writing statements in the data view do not include any end punctuation or periods

How to write certification-style questions in data views

• Certification style questions ask the taxpayer to certify that one or more statements are true.
• When writing these questions in a data view, stay as close as possible to the original question by using this formula: "Do you certify the following statements are true: Input the statements here after the colon and end with a question mark?"

How to write compound questions in data views

• Compound questions are when one question builds from or refers back to the previous question.
• In a data view if these questions will appear together in one sub-sub-section, you can remove the referential first sentence "You said . . " and include only the question. Example screens: worksheet-a-check-1 and worksheet-a-check-2

Data view guidelines from the Data imports design team

• Display skipped box content on the data views. In the manual entry W-2 data view we don't show this info because it isn't an input but in the data import flow we're presenting the data view to get taxpayers to review the information in Direct File against their Form W-2 so it's important to add this context during review on the data view. Not live yet, but will be relevant to "Skipped box d" on W-2 imports and 1099-INTs.
• For all W-2 data views, we updated the labels for basic information and employer information to lead with "box x" to make it easier for taxpayers to reference their Form W-2s when reviewing information
• For imported W-2's there's a remove W-2 dialog that varies from the generic remove collection since it mentions being unable to import again
• For Imported W-2's there are different buttons at the bottom. We have logic for where the buttons take you depending where you are in the flow:
  • If you just imported a W-2
    • "Review next W-2" if you imported more than one W-2 and have more W-2s to review.
    • "Continue" if you imported only one W-2 or if you're reviewing your last W-2 if more than one were imported.
  • If you finish importing the W-2s and revisit the data view from the Jobs collection page - then follow the existing data view button logic.

Dates

For Spanish: Use alpha characters to denote month (Ex.: 8 sept 2023) which eliminates any possible confusion that can be introduced by using numbers only in date formats. If numbers only must be used, ALWAYS show (MM/DD/YYY) in the entry fields (or MM/DD/AAAA for an SP version) to address any possible transpositions.

Errors and alerts

Field Validation Errors

A taxpayer sees a field validation error when they enter something incorrectly and need to fix it. There are a lot of fields in Direct File (136, to be exact) and 75 unique fields that can help or hinder a taxpayer. Follow these tips to give the most useful information when they need it the most:

• Brevity is essential. Remove words like "please", "you," "must", "sorry", and "we currently don’t support."
• Lead with an action (verb). Instead of “Must have only English letters, numbers, hyphens, or slash,” we can just say “Enter English letters, numbers, hyphens or slashes."
• Use digits instead of full words. "Enter 2 digits after the decimal." instead of "Enter two digits after the decimal."

Tax return alerts (aka, errors and warnings)

In Direct File, we have tax return alerts that we call errors and warnings.

• Errors: Force taxpayers to fix an issue before they submit
• Warnings: Provide a speedbump for taxpayers to consider their answers before they submit.

General writing and style guidelines for errors and warnings

• It's tempting to describe a problem on a screen with directional copy, or using the words "above" or "below" to help a taxpayer locate and fix a problem. Avoid using directional copy in errors, except for in rejection flows, where we've made an exception.
• Always bold the title of an error or warning
• Try to make errors and warnings feel actionable for taxpayers. Using a verb early on, like fix, review, or update, can make it clear that taxpayers need to take action to have the best outcome.

Template for writing errors or warnings

If you're writing an error or warning message for the first time, try following this basic formula:

1. Issue summary: one sentence summary of what the taxpayer needs to review or fix
2. Explanation: describe what the taxpayer did to trigger the alert or what's wrong
3. Resolution: explain what the taxpayer needs to do to fix the issue

Examples of Conversational Questions

“Did Kaylee live with you for over 6 months of the year?”

Form elements

Unexpected behavior

When we're asking something that doesn't fit taxpayers mental model, address the difference directly. For example DF'23 wasn't able to look up taxpayer's last year SS PIN but taxpayers expected it to alert them if they entered the wrong number. Stating clearly that it will not automatically check reduced the number of related rejects by ~14%

Response options (radio buttons)

• Capitalize the first word of response option.
• Do not use end punctuation for response options. If you have a situation that really demands end punctuation for a list item, it's ok to break this rule but be sure to break it consistently within that page.
• For drop-down menus that need to have an option for a blank box (such as Form 1099-G), use the following patterns:
  • Bite language: “If a box is blank on the [form], select Box is blank."
  • Drop-down should be:

- Select -
Box is blank
[Other options in alphabetical order]

General text

In general, content should be styled consistently. Unless otherwise noted, all page elements should follow these basic styles.

• Use sentence case (capitalize only the first word).
• Avoid center aligning text.
• Use serial commas (a.k.a., Oxford comma).
• It's ok to use an em dash when appropriate. Put a space before — and — after. (note: an em dash "—" is longer than the standard dash "-").
• If you have a complete sentence, use punctuation at the end. If you are just listing items or a topic, don't use punctuation at the end. For example, a heading that says "Submitting paperwork" doesn't need punctuation but "How to submit your paperwork." would use punctuation at the end.
• Periods and commas always go within single and double quotation marks.
• It's ok to end a sentence with a preposition.
• Smallest size should be 16pt or equivalent.
• Always have sufficient color contrast.

Headings

• Headings should be descriptive, consistent, and properly nested
• Use headings to give structure to pages, especially if there's a lot of content. Nest accordingly as you would if you mapped the contents of the page as an outline (H1-H4)
• Don't use colons at the end of the heading
• Don't use links in a heading that's used to structure content

Tip: if you were only able to see the headings on your page, could you easily find your way to key pieces of information?

Headings for form questions

• Put tasks in the form of a question when there are discrete question-based tasks. Ex. "In 2022, were you legally blind?"
• Put tasks in the form of a statement when there are multiple fields to be entered on the same screen. Ex. a page that asks you to fill in your address, email, and date of birth might have a heading like "Let's start with some basic information about you."

Research insight related to this content decision: Add context to headers on data views for folks using screen readers.

Why: User research S08 Assistive Tech E2E Observation General Public found that headers and content that don't signal to screen reader users the purpose of the screen (reviewing information inputted in the section instead of inputting new information) will slow down the screen reader user's navigation and they may have to review the page more than once to understand the purpose of the page and that they’re not missing anything.

Helper text

• Use a "Why do we ask?" link/button when asking questions that could feel intrusive to taxpayers or ones that touch on potentially sensitive topics. Explain why the information is relevant to their goal, why it has been included in the set of questions. E.g. "[Question about Marital Status]? Why do we ask?"
• Use a "How do I know?" link/button when asking questions where taxpayers could benefit from some help answering. E.g. "Do you have an IP PIN? How do I know?"
• Highlight/link/etc. definitions to tax and technical terms where they appear in text. "It looks like Johnny is your dependent. Next, we'll ask about Sally..."
• For Spanish: Keep terms that might be confusing in English or include in parenthesis for clarity. For example, "casilla (box)" to clarify where to look on a form.

Research insight related to this content decision: People who use both English and Spanish may be not as familiar with certain technical terms in Spanish but are more familiar with them in English.

Why: User research found that participants who were more comfortable with English technical terms didn't understand "casilla." They mistakenly thought it referred to a previous question vs. (box 15) on their Form W-2.

• Use “snack” links with summary explanations of larger topics. E.g. "You can claim Johnny for a full year even [in these circumstances]. Learn more about XXXX."
• Keep "snack" content to be generalized information. Personalized information should be directly on-screen.

Research insight related to this content decision: When asked about personal things like about which parent had a higher last year AGI, users became nervous and uncomfortable since they didn't understand at first why we needed that information.

Why: User research S02 Usability Testing: "You and Your Household" Shared Custody found that users get nervous when they see questions that feel personal, but they don't know exactly why that information is being asked.

Intros

• Intros are the first pages within a section of Direct File.
• Do not include language that indicates order, such as "Next, we'll..."

Links

Link behavior

• Links that are inline or part of a block of text (e.g., in a paragraph or within search results) should always use default link behavior of underlined.
• Links that are stand-alone elements (e.g., navigation links) don't need to have the underline except on hover [TBD].
• Links should open in the same window.
• Links that take you away from the domain should use the external link icon.
• Phone numbers should be hot linked on a mobile device but not for desktop.

Link style and content

• Match the link content to the destination content as closely as possible. If the H1 on the destination page is “Chat with customer support,” then the link text should say the exact same thing.
• Punctuate a meal link with a "." period.
• Use "Save and continue" for CTA's on screens where the taxpayer has entered information and "Continue" on informational screens
• Use first person for snack links (using pronouns like "I" and "my")
• Do not include personally identifying information (PII) in link text (it's recorded by Google Analytics)
• Each link on a page should be unique.
• If a PDF has a landing page with more information about it, link there instead of directly to a PDF. Only link directly to a PDF if absolutely necessary.
• Avoid linking to IRS Newsroom pages, as they’re less frequently updated and reviewed than Tax Topics pages. Use instructions and publication links as needed.

Link patterns

• The preferred approach for directing a user to find options for filing their federal taxes is this language and link: Find other ways to file your federal taxes.
  • Note, as of December 2024, the preferred URL to point to is irs.gov/filing/individuals/how-to-file. Use this link going forward, and update the old link if you come across it. Old link: irs.gov/filing/e-file-options
• The preferred way to refer a user to the Customer Support chat feature is this language and link: "If you need assistance, chat with customer support."
  • Note, there may be slight variances due to context. If you need to adjust the language, be sure to still use an anchor link that says "chat with customer support." Avoid saying "click here" or capitalizing "chat." Avoid saying "contact" since that could imply a phone call; "chat" is more precise.
  • For example, "For help, chat with customer support" or "If you aren't sure if your income is supported and you need assistance, chat with customer support."

External (meal) links

Meal links, which send taxpayers outside of Direct File, should be used as a last resort. If you can give taxpayers the information they need in DF, do so instead of sending them to separate windows which can be a bit difficult to navigate between. If you have any questions about what the best page is to link, check with our the IRS online services team.

• What makes a good meal link?
  • It has the most relevant information to the particular circumstance the taxpayer is in. For example, if they want to know about standard deductions, don’t link them to a page about standard and itemized deductions. Link them to information that’s most relevant to what they need to know.
  • It has the most available translations. If two pages are equally relevant but one is available in 2 languages and the other is available in 7, pick the latter.
  • It’s been updated or reviewed in the last 6 months (the date will be at the bottom left or top left of the screen).
  • For pub links, it points you directly to the information on a page, instead of starting you at the top and making you scroll down to find it.

Research insight related to this content decision: Avoid styling destructive actions as plain text links only. Make destructive actions clearer using icons.

Why: User research S06 End to End Observation Federal + State Taxes Study General Public found that on Income data view pages, a few participants were confused by the red "remove" button on top of each Form W-2 and 1099-INT data view page. One almost removed it by mistake when trying to address it thinking it was an error he needed to fix.

Lists

• Lists should be used to help make complex information more digestible.
• Use numbered lists for sequential steps, otherwise, use bullets.
• Capitalize the first word of each bullet.
• Do not use end punctuation for list items. If you have complex information that needs more than one sentence in a bullet, try adding the extra information under the bullet as a full sentence (see example below). If you have a situation that really demands end punctuation for a list item, it's ok to break this rule but be sure to break it consistently within that page.
• Don't use semicolons at the end of any type of list.
• If list content is suggesting action, try starting each with an action verb.
• Be consistent. Start each item in a list with the same language element (verb, noun, adjective).
• Use a colon after text introducing a list, unless it's a header

Outros

• Outros are pages guiding users off of Direct File that include:
  • Important information that, if miss-entered, could trigger issues with the taxpayer's return (especially numbers, which can be easy to mistype)
  • Key information that we want the taxpayer to double check because the information is critical for determining if their tax situation is in scope for the pilot, or if they'll be eligible for benefits down the line
  • 3-5 items (generally)
  • A reminder that people can go back to edit if they spot an issue
  • "Here's a quick summary"
• Do not include language that indicates order, such as "Finished your first section."

Rejections

Rejection resolutions in-app

Use case for this content type: Used when a taxpayer submits a tax return in Direct File and receives a "rejected" status from the IRS. The content includes an error code, which is a unique identifier for the rejection reason and an explanation of how to fix the rejection. This content was developed in parallel with the rejection resolutions for customer support.

Rejection resolution language

• Include "Error code: 0000-00000" at the top
• The first paragraph should explain the error in plain language
  • In the future, we should consider using the PAST tense here e.g. "Your name and SSN don't didn't match IRS records."
• During the filing season, we include a "How to fix the error" subheading that instructs taxpayers on how to fix their error in Direct File
  • In “how to fix," we say "edit your tax return" as an action because it matches the primary button call-to-action on the screen.
  • In "how to fix," we use in-line text links to send the taxpayer directly to a specific screen e.g. “Update your name, SSN, or ITIN.”
• If a rejection explanation becomes longer than 3 paragraphs we’ll add more subheadings for scan-ability
• When a rejection involves a spouse say “joint federal tax return” on the first mention on the rejection explanation screen.
• For a rejection involving a spouse or dependent use <spousefirstname> or <firstname> at least once in each paragraph for context (vs. only using “their”)
• When an MeF business rule says "each"child or dependent it indicates that one or more person has an issue and we say "one or more of your dependents"
  • When writing sentences starting: “One or more dependents" reminder to use plural verbs “have” and “don’t” e.g.: have a name and Social Security number (SSN) that don't match IRS records.

Rejection Resolution Alerts

These alerts follow the general errors and alerts system but there are some guidelines specific to alerts used in this context.

• The bold text at the top of alerts is standard and should be the same system-wide:
  • For a warning (yellow)
    • Review this information before you resubmit your federal tax return
  • For an error (red)
    • Fix this error to resubmit your federal tax return
• In alerts mentioning a spouse or married filing jointly, we just say "federal tax return" NOT “joint federal tax return” to save space and reduce complexity)
• When an alert refers to a field label, answer option, or button in Direct File, we use bold text to indicate that it’s on-screen element and try to match the language and capitalization exactly.
  • If you’re referring to an on-screen element- and the text is longer, e.g. “Yes, I have the IP PIN” it is ok to shorten it to: “Yes” when referring to it.
• You can link to another screen from an alert using natural language and in-line text links.
• If the error involves reviewing or updating two fields in Direct File we came up with this formula for mentioning and linking to the other field:
  • Before resubmitting your tax return, check that <your/their> <field name > is also correct.

URLs

• URLs should be short but descriptive.
• URLS should succinctly reflect the content of the page but they don't necessarily have to match the H1.
• Pages in Spanish should have Spanish URLs.
• Do not include PII in URLs (it's recorded by Google Analytics)

Word choice (A-Z) - English

A list of common terms and phrases in Spanish is available in the DF Spanish Translation Memory.

Adjusted Gross Income (AGI): Use "Adjusted Gross Income (AGI)," not "adjusted gross income (AGI)"

advance payments: For the Premium Tax Credit when talking about advance payments of the credit, on first mention on a screen say "advance payments of the Premium Tax Credit (PTC)". On following mentions shorten to: "advance payments of PTC" (we chose to drop "the" in the shorter version).

• Always "payments" plural.
• Always "advance" and not "advanced" because they aren't smart payments they're just early!
• Avoid using the acronym APTC because the Form 8962 doesn't use the acronym and two acronyms PTC and APTC may increase confusion or cognitive load.

Alaska Permanent Fund Dividend (PFD): Write "Alaska Permanent Fund Dividend" (with this capitalization). For second mentions on screen, you can use "[a/the] PFD." Since it's an initialism, use an indefinite or a definite article, depending on the context. User research has found that Alaskans refer to it as "[a/the] PFD" or "the dividend."

• For Spanish, use "Dividendo del Fondo Permanente de Alaska"

always: Put "always" and "only" in the right place

and: Use "and" instead of an ampersand (&)

carry forward: Say carry forward (not carry over) when referring to dependent care benefits from a prior year that you can use later.

citizen: Avoid using "citizen" as a generic term for people who live in the United States. Use "people in the U.S." or "people living in the United States"

copayment: Use "copayment" instead of "co-payment"

dashboard: Use "dashboard" to refer to the main Direct File app page. For ex., "Go to your Direct File dashboard"

dates: Spell out the names of month with dates for clarity and to avoid misunderstandings. For ex., instead of 4/15/2023, write "April 15, 2023"

• Cultural context: in Puerto Rico, the day is used customarily before the month (so the numeric date of 04/05/2023 would be interpreted as May 4, 2023, rather than April 5, 2023)

deleted: Say "removed," not "deleted." This is based on engineering's guidance since information can be removed from a tax return, but it's not accurate to say it's been deleted

descendant: Use "descendant" as the preferred spelling instead of "descendent"

died: Use "died" instead of "passed away"

Direct File: Spell out "Direct File" in all titles, headers, form labels, and links, as well as upon first use per page

• As appropriate, refer to Direct File as a "service" or "tool," not a "program" or "product"
• In Spanish, don't translate "Direct File"

doctor: Try to use "doctor" instead of "physician" for plain language reasons. [10/22 from Content Crew note, SMEs are checking regs on this for blindness definition snack and if we can use "eye doctor" vs. "ophthalmologists."]

Earned Income Tax Credit (EITC): Use Earned Income Tax Credit (EITC) instead of Earned Income Credit (EIC)

eligible: Say "eligible" or "not eligible." Avoid saying "ineligible," which is not plain as language.

employer-sponsored health coverage: How we refer to a plan that someone got from their job because this is how it's stated in the IRS instructions for PTC.

enrolled: When referring to a health insurance plan, say the person is "enrolled in" the plan. Avoid saying the person is "enrolled on" the plan.

federal tax return: When referring to the tax filing itself, we should use "federal tax return" on the first reference on a screen, then "tax return" thereafter on the screen. This is to avoid confusion between federal and state tax returns

federal taxes: When referring to the act of doing your taxes, we should use "federal taxes" on the first reference on a screen, then "taxes" thereafter on the screen

filing statuses: Capitalize filing status names (for example, Married Filing Jointly, Married Filing Separately, Head of Household) for better readability in different content types. Link to decision log

• When referring to a filing status, say the taxpayer is using it not filing as. For example: "using a filing status of Married Filing Separately and not: "filing as Married Filing Separately."

former spouse: Use "former spouse" in English for language where a taxpayer may have either experienced a divorce or may have had a spouse who died

forms: Capitalize the word “Form” when citing a specific form. Ex., Form 8332

• Use "Form W-2" instead of "W2"
• When referring to multiple copies of a form, write "Forms W-2" or "Forms W-2 and W-3"
• When referring to the parts of a form, write the Form, part, and then line separated by commas. Match the language shown on the form itself. For example: Form 2441, part II, line 2.
• When referring to a form, remember to include the article "a" in front of the form name. For example: "If you received a Form 1095-A . . . "

free: Avoid using the word "free" too much; it can erode trust

Health Savings Account (HSA): Note capitalization. For plural, use Health Savings Accounts (HSAs). When needed, use "an" (not "a") before using HSA in a sentence (for example, "an HSA trustee").

High-Deductible Health Plan (HDHP): Note capitalization. For plural, use High-Deductible Health Plans (HDHPs). When needed, use "an" before HDHP in a sentence (for example, "an HDHP").

Individual Retirement Arrangements (IRAs): On first reference use, Individual Retirement Arrangements (IRAs). Since "A" could be Account or Annuity, the IRS uses "Arrangement" to cover both cases: https://www.irs.gov/retirement-plans/individual-retirement-arrangements-iras

internet: When referring to "the internet" don't treat this as a proper noun and don't capitalize it. Write in lowercase as "internet" or "the internet"

IRS: Primarily use "The IRS" not "Internal Revenue Service," even on first instance

IRS Online Account: Use IRS Online Account when referring to the IRS Online Account service: https://www.irs.gov/payments/your-online-account

kindergarten through grade 12 (K–12): Where possible, use "kindergarten through grade 12 (K–12)" on first reference on a screen for clarity and plain language reasons. Note, K–12 uses an en dash, not a hyphen

look: Avoid using "look," "see," and "view" for referral links to be more inclusive of people who may have visual impairments and may be using screen readers. For example, avoid "For more information, look here [X]." Instead use something like "For more information, review [X]"

Marketplace health plan: The first intro screens for Premium Tax Credit refer to Marketplace insurance as: "a Marketplace health plan that qualifies for the Premium Tax Credit." In later PTC screens, we say: "qualified Marketplace health plan" on the first mention and shorten to: "qualified health plan" for additional mentions**.**

• It's ok to simply say "the plan" on a second mention if it's a second mention in the same sentence: "If there was more than one qualified health plan, review everyone who was enrolled across all of the plans."__
• Sometimes we refer to a "Marketplace health plan" as "Marketplace coverage." This is useful when not talking directly about the plan itself, but about eligibility or payment: "eligible for Marketplace coverage" or "payment for Marketplace coverage."

Medical Savings Account (MSA): Note capitalization. For plural, use Medical Savings Accounts (MSAs). When needed, use "an" (not "a") before using MSA in a sentence (for example, "an MSA").

modified AGI: Use "modified AGI," not "MAGI," based on discussion with General Counsel. On first reference, it's "Modified Adjusted Gross Income (modified AGI)"

may: Use "must," "may," and "should" to denote requirements, options, and recommendations

money: Use "money" instead of "cash" where relevant. IRS uses "cash" in context of what counts as a deductible donation, but we chose "money" because "cash" has a connotation of being paper money

must: Use "must," "may," and "should" to denote requirements, options, and recommendations

not married: Use the term "not married" to apply to taxpayers who are single or widowed to reduce the amount of language logic. (Revisit when to include other filing statuses such as qualifying surviving spouse. Consider using the same or similar terms for filing status as what is used with VITA sites)

numbers: For numbers, use the numerical value (for example, 6-11 months), unless it may lead to confusion within the sentence

only: Put "only" and "always" in the right place

parent: Use "biological or adoptive parent" instead of "legal parent." (Avoid the term "blood parent")

percentage, percent, and %: For instruction text or field labels, use "percentage" or "percent," depending on context. When using numerals or for a numeral input field, use %. For example, "Enter the percentage from box 8." "50%."

please: Avoid using “please” when asking for information. Saying “please” can undermine the authority or impact of the messaging or lead people to think that required fields are optional

Premium Tax Credit - This is an initialism where you pronounce each letter "P" "T" "C." When using PTC as a noun, include the article "the." For example: "He qualified for the Premium Tax Credit this year" or "You qualify for the PTC."

• When talking about advance payments of PTC, on first mention say "advance payments of the Premium Tax Credit (PTC)" and on following mentions shorten to: "advance payments of PTC" (drop "the" in the shorter version).

process: Use the word "process" carefully. At the IRS, "processed" or "processing" refers to the last step, when a tax return is complete and a refund (if any) is issued

• Avoid using the word "processing" to describe the period of time when a tax return is sent from Direct File to Modernized E-file (MeF) because this may be inaccurate

public safety officer: Use this capitalization

Railroad Retirement Board (RRB): Spell out on first use. For language that isn't associated with the official name, use lower-case.

• You told us you have a Form RRB-1099-R to report, which is issued by the U.S. Railroad Retirement Board (RRB). Direct File doesn't yet support railroad retirement payments from the RRB.

relationships: Use these terms for relationship-related content (as they apply or fit within context):

• Your child or their descendant includes your
  • Adopted child (including child lawfully placed with you for legal adoption)
  • Biological child
  • Foster child
  • Stepchild
  • Grandchild (or other descendant of your adopted, biological, foster, or stepchild)
• Your sibling or their descendant includes your
  • Sibling, their child, or their grandchild
  • Half sibling, their child, or their grandchild
  • Stepsibling, their child, or their grandchild
• Your parent, aunt, uncle, grandparent, or great-grandparent includes your
  • Parent
  • Stepparent
  • Grandparent
  • Great-grandparent
  • Parent's sibling (your aunt or uncle)
  • Note: this doesn't include foster parent
• Your in-law includes your
  • Child's spouse
  • Spouse's parent
  • Spouse's sibling
  • Sibling's spouse

removed: Say "removed," not "deleted." This is based on engineering's guidance since information can be removed from a tax return but it's not accurate to say it's been deleted

Saver's Credit: Note the use of an apostrophe in the credit's name. In some cases, where further information on the name of this credit would be helpful for clarity, we can use "Saver's Credit (Retirement Savings Contributions Credit)." Avoid "Saver's Tax Credit" to avoid confusion

second lowest cost silver plan: Use lowercase text when spelling out "second lowest cost silver plan (SLCSP)" on the first mention on a screen because this is how it's shown on Form 1095-A that we're referring to. On second mention, use SLCSP.

see: Avoid using "look," "see," and "view" for referral links to be more inclusive of people who may have visual impairments and may be using screen readers. For example, avoid "For more information, see [X]." Instead use something like "For more information, refer to [X]"

should: Use "must," "may," and "should" to denote requirements, options, and recommendations

sorry: Avoid using “sorry” when explaining an error or an outcome because this word can make the error or outcome seem more severe than it actually is

Social Security number: Use "Social Security number (SSN)" on the first mention on each screen, then abbreviate to "SSN" on future mentions

• Note: The "n" in "number" is lowercase when writing "Social Security number," per the SSA

Social Security card: Use "Social Security card." Note: The "c" in "card" is lowercase, per the SSA

spouse: Use "spouse" instead of "husband" and "wife"

• As soon as we've established that the taxpayer has a spouse and they've added the spouse's name to the tax return, refer to the spouse by "<SpouseFirstName>" or "<SpouseFullName>" instead of "your spouse"
• Where relevant, use "you and <SpouseFirstName>," instead of just "you"
• Use "former spouse" in English for language where a taxpayer may have either experienced a divorce or may have had a spouse who died

state Marketplace: When we refer to state-based exchange or marketplaces we capitalize the word "Marketplace" to follow what IRS.gov and HC.gov do.

surviving spouse: Use “surviving spouse” instead of "widow/widower"

• Make sure any language that follows questions about being a surviving spouse is phrased in an especially neutral way

Taxpayer Identification Number (TIN): Use "Tax Identification Number" instead of "tax identification number." Spell out on first reference

taxpayer: Use "Taxpayer" instead of "Filer." Note: This is based on discussion with General Counsel

unfortunately: Avoid using the word “unfortunately” to explain an outcome or tax situation because it adds a negative bias to the information that follows.

U.S. territories: Use "U.S. territories" instead of "U.S. possessions." Note: This is based on discussion with General Counsel

U.S. resident: Use “U.S. resident” as the preferred term over "resident alien," except for when tax nuance requires the use of “resident alien of the U.S."

view: Avoid using "look," "see," and "view" for referral links to be more inclusive of people who may have visual impairments and may be using screen readers. For example, avoid "For more information, view [X]." Instead use something like "For more information, refer to [X]"

workers' compensation: Use "workers' compensation" instead of "workers compensation."

ZIP Code: Use ZIP Code. Note: "ZIP" and the "C" in "code" are all capitalized

Context around word usage for content designers

Background: This section is intended to share context around certain terms or phrases for content designers to be aware of when designing content for Direct File.

• These terms or phrases may be a bit "slippery" or nuanced, so the aim right now is to formalize some of the year two mental models we've been using related to Direct File and how we've approached some of the word choices as we've expanded tax scope.
• These mental models are based on discussions with SMEs. Writing them down will hopefully help us cross-share this knowledge more easily.
• As with everything in Direct File, we remain flexible. This section will be updated over time and may be moved to a separate page.

Word usage context tips

• Taxpayer Identification Numbers (TINs) context
  • This is an overarching term to cover the different kinds of TINs the IRS uses for administering tax law.
  • There are four main types of TINs that we ask questions about in Direct File:
    • Social Security number (SSN)
    • Employer Identification Number (EIN)
    • Individual Taxpayer Identification Number (ITIN)
    • Adoption Individual Taxpayer Identification Number (ATIN), which is a TIN for pending U.S. adoptions. ATINs are temporary and aren't supposed to be used longer than two years
• Estimated tax payments
  • The IRS uses "overpayment" to refer to when a taxpayer's total payments were more than what federal tax was owed. An overpayment can be taken as a "refund" or be applied (all or in part) to next year's estimated federal taxes.
    • Note: “Total payments” is taken from Form 1040, line 33, and includes refundable credits. This is the preferred term from Chief Counsel (vs. something like “the amount of federal income tax you paid throughout the year”), because it’s more accurate.
  • While Direct File doesn't yet support a taxpayer applying all or part of their overpayment to their next year's estimated taxes (i.e., we don't have that functionality in the Payment section), we do need to ask about that situation as part of the Estimated taxes section so we can calculate their tax return.
  • Use each term carefully within its context:
    • Overpayment: When a taxpayer's total payments were more than what federal tax that was owed
    • Refund: One way a person can take the balance of their overpayment
    • Estimated tax payments: Payments made directly to the IRS (usually on a quarterly basis with deadlines in January, April, June, and September). A taxpayer can also apply an overpayment amount from one tax year to the next year's estimated tax payments
• Retirement income terms context
  • The IRS uses words like "distributions," "contributions," and "rollovers" regarding retirement income-related content (such as with the Form 1099-R flow).
  • We chose to use those terms within Direct File since the publications and forms use those terms. When considering the taxpayer experience of referencing the tax forms or IRS website, it makes sense to align our language consistently across that experience. For example, the Form 1099-R has a box for listing distribution codes.
  • Each term is a distinct type of activity related to what's reported on a Form 1099-R
    • Contribution: Net-new money added to a retirement account
    • Distribution: Money being withdrawn from a retirement account
    • Rollover: Movement of existing money from one retirement account to another where it will continue to sit until it's withdrawn (i.e., made into a distribution)
  • Note, this context is intended to help clarify that these are related concepts but are each distinct. This isn't language used in Direct File and would need to be cleared by CC if used

Content Style Decisions

A list or decision log of items that were discussed by the Content Crew and that we found a solution or pov for.

Style decisions

• Form labels
  • Say: "Form W-2," "Form 1099-G," etc.
  • Not: "W-2 form," "1099-G form," etc.
• When referring to multiple copies of a form, write "Forms W-2" or "Forms W-2 and W-3."
• When referring to the parts of a form, write the Form, part, and then line separated by commas. Match the language shown on the form itself.
  • For example: Form 2441, part II, line 2.
• Do not use end punctuation for response options (or, the copy for a radio button or checkbox).
• Use first person for snack links
• Capitalize filing status names (e.g., Married Filing Jointly, Married Filing Separately, Head of Household) for better readability in different content types (decision log).
• Use "standard deduction," not "Standard Deduction."
• "Snack" content should be generalized (personalized content should be inline content)
• Avoid using a bulleted list when there is only one list item
• Email, not e-mail
• Social Security number, not Social Security Number (IRS style guide)
• "State" is lowercase, unless part of an official name (IRS style guide)
• "Federal" should be lowercase unless it's part of an official name (e.g., "2022 federal tax return checklist," "Federal Tax Identification Number")
• "Federal taxes," not just "taxes" upon first reference per screen. After first reference per screen, "taxes" can be used.
• When mentioning paper filing method, always include the word "federal" e.g. "file your federal tax return by paper" even if it’s the 2nd or 3rd mention of the tax return on the screen.
• Avoid using uncommon acronyms in headers
• Spell out uncommon acronyms once per screen
• In alerts and errors, spell out acronyms on first mention (because the alerts and errors will be the first piece of readable content on the screen)
• Identification, not ID (to protect against confusion with ID.me)
• Avoid using questions as headings when a statement is more concise, or when a pattern of questions has been established
• Avoid unnecessary link text, such as "Click here for more" or "For more, see [link]"
• Link text and headings should stand alone without additional context ("Why can't I change this?" vs "Why can't I change my email?)
• Outros should include:
  • Important information that, if miss-entered, could trigger issues with the taxpayer's return (especially numbers, which can be easy to mistype)
  • Key information that we want the taxpayer to double check because the information is critical for determining if their tax situation is in scope for the pilot, or if they'll be eligible for benefits down the line
  • 3-5 items (generally)
  • A reminder that people can go back to edit if they spot an issue
  • "Here's a quick summary"
• Bites, snacks, and meals should be placed so that the flow of information is coherent. Generally, place bites, snacks, and meals after the content or form field it supports.
• Use "Save and continue" for CTA's on screens where the taxpayer has entered information and "Continue" on informational screens.
• Use a colon after text introducing a list, unless it's a header
• Spell out uncommon acronyms in all titles, headers, form labels, and links; otherwise just spell out uncommon acronyms upon first reference per page
• Commonly recognized acronyms (e.g., IRS) do not need to be spelled out
• As soon as we've established that the taxpayer has a spouse and they've added the spouse's name to the tax return, refer to the spouse by "spousefirstname" or "spousefullname" instead of "your spouse."
• Spell out "Direct File" in all titles, headers, form labels, and links, as well as upon first use per page.
• As appropriate, refer to "Direct File" as a "tool," not a "product."
• Say removed, not deleted
• Where relevant, use "you and your spouse," instead of just "you."
• Use "Adjusted Gross Income (AGI)," not "adjusted gross income (AGI)."
• Use "dashboard" to refer to the main Direct File app page. For ex., "Go to your Direct File dashboard."
• Spell out the names of month with dates for clarity and to avoid misunderstandings. For ex., use , , or April 15, 2023.
  • In Puerto Rico, the day is used customarily before the month (so the numeric date of 04/05/2023 would be interpreted as May 4, 2023, rather than April 5, 2023).
• Use "modified AGI," not "MAGI."
• When referring to "the internet" do not treat this as a proper noun and do not capitalize it. Write in lowercase as: internet or the internet.
• When displaying dollar amounts, use two decimal places to show the cents. e.g. "$400.00"
• Use IRS Online Account when referring to the IRS Online Account service: https://www.irs.gov/payments/your-online-account
• For now, for the Alaska Permanent Dividend Fund, we're using the "Go to Alaska Permanent Fund Dividend list >" as the button label. This may change over time and Forms 1099-MISC may evolve.
• If a big acronym like Earned Income Tax Credit is only mentioned once on a screen or in an alert, we spell it out fully and do NOT show the acronym to save space and reduce complexity.
• Addresses' input fields should use sentence case and have unique field names for people using assistive technology to be able to navigate more easily
• Re: spelled out months to help with clarity, especially for Spanish, and re-upping work from backlog
  • Individual Retirement Arrangements (IRAs): On first reference use, Individual Retirement Arrangements (IRAs). Since "A" could be Account or Annuity, the IRS uses "Arrangement" to cover both cases: https://www.irs.gov/retirement-plans/individual-retirement-arrangements-iras
• doctor: Try to use "doctor" instead of "physician" for plain language reasons. [10/22 from Content Crew note, SMEs are checking regs on this for blindness definition snack and if we can use "eye doctor" vs. "ophthalmologists."]
• The preferred way to refer a user to the Customer Support chat feature is this language and link: "If you need assistance, chat with customer support."
  • Note, there may be slight variances due to context. If you need to adjust the language, be sure to still use an anchor link that says "chat with customer support." Avoid saying "click here" or capitalizing "chat." Avoid saying "contact" since that could imply a phone call; "chat" is more precise.
  • For example, "For help, chat with customer support" or "If you aren't sure if your income is supported and you need assistance, chat with customer support."