FAQs - several methods to create them

[#1]

Love them or hate them, FAQs remain a popular format to inform and educate. I am often asked to create or format FAQs. Usually I use the “Table of Contents” method (below) for FAQs on a single page, but we have use cases where we need to retrieve FAQs published on different pages.

Here are several ways to format and list FAQs, from the simple to the complex, using common macros. There's no one "best" way to publish FAQs; it depends on the use case.

• How many FAQs do you have?

• Where do you want them to display (on one page or on multiple pages)?

• Do you want to integrate them into the text flow or call them out separately?

• Do you want the answer to be visible initially, or just the question?

• Do you want FAQs to only be visible one at a time?

• Do you want the text to be browser-searchable on a page?

• Do you want to organize or categorize them some way?

Examples below, illustrated with silly jokes and awful puns.

Expanding text (Confluence)

These work fine especially if there are a limited number of FAQs and you don't want to interrupt the flow of the text with an answer. Text isn’t browser-searchable until it’s expanded. CSS could be used to format the expanding links.

Cloak and Toggle Cloak (ServiceRocket Composition Tabs for Confluence)

These two macros work together and look like Expand but behave differently. There’s an option to choose whether the answer is visible initially or not, and an option to choose if opening one FAQ closes all the others. These can be combined with headings to leverage the TOC method (below).

Panels (Confluence)

A panel produces a nice-looking FAQ. 

Tabs (Adaptavist)

An interesting way to categorize FAQs concisely.

Table of Contents (Confluence)

A Table of Contents is an easy yet powerful implementation and one that most users quickly master once they see it in action and realize there are options for the Table of Contents macro. Format questions with a heading, then customize a TOC macro to show only that level of heading. By using different headings and different TOCs, FAQs can be grouped by topic. CSS can be used to manage the appearance of a heading.

Here is the TOC:

And here are the FAQs in the text.

The TOC method can be combined with other methods:

• Page Properties macro (Confluence) - Format the questions in the Page Properties table with a heading

• Excerpt and Excerpt Include macros (Confluence) - Put the TOC inside a page’s Excerpt, then display it on another page using Excerpt Include. Useful for displaying FAQs located on multiple wiki pages.

• Cloak/Toggle Cloak - Format the toggled text with a heading.

Page properties macro (Confluence)

The Page Properties macro can collect and categorize FAQs from anywhere in a wiki space, if used consistently. Nice-looking FAQs can be horizontal or vertical.

Different Page Properties ID’s and labels can be used to group or categorize FAQs.

A couple advantages of this method:

• The Page Properties Report macro can find FAQs on any page in the wiki if they are using the same Page properties ID parameter

• The Page Properties Report provides a link to the relevant page by default

A couple of cautions for using this method:

• Page Properties IDs and labels must be used correctly

• The Page Properties table must be formatted correctly

• The formatting of the Page Properties Report doesn't offer a lot of flexibility; the page title will always show and will always be listed first.
  
  

Individual pages (Confluence and/or Reporting)

This labor-intensive method offers a great deal of flexibility. One page per question, with each page labeled appropriately, and with the answer inside an Excerpt macro, enables several options. FAQs can be listed with the Content by Label macro, Children Display, Page Tree, or Include Page. Listings could also be designed using ServiceRocket’s Reporting add-on. CSS can be used to manage appearance.

Best practices

Regardless of what method you use, here are a few best practices I’ve learned from experience.

• Avoid overwhelming readers with many, many FAQs in one place. Categorize or chunk their display to keep them readable.

• Keep a consistent format between questions, and format them as questions.

• If the FAQs are used to educate readers about something new, once it isn't new anymore, consider folding the answers into relevant wiki pages.

More ways

I’m sure there are many other ways to generate FAQs including with add-ons. These are the methods currently available in our instance. If you have other examples I would love to hear about your own implementation!

[Samie Kaufman - Your Gal at Gliffy]

Hi Michelle! Great article!

I've always defaulted to the TOC structure, but I'm definitely curious about using the page properties macro to pull answers in. This seems like the most convenient way to address Qs that are truly "frequently asked." ;) 

Also, I loved all your jokes! Sharing them in my team's slack channel now hahah

[Kim Wallace]

Thanks for the great reminder that the Table of Contents Zone can be put to use here!