This page describes a documentation/support model called a Flowq - a FAQ with a flowchart, built from actual questions submitted in a chat room or web forum. A Flowq with no overlaps can theoretically hold up to 46,000 answers without putting readers off.


A Flowq is a technique for reducing the number of repeat questions in a web forum, mailing list or chat room. Some of the key features include:

  • An iterative approach that lets a large team of editors collaborate to provide answers
  • An evidence-driven method for matching questions with answers
  • A complete list of answers to common questions
  • A flowchart to let readers quickly navigate to answers, or to self-triage problems that don't yet have an answer

Because Flowqs are driven mainly by real-world data, a Flowq must be based on the traffic in a specific web forum, mailing list, or chat room. This will be referred to as "the forum" or "your forum" in the remainder of this document.

The Ubuntu Signpost is the original example of a Flowq. This guide is based on experience gained (and mistakes made) creating the signpost.


There are three stages to building a Flowq assembly, initialisation, and organic growth.

During the assembly stage, you'll put a team together and find some initial questions from your forum, or from other forums if you are creating a new forum alongside your Flowq. The purpose of this stage is to give your team a good understanding of the problem space.

During the initialisation stage, you'll create an initial flowchart with initial answers. The purpose of this stage is to create a structure that your Flowq can grow around. You should only add a minimal amount of content at this point.

During the organic growth stage, you'll add questions and answers to the Flowq as users ask them. Unlike the other two stages, this is an open-ended process that will continue for the lifetime of your forum.

Stage 1: Assembly

The first stage in building a Flowq is to get a team of writers together, and find a few questions to get your Flowq started. You need at least 10 questions, and preferably no more than 20. Your questions should be a representative sample of real user questions - you can add all the other questions at the start of stage 3.

A Flowq has to start with a forum where real people get help. This can be a chat room, a web forum, a mailing list, or anything else. How you assemble your Flowq depends on whether you already have a forum to build on.

While starting a new forum

If you are starting a forum at the same time as you start your Flowq, it can be tempting to make up some initial questions. Because Flowqs must be built on real-world questions, you should search online for questions that have been asked in other forums, which you would like to have been asked in your forum. As well as giving you real-world questions, this gives you some ideas about where your target audience hangs out.

Another useful technique when starting a forum is to find real-life questions that you would not like to be asked in your forum. Think about why these questions don't fit, and how they differ from questions that do. As you read more good and bad questions, you should gradually find a pattern for good questions. For example, Signpost questions all fit the pattern “where should I go to talk about my Ubuntu-related issue?”. Questions in a support forum might all fit the pattern “how do I solve my Ubuntu-related problem?”. Once you know the pattern, it's much easier to decide which questions are off-topic for your forum, and therefore off-topic for your Flowq.

If you can't find any real-life examples of questions, you should run your forum for a month or two, then create your Flowq based on your existing forum.

From an existing forum


Advice in this section might not resemble real life experience.
This page is based on the experience of creating a forum from scratch, so the following is guesswork.

When assembling a Flowq for an existing forum, the most important thing is to get the people that provide answers to buy in to the Flowq. No matter how good your documentation, or how hard you work at it, it won't do any good unless other people add their answers. The best way to create buy-in is to talk to people about the plan before you start, ask them for the questions they're most frequently asked, and get some of them to join the Flowq team ready for stage 2.

Stage 2: Initialisation

The second stage in your Flowq is to create an initial structure, and to provide initial answers to your questions. This will involve deciding where your Flowq will be hosted, who can edit it, how it will be formatted, and what your root node will look like.

The root node is the first question and the first answers that users will see when they use your Flowq. There must only be a single root node with at most six answers, in order to hold the attention of those users that need to be lead by the hand. You might want to think over the questions you found in stage 1 before deciding on a root node, but here are some rules that your root node must follow:

  • Must use language that users understand
  • Must speak to users' interests
  • Must not lead to a grand taxonomy of questions

To see why these rules are important, consider a technical support Flowq with a root node like the following:

What sort of problem do you have?

 * hardware problem
 * software problem
 * none of the above

Not all users know the difference between "hardware" and "software" problems. If their CD player keeps switching to a different skin, they might think it's a hardware issue because it's a CD player.

Even if users know the difference between hardware and software, they might not be able to tell what sort of problem they're having. If their CD player keeps dropping songs from a playlist, is that because the CD is scratched, or the program has a bug?

Even if users can work out whether the problem is in hardware or software, many will dismiss it as irrelevant, and skip straight to the forum.

Even if users do spend the time to work out all of the above, editors will get the impression that questions should spell out neat classes of problems that users might have, rather than the messy collections of questions they really want to ask.

A technical support Flowq would be better to use a question like this:

What sort of problem are you having?

 * My computer won't start
 * A program keeps crashing
 * I click on something, and the wrong thing happens
 * I need to do something, but I don't know how
 * None of the above

Although this is messier, it's a more accurate reflection of the types of things that real users think. When a user can empathise with a specific answer, they're more likely to click through, and less likely to skip straight to the forum.

Your Flowq will have to match your team's style and the subject area it covers. You will probably design a fairly hierarchical Flowq, with major topics leading to smaller topics, and with occasional links between siblings. For example, a category of "support" questions and "bug" questions, with links between them when a support issue turns into a bug report. Users won't notice the structure though, so baroque constructions are acceptable, and organic growth will probably lead to a messier structure anyway.

Stage 3: Organic growth

The final stage in your Flowq is to populate it with questions and answers, based on user requests.

When your flowchart starts growing, it can be quite frustrating to see that the questions you're asked don't fit into the neat divisions you've assigned. You should resist the temptation to dismiss these as silly questions, because the purpose of a Flowq is to help people, not to neatly model a problem space. If user questions don't fit neatly into the structure of your flowchart, then your flowchart has a bug. If user questions aren't answered, then your FAQ has a missing question. No matter how beautiful your flowchart is, no matter how ill-formed your users questions are, a Flowq that doesn't answer questions isn't performing its function.

During the organic growth stage, you should treat your Flowq like a script when you provide help. When you follow the Flowq as a script, there are four possible outcomes:

  1. The Flowq leads you straight to the answer, which you give to the user
  2. The Flowq leads you to where the answer should be, but doesn't provide an answer. You should give the user an answer, then add it to the Flowq
  3. The Flowq leads you down one route, when the answer is down another route. You should link from one question in the new route back to the old route (creating an "overlap")
  4. The user's question doesn't fit neatly into the Flowq. You should modify the Flowq to fit the question

This will probably make an awful mess of its neat structure, but that's just because the Flowq is starting to resemble the chaotic mess that is the users' experience, instead of the neat structure your experience.

Treating your Flowq like a script has another benefit: if you make it clear that you're just reading off the screen, then users are more likely to go to the Flowq first, rather than imprinting on you for help with every problem they have.

Flowq nodes

A Flowq is built from branch nodes and action nodes, with a single root node which users start at. When adding content to a Flowq, you need to follow the rules for the node(s) you edit.

Branch nodes

A branch node is a node that asks a user a question. The rules for a branch node are:

  1. There must be at most 6 answers, plus one "none of the above" answer that sends you to the forum
  2. The branch must only use words and phrases that have been used by people whose questions brought you to this point
  3. Answers must try to provoke a "that's me!" response in the reader
  4. Except for the root node, branch nodes must have at least one other branch node leading to it

The node is limited to seven answers because people can only take in 7 things at once. Any more and users will get confused and jump straight to the forum.

Using real-world words and phrases ensures that questions are written in a way that your users understand, so that they're less likely to give up and skip to the forum.

Users are more likely to click through questions if they can empathise with the answers. Aiming to provoke a "that's me!" response will help you find answers that users empathise with and click through.

Editing branch nodes

When you follow a question through a Flowq, and and land at a Flowq node with a missing option, then you should edit the node. The rules for editing a branch node are quite simple:

  1. If your question has less than 6 answers (not including "none of the above"), then add to the node
  2. Otherwise, if the longest route from the root node through this node to an answer node is at most 6 steps, split the node
  3. Otherwise, rebalance the tree until one of the above becomes true

Adding an answer

Adding an answer is the simplest way to edit a branch node: link from the question to another node, which you might need create. If the answer doesn't make sense in relation to the node's question, you might need to make the question more general.

Splitting a node

Splitting a node is slightly more complex than editing it. Splitting a node involves sorting answers into groups (preferably about 3 groups), creating branch nodes for each of the groups, and editing the current node to point to each of the new decision nodes.

Rebalancing the tree

Rebalancing the tree is quite hard. Unless you can rebalance a very small section of the tree, you should consult with the rest of the team before attempting it.

Rebalancing the tree involves looking at all the routes through the Flowq which involve the current node. Any of those nodes could be split, merged, or completely rewritten in order to reduce the number of answers for a given node.

Action nodes

An action node is a node that asks the user to perform some action. Most action nodes wil provide a final answer, but action nodes can also provide intermediate self-help steps, or can explain how to phrase a question for the forum.

  • The rules for action nodes are:
  1. The longest route from the root node to the action node must include no more than 7 nodes, including the action node and the root node
  2. The node must have zero or one nodes leading from it. You must never ask a question in an action node
  3. The action must be based on actual advice given to a reader, which you've confirmed that they understood and followed correctly
  4. The node should have at least one branch node leading to it

  5. If the action node asks the reader to ask a question in the forum, it must ask them to specify the path they took through the Flowq

The longest route is limited to seven nodes because people can only take in 7 things at once. Any more and users will get confused and jump straight to the forum.

Most action nodes are end points in a Flowq, but it is possible for actions to lead to more questions. Follow-up questions are put in separate branch node so that both count towards the limit of seven, and so that another action node can reuse the same branch.

Using real-world advice ensures that actions are described in a way that your users understand, so that they're less likely to give up and skip to the forum.

You should usually only add an action node in response to a user question, because that's the only way to get real-world advice to base the answer on. However, sometimes it's appropriate to add disconnected nodes. For example, you might have stock answers that haven't been asked by users yet. Disconnected action nodes can be tolerated in small numbers, especially in young Flowqs.

If directed to a forum, users should specify their route through the Flowq so that the person handling their problem knows what to edit when they update the Flowq.

Editing action nodes

Editing action nodes is fairly straightforward: If a user reads a node but needs more information, or had a problem, or asked anything else about an action node, then that information should be added to the node.


This section will discuss some of the theoretical issues behind a Flowq.

Knowing the answers warps your view of the questions. When someone comes across a new situation, they try to interpret it using their own personal set of assumptions, prejudices, interests and skills. As they learn more, their view of the issue adapts to resemble the common "expert" view. The "expert" view makes it possible to think about problems in a way that finds solutions, but impossible to think about problems the same way as the people you're helping. The best way for an expert to speak clearly and reliably to non-experts is by inserting as little of their expert language as possible into a conversation.

The original FAQs were attached to newsgroups and mailing lists that ensured all questions really were frequently asked. When FAQs started to be attached to websites with no way to measure frequency, they gradually became NAQLAs: never-asked questions I would like to answer.

People are often tempted to sit down and write lists of common questions. This is a slow and arduous process, which usually creates a NAQLA because they're expert-centric documents based on little evidence about frequency.

People can only take in 7 things at once. Human brains can hold between 5 and 9 concepts in their head at one time. The size of a concept depends on the skill of a brain, but it's reasonable to assume that Flowq readers will treat a single question, or a single answer, as one concept.

No question should ever need to be answered twice. People answering questions are a limited resource, and a question answered twice is a waste of that resource. Once a question has been answered, it should be possible to direct everyone with the same question towards that answer.

Flowq (last edited 2013-12-13 23:31:34 by knome)