Skip to main content

FAQs

Whether and how to write FAQs depends on what kind of content you’re creating. Specifically, there are different guidelines for technical documentation than for other types of content, such as marketing or technical support.

Technical user documentation​

Don't use FAQ pages in Unity user documentation. FAQ pages aren’t an ideal way to present content for the following reasons:

  • FAQ pages don’t describe the user journey through the product in a logical order according to the tasks the user needs to complete.
  • FAQ pages don’t follow the rule of one topic per page. By covering multiple topics with no clear hierarchy, FAQs make it harder for users to find and use information.
  • FAQs can always be better presented in dedicated topics. If a question is actually frequently asked, then it needs its own documentation.
  • FAQs weaken strong headings by placing meaningless words at the start of a line, where users are most likely to scan for relevant information. Users are less likely to read long questions than short, effective headings that provide the answer.
  • FAQs lead to duplication in search results when information is already documented in its own topic.
  • FAQs rarely come from actual user queries and instead tend to be marketing-oriented or based on imagined user needs.
  • The FAQ format doesn’t scale. As more questions are added, information becomes increasingly difficult to organize and find.

Instead, find a logical way to build information into the structure of the main docs. Determine what kind of information you are documenting and present it in the associated page type:

  • Concept page: Explains an idea, or gives background information or context.
  • Task page: Demonstrates a step-by-step procedure that shows how to achieve a goal.
  • General reference page: Documents the attributes of a specific tool or object.
  • UI reference page: Documents the properties and settings available in a user interface.
  • API reference page: Documents the syntax of and key information about API code elements.

Marketing and technical support documentation​

If you're creating FAQs for product marketing or technical support, then contact Paola Nanquen by email or on Slack for more information.