Help content

Our help content is anything that helps explain what our users need to know about how to use our products. That might be a quick tip on a screen, an article on the web, or a chatbot conversation. When help is friendly, findable, and accurate, it makes people believe in our products and ultimately stick with us. 

There are two general categories of help content: quick in-line help and longer help articles.

Formatting

Anatomy of a help article 

Every article should have a title, summary, intro, and body (with organized headers). Here are some formatting tips.

Title


Use 8 words max, ideally fewer for Google search relevance.

Don’t punctuate unless it’s a question.

  • Create and file 1099s with QuickBooks Online

Start with an action verb if you can.

  • Creating and filing 1099s with QuickBooks Online

Avoid gerunds (verbs masquerading as nouns ending with -ing).

Don’t use jargon.

Summary

The summary shows just below the title and is ideally 1 sentence, 2 max. You can usually write it by finishing this sentence: By reading this article, a customer should be able to learn _____.

Examples

  • Learn what to do if you can't reconcile your accounts.
Intro


  • Explain why your article matters and what to expect.
  • Be brief. One short paragraph (2-4 sentences), maximum 2. Put other info under headers in the body.
  • Try to position things positively even if describing an issue.
  • Avoid lengthy "notes" or "before you begin" sections that tend to grow with random info over time.

Examples

  • If you can’t pay your entire tax bill right now, don't worry. Here's how you can request a payment plan from the IRS.
Body
  • Use headers to organize everything into actionable or logical sections. A heading should be about one thing, not 5. Tip: Good to include “How to…” in headers for SEO.
  • Don't mix content types. For example, split how-to and troubleshooting info into separate articles.

Other help article elements

Here are some guidelines for common elements of an article, such as lists, steps, and images.

Steps


Keep numbered steps to 2-9 steps per section.

Avoid nested steps.

Be clear about where to start.

Don't include unnecessary steps. Keep them to just what a customer needs to complete the task.

Break into distinct sections under headers to cut down longer lists.

Only use numbered steps for actions that must be sequential. 

Only bold the UI elements people actually select.

Each step should be one action. See How to write about the interface for more info.

Notes, callouts, warnings
  • Highlighted callouts can be distracting from the flow of the article. Use these sparingly.
  • There's often no need to visually call out a note separately or in color. If you must add a note, bold the word Note and use a colon after.
Links


Only link actions and be sure it's clear exactly where the link is taking the customer.

Don't say "Click here."

Link to other articles a customer will definitely need to complete a task or follow up on.

Don’t create long lists of related content to link off to.

Bold and italics
  • Only bold UI elements. Bolding too many things reduces the scanability of an article. 
  • Avoid using italics in help content. The meaning or emphasis it conveys is not always clear.
  • Learn more about bolding, menus, and more in How to write about the interface.
Images, animations, and video

Try to avoid images and animations. They're rarely necessary for comprehension and make it harder to quickly scan over an article. They also get out of date quickly and present accessibility issues if we rely on them to convey too much info. 



Use image, animations, or video only when not doing so would result in truly lengthy or awkward explanations.

Don’t use images to show every screen your steps describe.

If there's an existing support video that covers the same subject as the article, include it in the article intro. This way folks who prefer to learn visually are better served. It can also help people discern if an article is relevant to them. 

Anatomy of a help article 

Every article should have a title, summary, intro, and body (with organized headers). Here are some formatting tips.

Title


Use 8 words max, ideally fewer for Google search relevance.

Don’t punctuate unless it’s a question.

  • Create and file 1099s with QuickBooks Online

Start with an action verb if you can.

  • Creating and filing 1099s with QuickBooks Online

Avoid gerunds (verbs masquerading as nouns ending with -ing).

Don’t use jargon.

Summary

The summary shows just below the title and is ideally 1 sentence, 2 max. You can usually write it by finishing this sentence: By reading this article, a customer should be able to learn _____.

Examples

  • Learn what to do if you can't reconcile your accounts.
Intro


  • Explain why your article matters and what to expect.
  • Be brief. One short paragraph (2-4 sentences), maximum 2. Put other info under headers in the body.
  • Try to position things positively even if describing an issue.
  • Avoid lengthy "notes" or "before you begin" sections that tend to grow with random info over time.

Examples

  • If you can’t pay your entire tax bill right now, don't worry. Here's how you can request a payment plan from the IRS.
Body
  • Use headers to organize everything into actionable or logical sections. A heading should be about one thing, not 5. Tip: Good to include “How to…” in headers for SEO.
  • Don't mix content types. For example, split how-to and troubleshooting info into separate articles.

Other help article elements

Here are some guidelines for common elements of an article, such as lists, steps, and images.

Steps


Keep numbered steps to 2-9 steps per section.

Avoid nested steps.

Be clear about where to start.

Don't include unnecessary steps. Keep them to just what a customer needs to complete the task.

Break into distinct sections under headers to cut down longer lists.

Only use numbered steps for actions that must be sequential. 

Only bold the UI elements people actually select.

Each step should be one action. See How to write about the interface for more info.

Notes, callouts, warnings
  • Highlighted callouts can be distracting from the flow of the article. Use these sparingly.
  • There's often no need to visually call out a note separately or in color. If you must add a note, bold the word Note and use a colon after.
Links


Only link actions and be sure it's clear exactly where the link is taking the customer.

Don't say "Click here."

Link to other articles a customer will definitely need to complete a task or follow up on.

Don’t create long lists of related content to link off to.

Bold and italics
  • Only bold UI elements. Bolding too many things reduces the scanability of an article. 
  • Avoid using italics in help content. The meaning or emphasis it conveys is not always clear.
  • Learn more about bolding, menus, and more in How to write about the interface.
Images, animations, and video

Try to avoid images and animations. They're rarely necessary for comprehension and make it harder to quickly scan over an article. They also get out of date quickly and present accessibility issues if we rely on them to convey too much info. 



Use image, animations, or video only when not doing so would result in truly lengthy or awkward explanations.

Don’t use images to show every screen your steps describe.

If there's an existing support video that covers the same subject as the article, include it in the article intro. This way folks who prefer to learn visually are better served. It can also help people discern if an article is relevant to them. 

Goals for help



Empathy

Get familiar with the customer problem. What does the customer need right now? Be human and offer a touch of reassurance if something might seem daunting. 

Simplicity

Keep the customer moving forward. Don’t overwhelm them with too much information. Don't overemphasize all the steps and complexities. Instead, summarize and get going.

Effectiveness

Organize content so it’s easy to scan and navigate. Make sure Google search is considered as well as PON contexts, and keep topics cross-linked if you think there are related tasks or info.

Focus

Answer the question the article is meant to solve. And organize content around customer needs and language, not internal needs.

Help articles

These are available both online and via the in-product Help menu that's in all our products. The types of help articles we create are concept and feature overviews, topical hubs, setup guides, how-tos, advanced topics and troubleshooting, FAQs, and References  (link lists, legal, or compliance info). We also produce support videos, and host a community forum where QuickBooks customers find and answer questions, and these topics regularly appear in search results.

In-line help content

Planning in-line help content



Use hyperlinks at strategic points throughout the product to give customers access to in-line help in the form of tooltips, guided tours, and/or PONs.

Don't link out to external (non-Intuit) articles, websites, or resources.

Make data-driven decisions whenever possible about where to place help content, what type of help to use, and which info to include.

Link out of the product to internal content (public relations articles, FAQs, support sites, etc.), unless it’s truly the best way to help a customer move forward. In most cases, being taken away from their task is likely to derail and frustrate them.

Make careful choices about when to keep or cut financial jargon. Sometimes we need to keep it and define it to give customers the terminology and understanding they need. Other times, it’s better to cut it.Make data-driven decisions whenever possible about where to place help content, what type of help to use, and which info to include.

Work with the right subject matter experts to make sure your content is correct from an accounting, tax, or technical perspective.

3 types of in-line help content

We use 3 types of in-line help across Intuit products, depending on how long and in-depth the content needs to be.

Tooltips

Tooltips are 2-3 line snippets that give customers quick, contextual info about a specific feature or piece of the experience. Use them to:

Examples

  • Point out a new feature
  • Quickly highlight benefits or entitlements
  • Guide customers through a new experience
  • Explain why we’re collecting certain data
  • Help customers complete a task

Learn more about tooltips on the Tooltips content patterns page.

Guided tours

A guided tour is a sequenced set of tooltips that guides customers step by step at the screen-level. Customers step through the tour by clicking the next and back buttons in a tooltip, or by taking a specific action on the screen. Use them to:

Examples

  • Call out or orient customers to a series of new product features or changes
  • Guide users step by step through a series of actions, tasks, or other multi-step information

Learn more about guided tours on the Tooltips content patterns page.

Point-of-need (PONs)

Point-of-need links, or PONs, are longer, more in-depth answers to questions or concerns we expect customers to have as they interact with a specific screen or topic. You can use them on landing tables, forms, and throughout the product. Use them to:

Examples

  • Explain accounting, financial, or tax concepts and terminology
  • Explain rules or guidelines
  • Answer common questions about what to enter, where to enter it, why we’re asking for certain info, or what to do if you don’t have the info we need
  • Provide lists of information

Keep in mind that PON content lives only within the software and is written to be very contextual to a specific screen or item on the screen. This is different from FAQs or help articles, which are written to be more general and can be accessed outside of the product, on the support site.



  • Tell me more about payroll services
  • Help me calculate my mileage
  • Why don’t I qualify for this credit?
  • Why we’re asking
  • If you’re already enrolled
  • What if none of these apply to me?

Phrase help links in the voice of the customer as statements or questions. Occasionally, we phrase help links as “If” statements.

  • Tell me more about payroll services.
  • Help me calculate my mileage.
  • Why we’re asking.
  • If you’re already enrolled…

Don’t punctuate help links unless they’re in the form of a question or exclamation. And don’t punctuate statements that would normally end with a period.

Start each PON with a short, clear answer that includes the most basic info about the topic. This content usually appears in a call-out box, and should apply to the majority of customers who will see the answer.

To answer more specific or in-depth questions (or speak directly to a smaller segment of customers), add 1 or more expando links below the basic answer.

Tips for creating help content

Do your research 

  • What's out there already? If this is for one product, will info for other products show up in Google or in-product search? Go find out.
  • Customers rarely know exactly what product they have. If you see a ton of related topics in search, it might be time to disambiguate the whole topic.
  • Coordinate with help writers at least one month before any public product launch.

Answer the user's question 

  • Content isn’t just a bunch of questions and answers. Organize your content set by the help content type so that users can find answers to specific questions with a simple Google search.
  • Create action-oriented content. Be directive from the first word in the title. Create sections that are organized around specific actions.

Keep it scannable 

  • Walls of text and long paragraphs make people give up.
  • Customers don't want to know everything about a topic. Get to the point.
  • Follow formatting guidelines built to fit this rule. 

Don’t forget content governance

If you only produce content and don't check how it's doing, it will get stale fast. Put your content strategy hat on every day.

Voice flexes

Our Intuit voice and tone principles apply to all content. Here’s how they flex for Help.  

Don’t leave room for guesswork

Be as specific as possible with accounting concepts and tax law. However, when writing detailed steps, it's OK to say “Enter your info” instead of calling out every field that needs to be filled out on a screen. But it's not OK to generalize a process so much it leaves users guessing. 

Keep it positive

It's easy to tell folks what they can't do. Try to focus on providing assurance and resolution instead. 

Don't sell stuff

Help is about how to understand and use our products. It’s fine to succinctly explain the benefit of a feature. But an article should never just be about why to use a feature, or come across like we're trying to sell something.

Link copied