FAQs, Forums and Other Support Resources

Self-service support is arguably the most important role of a developer portal. Without proper documentation, API teams will spend countless hours on introduction workshops and other training and support efforts.

In this post we’ll analyze the characteristics of a number of support resources and look at how they involve users to develop information about the problem areas in an API’s use. We’ll list pros and cons for the different resources, look at their place in the site architecture, and finally propose best practices.

Support resources are a documentation format

Even the best documented APIs, that complement their API reference with plenty of onboarding tutorials, also have a wide range of support solutions on their developer portals. Twilio, often praised for the quality of their API documentation, includes a list with support articles on its Portal. The better the portal, the more support solutions available.

On first sight this might seem counterintuitive: on portals with great documentation you would expect less support. This does make sense however if you see support artifacts as a type of API documentation. When writing the docs, it is hard to provide materials that will fulfill all requirements to everybody: sometimes you might overlook a demographic, or find out that some people use different words or mental models to understand your service. When you capture the support interactions with these people, they can become a valuable documentation resource that explains problematic concepts in the customer’s words, improving the documentation and reducing the number of people that need staffed support.

Support types: peer-to-peer support and staffed support

Staffed support

Questions are answered by a support team, and where possible reused as documentation content. Examples:

1. FAQ pages
2. Knowledge Base pages
3. Support pages (email, contact form, live chat)

Peer-to-peer support

Interactions between developers are facilitated and result in community support. Staff might occasionally answer questions, or lend authority to an answer, but most questions are answered by customers or partners. Examples:

4. Community sections / Forums
5. Third party community pages, like GitHub and StackOverflow

1. FAQ pages

“Frequently Asked Questions” or also “Questions” list issues that have been previously addressed in a question-answer format. FAQs are popular help sources, because they are easy to produce. They are however delayed (issues appear online after a answer-evaluate-publish workflow) and incomplete: a lot of FAQ pages have sentences like “Can’t find what you’re looking for?” and CTAs (call-to-action buttons) to ask for support on not yet listed problems.

Developers don’t read, they scan pages and should be able to grasp the content of the FAQ page right away. Some examples of how that could be done:

• Structure FAQs into categories. Longer lists (with more than ten topics) are easier to scan when they are divided into categories.

• List FAQs chronologically or without clear order. This works when the FAQs only include a small number of topics (not more than 5). When used in this way FAQs function as marketing material that helps overcome common objections rather than as documentation.

• Add a search bar, and provide a scannable result list.

In our research, 6 Portals out of 10 provided an FAQ page.

2. Knowledge Base: the upgraded FAQ page

Knowledge Base pages list issues and answered questions, often wrapped in articles. The articles are structured into categories. Developer portals added the following elements to improve the content scannability:

• A table of content

• Visual design elements, like icons

In our research, 4 Portals out of 10 provided a Knowledge Base page.

3. Support pages

Users are invited to send an email, chat live or submit a detailed contact form to the company’s support team.

Every developer portal in our research provided a way to contact their support team.

4. Community section: problem solving among peers

We made the distinction between community portal pages and community sections. A community portal page typically contains links to a number of support pages. A community section involves users in peer-to-peer support interactions on-site. Its page structure is very similar to that of GitHub repositories and StackOverflow pages, but search options, filtering options and terminology might differ. Most on-site community sections will also lack the sophisticated gamification and intrinsic reward systems that make third-party community solutions so successful.

In our research, 3 Portals (Keen IO, Dwolla, DigitalOcean) had a community portal page and 2 Portals (Apigee and Dwolla) a community section. DigitalOcean’s community portal page mainly contained links to tutorials.

5. Third-party community platforms, like GitHub and StackOverflow

7 developer portals provided third-party community platforms. We found links to Twitter, Slack, Facebook and
Google Groups, but GitHub and StackOverflow were by far the most popular. The popularity of third party community platforms is a double-edged sword, they have a lot of content, but that also means that users might need to invest more time to explore the content. Public, third-party community platforms have a number of other less ambiguous advantages:
A lot of potential contributors will already have an account and might have built a reputation on the platform that can be used to moderate their contributions. Developers typically also already have an intuition for the culture, rules, and interface of third-party community platforms.

Choosing support types: support strategies

The 10 companies in our research combined between 2 and 4 support resources. We deducted the following strategies:

• All developer portals provided at least one option to contact a support team.
• FAQ and Knowledge Base pages rarely occurred together. DigitalOcean provided both, but used confusing browser page titles (“Questions and answers” for the FAQs and “Frequently asked questions” for its “Help and Knowledge base”).
• On-site community sections and third-party community platforms had a similar function:
• 4 out of the 10 portals that didn’t have an on-site community section had set up a GitHub and/or StackOverflow project instead.
• Twilio used an “Ask the Community” CTA to link to their StackOverflow page, Dwolla to link to their community section.

Through their support pages, the developer portals exposed information about UX and content architecture. We observed two patterns:

• Scanning and scrolling takes too much time. The articles are not collapsible, a table of content is missing, the used support terminology is confusing.
• Scanning and scrolling takes a minimum of time. Users are able to switch easily between information sources, search functionality works efficiently, community members can interact.

Setting up a support strategy helps to choose the right support systems for your developer portal. An understanding of the following aspects is essential:

• Audience
• Budget
• Maturity of your community

Providing users with peer-to-peer support, like forums or on-site community sections, might not be the best choice for young API companies. Building a community of developers takes time and an empty forum can undermine trust. Forums also need a control mechanism to handle spam and unwanted comments. When you are not 100% sure if you will be able to successfully launch a developer community, it is better to invest in a staffed support instead that later can evolve into a peer-to-peer support service.

Information architecture of support pages

Most of the overview pages (the front pages of developer portals) contain links to FAQ, Knowledge Base and community sections in their header, body and/or footer. CTAs linking to GitHub and StackOverflow pages were regularly implemented on the support subpages. Options to contact the support team occurred on both the overview page and the support subpages.

DigitalOcean categorized its support pages on the marketing site and not on its developer portal. The Mattermark Developer Portal is the “Help Center” of the Mattermark marketing page.

All support options on a single page: the support overview page

A support overview page might help to avoid haphazardly placed links on the Portal that could confuse developers.
In our research, almost half of the reviewed developer portals provided one. We found it is important to:

• Use unambiguous terminology that immediately shows what the support title covers.
• CTAs - on the support subpages that link back to the support overview page. This might help the developer to navigate through the information.

Support labels

There’s not enough consensus in the labeling of support resources to draw conclusions about best practices, so we’ve listed all the labels we found here, and will leave their prioritisation to a follow up research. Apart from “FAQ”, “Frequently Asked Questions”, “Knowledge Base”, Community, “GitHub” and “StackOverflow” we also found:

• Support
• Support overview
• Help center
• Get Help
• Help
• Account (with subcategory support)
• Answers
• Stuck or need help?

on the overview pages, and

• Support centre topics (linking to FAQ a.o.)
• Discussion forum (linking to the on-site community section)
• Questions
• Help and Knowledge base
• Need help?

elsewhere on the Portal.

CTAs to on-site community sections:

• Ask the Community

CTAs to GitHub and/or StackOverflow:

• Visit StackOverflow
• GitHub issues
• Ask the Community

CTAs to contact the company’s support team:

• Talk to support
• Submit a request
• Stuck or need help?
• Get support
• Email us
• Can’t find what you’re looking for? Contact support
• Let us know
• Get in touch
• Direct messaging

Ambiguous names:

• “Resources” referred to Keen IO’s community portal page; Apigee categorized reports, stories, videos, customer stories and webcasts into “resources”.
• “Ask the Community”: a CTA to Dwolla’s community section and to Twilio’s StackOverflow page.

Support page subcomponents

We regularly found:

• Search bars
• CTAs with links to support pages or to contact the support team

Subcomponents that improved UX:

• Table of content (e.g. for Knowledge Base categories in the sidebar)
• Live chat options (via unfoldable icons to open a chat box or via automatic pop-up windows)
• Icons
• Code snippets in articles
• A category with “Popular questions” on the overview page
• A CTA to browse the API reference
• A definition of “Knowledge Base”

“Knowledge Base” was also the main title of the Mashape docs page sidebar, including API references, tutorials and FAQs.

Best practices

Ideally, the support team will collaborate with technical writers to create and maintain documentation and support pages. It is crucial to keep them up-to-date and user-friendly:

• An FAQ or Knowledge Base page can be an advantage, but is not a must. Keep the skimming audience in mind: provide a structure that enables developers to scroll through the content quickly, add the total number of articles per category, insert selection criteria (like top articles, latest articles, all questions, unanswered questions) and reference information (like votes) on community pages.
• Provide an on-site community section where developers can communicate with peers. Make the content easily findable. A company GitHub or StackOverflow account could replace a community section on the Portal itself.
• Organize FAQ pages in such a way that it makes it easy to explore and extract results from them.
• Provide means to contact the support team.
• A support overview page could help the developers to speed up.
• Make support available on the developer portal, not only on the company’s marketing page.
• Make sure the terminology is unambiguous (e.g. a tutorial page is not a community section).
• Combine different support resources.

Developer Portal: Components Series In this series we give a thorough overview of the documentation components used on developer portals.

Read more

_Many thanks to my colleague Kristof Van Tomme for co-authoring._