How do I build a step-by-step troubleshooter that asks questions and leads to a fix?

Before you start

• You need permission to manage the help centre.
• Write your fix articles first. A fix step can link to one.
• The tree is typed in an advanced box, as text in JSON form. Take your time and copy the example below.

Steps

1. Open Stories and choose Troubleshooters. This opens the list of troubleshooters.
2. Choose New.
3. Fill in Title. Optional: Summary and Platform, for example the device or app the problem is about.
4. In the box for the field tree, type your tree. It is marked “advanced”. Use the example below.
5. If the box says "That is not valid JSON, so it was not applied.", check for a missing comma or quote.
6. Put the entry in the right hub section, then publish.

The shape of a tree

A tree has a start and a list of nodes. There are three kinds of node:

• QUESTION has text and 2 to 8 answers. Each answer has a label and a next that names another node.
• FIX has text. It can also have an articleId, the number of one of your published stories, or an https url.
• CONTACT ends the walk at your "Still need help?" panel.

{
  "start": "q1",
  "nodes": [
    { "id": "q1", "kind": "QUESTION", "text": "Do you remember your password?",
      "answers": [ { "label": "Yes", "next": "q2" }, { "label": "No", "next": "f-reset" } ] },
    { "id": "q2", "kind": "QUESTION", "text": "Is two-step sign-in on?",
      "answers": [ { "label": "Yes", "next": "f-code" }, { "label": "No", "next": "c1" } ] },
    { "id": "f-reset", "kind": "FIX", "text": "Reset your password from the sign-in page.", "articleId": 1007 },
    { "id": "f-code", "kind": "FIX", "text": "Check your phone's clock and use a backup code." },
    { "id": "c1", "kind": "CONTACT", "text": "We can help you personally." }
  ]
}

Rules the site checks when you save

• 1 to 50 nodes.
• Node ids use lower-case letters, digits and dashes, up to 40 characters, starting with a letter or digit. Each id is used once.
• A question has 2 to 8 answers, and every answer points to a node that exists.
• Every node can be reached from start.
• The tree can't loop. If an answer leads back to an earlier question, you see: "This troubleshooter loops back to an earlier step. Every path must end with a fix or contact step."
• The tree can be up to 32 KB.

Good to know

• Each published troubleshooter has its own page on your site.
• Insights. Help insights shows Where troubleshooters ended, so you can see which fixes readers reach.
• A fix with an articleId links to the story only while that story is published.

Common problems

• "This troubleshooter loops back to an earlier step." An answer points back. Change its next to a fix or contact node.
• A save error about the tree. The error names fields.tree. A node is missing a part, such as text or a valid next. Compare with the example.

Questions

Related

• Help hubs
• Contact options
• Search suggestions and insights
• Help centre and product docs