Create
cancel
Showing results for 
Search instead for 
Did you mean: 
Sign up Log in

Next challenges

Recent achievements

  • Global
  • Personal

Recognition

  • Give kudos
  • Received
  • Given

Leaderboard

  • Global

Trophy case

Kudos (beta program)

Kudos logo

You've been invited into the Kudos (beta program) private group. Chat with others in the program, or give feedback to Atlassian.

View group

It's not the same without you

Join the community to find out what other Atlassian users are discussing, debating and creating.

Atlassian Community Hero Image Collage

FAQs - several methods to create them

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.

image-20200621-005924.png

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).

image-20200621-005959.png

Panels (Confluence)

A panel produces a nice-looking FAQ. 

image-20200621-010024.png

 

Tabs (Adaptavist)

An interesting way to categorize FAQs concisely.

image-20200621-010051.png

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:

image-20200621-010122.png

And here are the FAQs in the text.

image-20200621-010136.png

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.

 

image-20200621-010228.png

image-20200621-010247.png

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

image-20200621-010203.png

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.

image-20200621-010329.png

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!

1 comment

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

Like Michelle Rau likes this

Comment

Log in or Sign up to comment
TAGS
Community showcase
Posted in Feedback & Announcements

Developer Day is next week – check out the agenda!

Hey there, community! Hope everyone is well and safe! ✨ The last few months have been busy – especially with the judging + picking of our Codegeist 2020 winners, the launch of Atlassian Ventures, a...

218 views 1 7
Join discussion

Community Events

Connect with like-minded Atlassian users at free events near you!

Find an event

Connect with like-minded Atlassian users at free events near you!

Unfortunately there are no Community Events near you at the moment.

Host an event

You're one step closer to meeting fellow Atlassian users at your local event. Learn more about Community Events

Events near you