We write help articles for a broad range of customer questions and problems. Unlike in-line help (tooltips, guided tours, and point-of-need help, which are specific to where a customer is in the product), help articles provide answers that are more general.

How to write help articles

Goals

  • Empathy:
    Do your research. Get familiar with the customer problem. Immerse yourself in the customer’s experience.
  • Simplicity:
    Present just enough content to keep the customer moving forward. Don’t overwhelm customers with too much information.
  • Design:
    Organize content so that it’s easy to scan and navigate.
  • Focus:
    Answer the question.

Title (H1 heading)

  • Keep it short.
  • Write from the customer’s point of view.
  • Use sentence case.
  • Don’t punctuate a heading or subheading, unless it’s a question or exclamation.
  • Keep search in mind. What words or phrases are customers most likely searching for?
  • Avoid additional formatting (like bold or italics).

Introduction (nugget)

  • Keep it short, usually just 1 or 2 sentences.
  • Focus on what and why what the topic is for, and why it’s important to the customer (customer benefit).
  • If possible, make the intro actionable and answer their top-of-mind question in the first sentence. (Example: If you can’t pay your entire tax bill right now, you can request a payment plan from the IRS.)
  • Be clear and direct when you introduce important next steps. (Examples: Take these steps by April 18 to avoid a penalty; Here’s what you need to do).

Headings and subheadings

  • Use sentence case
  • Keep it short
  • Don’t punctuate except for emphasis or if it’s a question

Steps (numbered list)

  • Use numbered lists to communicate a clear set of sequenced steps.
  • Write at least 3 steps, no more than 10.
  • Punctuate consistently.
  • Capitalize the first word in each sentence and end with a period.
  • Write complete sentences.
  • Use parallel structure.
  • Describe 1 task per step. (Navigating can be combined into 1 step. Eg. Go to the settings menu and click payroll settings.)
  • Make sure all the info they NEED to complete the steps is included.
  • Lead with the why. For example, “To display invoice numbers, do this.”
  • Avoid location, orientation, or directional hints like top left.
  • Consider the goal of your steps. Are you guiding someone through a long, complex process? Or focused on how to do a quick task? Chunk your info accordingly.
  • Make sure each step describes an action and isn’t just an explanation.
  • Don’t stack multiple lists within a single article, if at all possible. This can be visually overwhelming and make scanning difficult.

Bulleted list

  • Use bulleted lists to communicate options, situations, or items that don’t need to appear in a step-by-step sequence.
  • Write at least 3 points and no more than 10.
  • Incomplete sentences are OK.
  • Use parallel structure. If the list is incomplete sentences, all items in the list should be incomplete sentences.
  • Punctuate and capitalize only if complete sentences.
  • Don’t stack multiple lists within a single article, if at all possible. This can be visually overwhelming and make scanning difficult.

Emphasis

  • Use bold to indicate a user interface element the user is acting on.
  • Don’t use bold for emphasis.
  • Don’t use capital letters for emphasis.

Article closing or conclusion

  • Let customers know what’s next. What can they do now that they completed the steps?
  • Are there next steps they can or should take?
  • Offer a bit of reassurance, confirmation that can help the customer feel a sense of accomplishment.
  • A conclusion can be as simple as, “That’s it. Now you can make your sandwich.”

See also/related links

Try not to present such links. They tend to lose or frustrate customers more than help. And they make our products seem too complicated.

Tips, warnings, important info, notes

  • Info that’s critical to understand before beginning a task needs to be at the top of a help article.
    Examples:

    You can’t undo this.
    Make sure you do this before you make this other change.
    This is due on February 20.
    It takes 2 days to process direct deposit payroll.

  • If it’s just a helpful hint, put it with the info it relates to.
  • If it’s a hint on what to do next, put it after your task.
  • If it’s a tip for a step, include it under the step.
  • If it’s a tip for the whole process or before you get started, put it right up front.

Definitions

  • Explain terms in context, rather than separating out a dictionary-style definition.
  • Avoid jargon as much as possible.
  • When you have to define jargon or accounting or tax terms, be clear and direct: State the term first and explain second.

Example

The standard deduction is the portion of your income that is not taxed. You can use it to reduce your tax bill.

Images

  • Use with caution. They need to be updated every time that area of the product changes. Also, we might need localized and translated versions (which also have to be maintained).
  • Enhance step-by-step instructions with brand-appropriate images, only when needed.
  • For navigation, add an image of the relevant product screen to help customers know where they should be in the product.
  • Make sure images are not too detailed.
  • Use brand-appropriate colors if you circle or point to something within an image.
  • Don’t use images that look like ads or marketing campaigns.

Choose vs. go to vs. select

Use “go to” for navigation. Example: Go to the gear or create icon to start an action.

Capitalization: sentence case

  • Capitalize the first word in a UI element (sentence case). Examples: Gear icon, Account & settings, Run payroll.
  • Don’t brand features by capitalizing them.

Navigation

  • Spell navigation out with words (don’t use symbols like > to mean “go to” or “then.”
  • Don’t use directions like “”top right” or “on the left side of your screen.”

Voice and tone in help articles

Help articles should be as concise as possible, without being curt or incomplete. In other words—less is more—but sincerity and accuracy are still key. The goal is to give customers an immediate sense of relief and the facts or steps they need to move forward quickly.

Lean into the Intuit perceptive voice in most help content, including help articles. This means speaking to customers in a sincere, reassuring tone and following these voice principles:

  • Give them closure.
    Find a resolution for every person and every situation. Give them what they need to move forward. If something seems (or is) impossible for the customer to do but still needs to be done—help them figure out what to do.
    Examples:
    If you can’t pay all of the tax you owe, you can request a payment plan from the IRS. Here’s how to get started…
    When you select Talk to a specialist, you’ll be asked to add PLUS benefits first. This is the best and fastest way to get help. If you’ve already tried this and still need help, call us at 800-446-8848.
  • Meet their need instantly.
    Give a direct answer right away. If the question is high-stakes and driven by anxiety, consider meeting their emotional needs first. Ask yourself, what does the customer need right now? Answer that in the first sentence. If details or edge cases are necessary, include them later on in an expando.
    Examples:
    Yes. You can deduct summer camp tuition as child care, if your child attended camp so you could work.
    No. An extension gives you more time to file your taxes, but it doesn’t give you more time to pay your taxes.
  • Be clear.
    Be crystal clear and don’t leave room for guesswork. Be as specific as possible with accounting concepts and tax law. Use language that shows we have a strong point of view. Write detailed and drawn out steps when needed.
    Examples:
    Only U.S. citizens or resident aliens who were out of the country on April 18 can file an extension after the April 18 deadline. They must file their extension by June 15.
  • Simplify.
    Break answers down to the most basic level. Be strict and don’t include info that adds confusion. Consider breaking everything into steps, if possible. Use formatting that makes it easy to consume.

Flex the perceptive, personable voice attributes when you talk to customers about security or privacy.

Don’t use a persuasive (marketing) voice in help content, even if you’re describing offers or features. It can come across as too salesy or insensitive to customers who just need straightforward help.

Empathy and apologies

It’s tempting to say “sorry” when customers hit a roadblock. But too much focus on what’s wrong can reduce their confidence and get in the way of the clear, direct answers they need.

  • Use “sorry” and other apologies sparingly. Save it for times when we really mess up or can’t deliver on a promise (like when a customer loses all their data). If you do use it, make sure it’s authentic—not false, flippant, or condescending. Help them understand, but don’t point the finger.
  • Don’t call out how “scary” or “stressful” something is. This can trigger FUD, even if it wasn’t there to begin with. Use words like these rarely, if at all. Instead, use patient, nonjudgmental know-how to help customers trust in their outcome, get unstuck, and push through.

Formatting and style

Capitalization

Follow the Intuit Design System capitalization guidelines.

Contractions

Use them. They help us have a human conversation with our users: Don’t, can’t, they’re, you’re, it’s, etc.

Don’t use: Do not, cannot, they are, you are, it is, etc.

Expandos

  • Use them to help customers quickly sort through specific or in-depth info.
  • Don’t use them to hide general info that applies to most customers.
  • Write link titles that are easy to scan and in the customer’s own language. They should be specific enough to help customers quickly rule them in or out.
  • Stick to a max of 3-5 per article, if possible.

Examples:
I need a copy of my 2016 return
I need a copy of my 2017 return
I need a copy of an older return

Links

  • Put hyperlinks after or below info you want customers to read. Instead of reading, customers often go straight to hyperlinks and bounce to another page. Keep this in mind—and use hyperlinks strategically to move customers along the right path at the right time.
  • Consider moving hyperlinks to the bottom of the page, if you need them.
  • Use them higher on the page to redirect customers who might be in the wrong place. (Example: If you’re looking for your state refund, see this article instead.)
  • Think of all content you link out to as part of a complete end-to-end help experience. Always check it to be sure it’s accurate, well-written, and provides the info and continuity customers will need after landing on your article.
  • Don’t link out to external (non-Intuit) resources, unless it’s truly the best customer experience. If you do link out, only link to credible government agencies, such as the IRS. (Example: Track your refund with the Where’s my refund tool on the IRS website.)

Scannability

  • Write clear, concise answers that reduce the need to scroll or toggle.
  • Keep critical info above the fold and visible in the mobile screen.
  • Chunk content into mini-paragraphs (2-3 sentences long) instead of larger blocks of text.
  • Use subheads, expandos, and other formatting to break up longer content.
  • Keep in mind that customers scan help articles in this order: Title > Bold headline > Bold verbs > Hyperlinks > Bullet points, if any
  • Don’t overuse bold or italic fonts. This makes content harder to read, not easier. Use bolding only when you reference button labels or specific sections of the product. Avoid italics in most cases.

Examples:
When you’re finished, select Done.
Select Edit to make changes.
We’ll help you enter it under Income & Wages.

Types of help articles

Common topics for help include:

  • Navigation
  • Products and features
  • Offers
  • Tax rules and processes
  • Accounting rules and processes
  • Small business finances
  • Personal finances
  • Customer policies

Sometimes a help article is just about a concept, like deductions or reconciliation. In that type of article, the focus might not be steps, but just explaining what a thing is. Some common concept help articles are for things like accounting methods and tax terms.

How do customers find help articles?

  • Doing a Google search
  • Going directly to the TurboTax, QuickBooks, Mint, or ProConnect support site
  • Selecting the help button after signing in to their product.

    In our online products, this opens the help panel.
    In our mobile apps, this opens the virtual assistant.
    In TurboTax CD/Download, this opens the TurboTax support site (also known as Answer Exchange) in a browser window.