Create Troubleshooting Guide

“This step-by-step training module guides new Authors in creating an interactive troubleshooting guide. Log in to your Yonyx account in another browser tab and follow along with this article as you build a decision tree-based troubleshooting guide. You’ll discover the various features of the Yonyx platform!” You may also choose to schedule time for a hands on authoring workshop.

Step 1 – Create Troubleshooting Guide: Start with the Root Node

Creating a troubleshooting guide starts with the Root Node. This may be the symptom or the call driver that customers frequently need help with. In this example, we will create a troubleshooting guide for customers needing help with “Customer Setup Issues”.

1. From the Gear drop-down, choose “My Guides”
2. Click on “Create Guide”
3. Enter the Title, “Customer Setup Issues”
4. Click “Save & Edit”
5. Enter a brief description of the guide in the body section, “This guide will help you troubleshoot Customer Setup Issues.”
6. Enter the Follow-on Question, “Is the customer able to log in?” Note, we are troubleshooting an imaginary SaaS platform here.
7. Click the Save button, or press the “Enter” key on your Keyboard (with the cursor in the Follow-on question section) to save.

You just edited the Root Guidance Step of your decision tree. Each Guidance Step has three main sections:
– Title – brief one-line summary
– Body – may contain text, images, videos, tables, hyperlinks, and embedded forms.
– Follow-on question – A question (or statement) that may lead to branching.

Step 2 – Add User Responses to Create Branches

Creating a troubleshooting guide involves connecting two types of nodes: Guidance Steps and User Responses. A guidance step provides incremental guidance to the user and includes a follow-on question. User Responses are the possible answers to this question, which create branches in the decision tree.

1. Click on the “Add User Response” button.
2. Type “Yes”
3. Click the Save button, or press the Enter key on your keyboard to save.
4. Click on Add User Response button again.
5. Type “No”
6. Click the Save button, or press the Enter key on your Keyboard to save.

Note, User Responses are answers to the Follow-on question from the preceding Guidance Step. 

Step 3 – Add Guidance Step “Check Caps Lock Key”

Creating a troubleshooting guide mimics an imaginary conversation between a subject matter expert and the user. This conversation can follow multiple pathways across different branches of the decision tree. For example, if the customer cannot log in, they might need to ‘Check the Caps Lock Key.’ Let’s add a guidance step for this scenario.

1. Click on the “No” User Response in Map View.
2. Click on the “Add Guidance Step” button.
3. Type “Check Caps Lock Key” in the Title section.
4. Leave the Body section blank for now. 
5. Type “Is the Caps Lock Key turned on?” in the Follow-on Question section.
6. Add a note to yourself, “Add a picture of the caps lock key here”. The author’s notes are not visible in User View.
7. Click the Save button, or press the Enter key on your keyboard to save.
8. A Guidance Step containing the Author’s notes gets highlighted with a red color around it.

A Guidance Step (represented by a blue box in Map View) may be followed by User Responses (shown as grey boxes in Map View). Each User Response should be linked to a Guidance Step. Orphaned User Responses that aren’t connected to Guidance Steps are removed in User View.

Step 4 – Copy/Paste User Response Nodes – “Yes” and “No”

As you develop the troubleshooting guide, you’ll start to value productivity features like copying and pasting decision tree nodes. Include “Yes” and “No” response options for the question, “Is the Caps Lock key turned on?”

1. Click on the “Yes” User Response in Map View.
2. Click on the “Copy” button.
3. Click on the “No” User Response in Map View.
4. Click on the “Copy” button.
5. Click on the “Check Caps Lock Key” Guidance Step.
6. Click on the “Paste User Response” button.

Step 5 – Add Guidance Step “Turn off Caps Lock Key”

If the Caps Lock Key was on, tell the user to Turn Off the Caps Lock by adding a guidance step.

1. Click on the “Yes” in Map View.
2. Click on the “Add Guidance Step” button.
3. Type “Turn Caps Lock Key Off” in the Title section.
4. Type “Are you able to log in now?” in the Follow-on Question section.
5. Click the “Save” button or press the “Enter” key on your keyboard to save.

Step 6 – Boost Efficiency with Keyboard Shortcuts

Creating a troubleshooting guide can be time-consuming. It’s crucial for authors to master keyboard shortcuts and become power users. These shortcuts are designed to keep your left hand on the keyboard while your right hand controls the mouse.

1. Click on the “Help” button to see all keyboard shortcuts. 
2. Keyboard Shortcuts are designed to keep your left hand on the keyboard while you use your mouse with the right hand.
3. Keyboard Shortcuts are active when the cursor focus is on Map View (white background).
4. Keyboard Shortcuts are inactive when the cursor focus is on Interactive View (grey background).

Step 7 – Copy/Paste Decision Tree Nodes using Keyboard Shortcuts

Add “Yes” / “No” User Responses using Keyboard Shortcuts.

1. Click on “Yes” and press “c” to copy.
2. Click on “No” and press “c” to copy.
3. Click on “Turn Caps Lock Key Off”.
4. Press “v” to paste.

You can copy multiple User Responses and one Guidance Step, at a time.
– Copied User Responses can be pasted on any Guidance Step.
– A copied Guidance Step can be pasted on any “Orphan User Response”.
– Copy-paste feature works across Yonyx Guides open in different tabs of the same browser.
– Thus, an Author may copy nodes from one Yonyx guide and paste them into another guide in another tab of the same browser.

This feature significantly enhances the productivity of authors creating a troubleshooting guide, whether starting from scratch or copying nodes from an existing guide.

Step 8 – Add a Leaf Guidance Step “Thank You”

If the user is now able to log in, end the journey with a “Thank You” Guidance Step

1. Click on “Yes” and press “a” to “Add Guidance Step”.
2. Type “Thank You” in the Title. 
3. Leave the Body section and Follow-on Question sections blank.
4. Pressing the “Enter” key on your keyboard will save a Guidance Step if the cursor is either in the Title or Follow-on Question section.

Leaf Guidance steps are the end points of the user’s journey through a troubleshooting guide. All decision tree pathways should end in a guidance step.

Step 9 – Add Guidance Step “Reset Password”

If the user is still unable to log in, tell them to “Reset Password”. 

1. Click on “No” and press “a” to “Add Guidance Step”.
2. Type “Reset Password” in the Title. 
3. In the Body section, type “Click Here for Instructions”
4. Select the text in the Body section (Cmd-A), and click on the Hyperlink icon.
5. Paste the URL of an article containing instructions on how to reset your password. 
6. Select among Button Styles drop-down to choose a color to optionally highlight the hyperlink.
7. Add a Follow-on Question, “Are you able to log in now?”

Step 10 – Copy/Paste “Yes” and “No” User Response Nodes

Add Yes/No User Responses using Keyboard Shortcuts

1. Click on “Yes” and press “c” to copy.
2. Click on “No” and press “c” to copy.
3. Click on “Reset Password”.
4. Press “v” to paste.
5. Remember, You can copy multiple User Responses and one Guidance Step, at a time.
6. Copied User Responses can be pasted on any Guidance Step.
7. Any “Orphan User Response” has no Guidance Step following it.
8. A copied Guidance Step can be pasted on any Orphan User Response.
9. Copy-paste feature works across Yonyx Guides open in different tabs of the same browser.

Step 11 – Connect “Yes” Node to “Thank You” Node

If the user can log in after resetting the password, connect to ” Thank You”.

1. Click on “Yes”
2. Click on “Connect”
3. Click on “Thank You”.
4. Click on “Connect Here”.

The Connect feature enables authors to merge different decision tree pathways by linking various user response nodes to a single guidance step, minimizing content duplication. This feature is essential when creating a troubleshooting guide as it streamlines the process by consolidating multiple pathways into one. This not only saves time and effort but also ensures consistency across the guide. By reducing redundancy, it simplifies the management and updating of the guide, enhancing overall efficiency for authors.

Step 12 – Connect & Disconnect Decision Tree Nodes

If multiple User Responses lead to a Guidance Step, the Author can disconnect one of them.

1. Click on “Yes”
2. Click on “Disconnect”
3. Click on “Yes” or press the “Enter” key on the keyboard to confirm.
4. Note, the Guidance Step, “Thank You” re-draws itself following the User Response leading to it.
5. To re-connect, click “Yes”
6. Click on “Connect”
7. Click on “Thank You”
8. Click on the “Connect Here” button.

The “Disconnect” feature is essential during the creation of a troubleshooting guide, allowing authors to separate linked pathways and customize guidance for different scenarios. This ensures accuracy and flexibility, making the guide more precise and effective.

Step 13 – Connect to Guidance Step “Reset Password”

If the Caps Lock Key was not turned on, the user should try resetting the password.

1. Click on “No”
2. Press “q” [Keyboard shortcut for Connect].
3. Press the “Esc” key from the keyboard. The Interactive View panel disappears. 
4. Use the Keyboard arrow keys to scroll to the right.
5. Click on “Reset Password”.
6. Press “w” [Keyboard shortcut for Connect Here].

Step 14 – Add Leaf Guidance Step “Escalate Issue”

If resetting the password also doesn’t solve the customer issue, Escalate.

1. Click on “No”
2. Press “a” [Keyboard shortcut for Add Node].
3. Enter in the Title field, “Escalate Issue”
4. Press the “Enter” key on the Keyboard, to save.

Step 15 – Access Troubleshooting Guide in User View

Internal Users (e.g. Call Center Agents) or External Users (self-servicing customers) access guides in User View.

1. Click on “Home” on Interactive View to select the Root Node.
2. Click on “View” to access this guide in User View
3. Go down a path by choosing a User Response at every step.

Orphan user responses are stripped off in the user view to prevent confusion and maintain clarity. If these unlinked responses were visible, a call center agent might click on them, only to find that they don’t lead to any guidance steps. This can give the impression of a broken pathway, undermining the effectiveness of the troubleshooting guide. Removing orphan responses ensures that users encounter only relevant and actionable information, streamlining the troubleshooting process.

Step 16 – Enrich the Troubleshooting Guide – Add Image to a Guidance Step

Traverse in Interactive View to locate Guidance Step. Edit step to add image.

1. Click on “Home” on Interactive View to select the Root Node.
2. Click on “No” in Interactive View. Note, this selects the Guidance Step following the “No” in Map View. Authors can go through the guide interactively in this view to locate the section, they would like to edit.
3. Press “e” to edit the Guidance Step. [Shortcut for Edit]
4. Click on the “Images and Videos” button, then choose Image Explorer.
5. Click on the “Choose Files” button to select an image from your computer. 
6. Click the “Upload” button to upload the image to your Yonyx Image Library. 
7. Once uploaded, an icon-size view of the image appears in the Library.
8. Hover over the icon-size image and note the name of the image starts with the file name of the uploaded image.
9. Choose the image and click “Insert”

While creating a troubleshooting guide, incorporating images enhances its effectiveness by clarifying complex instructions and making them easier to understand. Visuals provide concrete examples of parts or errors, reducing ambiguity and minimizing misinterpretation. They also make the guide more engaging and less text-heavy, helping users stay focused. Additionally, images support visual learners by presenting information in a format that’s easier to process and remember. Yonyx supports both static images, as well as animated gifs.

Step 17 – Add Call Out Text to a Guidance Step

Use Callouts to draw attention to something.

1. Select the “Check Caps Lock Key” step in Map View.
2. Press “e” to edit.
3. Click on the embedded image to select.
4. Use the right arrow key on the Keyboard to place the cursor to the right of the image. 
5. Press Enter key twice to add two new lines after the image.
6. Click on the “Insert template” button.
7. Choose the “Callout with small emoji” option from the drop-down
8. Click Save
9. Select the text in the template and replace it with “Some computers may have a small LED in the Caps Lock Key. The LED is turned on to indicate that the Caps Lock Key is pressed.”
10. Callout messages are used to draw attention to some important information within a Guidance Step.

The ability to add “callout text” when creating a troubleshooting guide is important because it allows authors to highlight and emphasize key information or instructions. Callout text can draw attention to specific details, warnings, or important steps, ensuring that users don’t overlook critical elements. This feature helps improve clarity and focus, making the guide more user-friendly and effective by clearly directing users to essential information.

Step 18 – Search across Troubleshooting Guide in Map View

Powerful Search with multiple criteria.

1. Select “Leaf Guidance Steps” from the Search drop-down.
2. Click the “Search” button to find possible endpoints of journeys through the guide.
3. The first Leaf Guidance Step, “Escalate Issue” is selected. Click the Next or Prev buttons to select all Leaf Guidance Steps one by one. 
4. Select “Orphan User Responses” from the Search drop-down.
5. Click the “Search” button to find all Orphan User Responses one by one. 
6. There should be no Orphan User Responses when a guide has been completed by the Author.
7. Similarly, choose “Search All Fields” from the Search drop-down. Now enter “Caps Lock” in the Search text field and click the “Search” button. 
8. You now see all the nodes containing “Caps Lock” text.
9. This full-text search is case insensitive and searches across the Title, Body, Follow-on Question, and Author’s Notes sections of all nodes in the guide. You can also choose to confine your search to a particular field type – e.g., “Title” from the Search drop-down to search across only the Title section of all nodes.

The ability to search across the decision tree is crucial when creating a troubleshooting guide because it streamlines navigation and management of complex structures. Search criteria such as “text,” “leaf guidance steps,” “orphan user responses,” “nodes similar to current node,” “nodes containing placeholders,” and “nodes containing commands” enable authors to quickly locate specific information, identify and address gaps, and ensure consistency. This functionality helps in efficiently updating, reviewing, and maintaining the guide, ultimately improving its accuracy and usability.

Note 1: Yonyx Platform provides very comprehensive ways to search across your decision tree. Authors with complex decision trees containing hundreds or thousands of nodes appreciate being able to search and hop directly to a node. 

Note 2: Search takes place across the expanded portion of the decision tree. To expand your decision tree completely, click the “Home” button in Interactive View and click on the “Expand Guide” button in the top right-hand corner in Interactive View. You may also use the keyboard shortcut “x” to expand.

Step 19 – Create Troubleshooting Pathway for a User who is able to Login

If the user is able to log in, determine the issue faced by such a user.

1. Click the “Home” button to select the Root node.
2. Click on “Yes”
3. Press “a” [Keyboard shortcut for Add node].
4. Type “Determine Issue Faced” in the Title. 
5. Type “What issue is the customer, facing then?” in the Follow-on question. 
6. Press the “Enter” key to save.
7. Press “a” to add a user response.
8. Type “Unable to access content”
9. Press the “Enter” key to save.
10. Press “a” to add another user response.
11. Type “Unable to administer account”
12. Press the “Enter” key to save.

Step 20 – Use Placeholders, Commands and Logic Conditions

This imaginary SaaS platform we are troubleshooting requires a user to be set up as an Admin and he/she should access the platform only via PC or Mac in order to be able to see the Administration features. Now we get to some cool stuff … continue following along!

Create two placeholders.

1. Click the gear drop-down and choose “User Defined Objects”
2. Click on the “Create Placeholder” button.
3. Type “Device Type”.
4. Notice the platform creates an internal name with capital letters replaced by small letters and space characters replaced by hyphens.
5. Click on the Save button.
6. Now once again, click on the “Create Placeholder” button.
7. Type “User Type”.
8. Click on the Save button, or press the “Enter” key to save.

Placeholders are objects that store values (a Placeholder corresponds to a CRM field when used with Yonyx Data Connector) 
Commands are configurable forms that can be embedded in multiple guidance steps across multiple Yonyx Guides.
Logic Conditions are also called auto-traverse conditions. These conditions are specified in User Response nodes to help automatically skip along a path in User View, based on Placeholder values.

Step 21 – Create Yonyx Command (Embeddable Form)

Create a Yonyx Command (Embeddable Form).

1. Click the Commands tab under User Defined Objects.
2. Click on the “Create Command” button.
3. Type “User Access Details” in the name field.
4. Type “This form will let the Agent provide the role setup for the user and the device type used by the user to access the platform” in the Description section.
5. Click on the “Data Capture” tab.
6. Click on the “Add Field” drop-down and choose the Radio button list.
7. Associate the user-type placeholder with this field. This means the radio button option chosen by the Agent will be stored in the user-type placeholder.
8. Type “What role is this user set up with?” in the Label text field.
9. Type “Basic” under List Items. Click on the + sign to add a new item.
10. Type “Editor” for the second list item. Click on the + sign to add a new item.
11. Type “Admin” for the third list item. 
12. Note, you can also change the order of the items by clicking and dragging with the large + sign in the middle of each list item.
13. Click on “Radio Button List” to collapse the configuration screen for it.
14. Click on the “Add Field” drop-down and choose a Dropdown List.
15. Associate the device-type placeholder with this field. This means the Dropdown option chosen by the Agent will be stored in the device-type placeholder.
16. Type “What device is the user trying to access the platform with?” in the Label text field.
17. Type “iPhone” under List Items. Click on the + sign to add a new item.
18. Type “iPad” under List Items. Click on the + sign to add a new item.
19. Type “Android Phone” under List Items. Click on the + sign to add a new item.
20. Type “PC” under List Items. Click on the + sign to add a new item.
21. Type “Mac” under List Items. Click on the + sign to add a new item.
22. Click the “Save” button to save this command.

This command will capture the user-type via a radio button choice and a device-type via a drop-down element included in the form. 

The ability to add embeddable forms (Yonyx Commands) when creating a troubelshooting guide is essential because it allows for the collection of specific data, such as the product model number, error codes or purchase date, directly within a step of the guide. These values are stored in Yonyx placeholders and used to auto-traverse the guide based on logic conditions set by the author. This enables the guide to automatically follow a path defined by the collected information, making the troubleshooting process more efficient, less error prone and personalized to individual needs.

Step 22 – Add Guidance Step with Embedded Form

Add Guidance Step with Embedded Form (Yonyx Command).

1. Click “Unable to administer account”.
2. Press “a” to add a Guidance Step.
3. Type “Get User Access Details” in the Title field.
4. Type “Next Step” in the Follow-on question field.
5. Scroll down and click on the “Choose” button to add Yonyx Command. 
6. Select the user-access-details command and click Insert.
7. Click the “Save” button.
8. Note the form appears in the Body section of the guidance step.
9. Press “a” to add a User Response.
10. Type “Continue” and press “Enter” to save.

Note: Every Guidance Step that contains a Yonyx Command (embedded form) should have a User Response following it – i.e. such Guidance Step should not be the Leaf Guidance Step of the guide. The User Response node(s) following such Guidance Steps behave like a “Submit” button for the form data captured in the Guidance Step.

Step 23 – Add Logic Step to be Auto-Traversed (skipped over)

Add Guidance Step that will be skipped over based on logic conditions added to its User Responses.

1. Click “Continue”.
2. Press “a” to add a Guidance Step.
3. Type “Skip using Logic Conditions” in the Title field.
4. Type “Which direction?” in the Follow-on question field.
5. Press “a” to add a User Response.
6. Type “Admin & PC” and press “Enter” to save.
7. Press “a” to add a User Response.
8. Type “Admin & Mac” and press “Enter” to save.
9. Press “a” to add a User Response.
10. Type “All other combinations” and press “Enter” to save.

Step 24 – Add Logic Conditions to User Response Nodes

Add Logic Conditions (Auto-traverse conditions) to all User Responses.

1. Click “Admin & PC”. We’d like to skip along this path if user-type = Admin and device-type = PC.
2. Press “e” to edit the User Response.
3. Select Placeholder user-type
4. Note that you can choose multiple logic conditions – e.g. “Is Equal To”, “Begins With”, “Greater Than” etc.
5. Type “Admin” for its value.
6. Note that you can assign a specific value (like Admin) to a Placeholder, or assign it the value of another user-defined or system placeholder.
7. Click “Save”
8. Click + to add another condition.
9. Select Placeholder device-type
10. Type “PC” for its value.
11. Now, click “Admin & Mac”. We’d like to skip along this path if user-type = Admin and device-type = Mac.
12. Add placeholder auto-traverse conditions for this User Response similar to the earlier one.
13. Now, click “All other combinations”. We’d like to skip along this path if
    1. user-type = Admin and device-type = iPhone or
    2. user-type = Admin and device-type = iPad or
    3. user-type = Admin and device-type = Android Phone or
    4. user-type = Editor or
    5. user-type = Basic
14. To add all this logic for “All other combinations”, simply click on the “Fallback Auto Traversal” checkbox.

Step 25 – Add Guidance Step for “Valid User Type and Device Combination”

Add Guidance Steps for Valid User Type and Device Combination.

1. Click “Admin & PC”. 
2. Press “a” to add a Guidance Step.
3. Type “Valid User Type and Device Combination” in the Title section.
4. Type “Is account on hold due to payment issues?” in the Follow-on question section.
5. Press the “Enter” key to save.
6. Click “Admin & Mac”
7. Click the “Connect” button.
8. Click “Valid User Type and Device Combination”
9. Click the “Connect Here” button.

Both “Admin & PC” or “Admin & Mac” User Responses now lead to “Valid User Type and Device Combination” to continue further troubleshooting.

Step 26 – Add Guidance Step for “Invalid User Type and Device Combination”

Add Guidance Steps for Invalid User Type and Device Combination.

1. Click “All other combinations”. 
2. Press “a” to add a Guidance Step.
3. Type “Invalid User Type and Device Combination” in the Title section.
4. Type in Body section.
   1. To access Admin functions:
      • User Type should be Admin
      • Device Type should be PC or Mac
   2. Select a 2×2 table and add to a new line.
   3. Type “User Type” and “Device Type” in the first column of the two rows.
   4. Keep your cursor in the second column of the first row.
   5. Click Tools->Insert Placeholders and choose user-type, then click the “Insert” button.
   6. Repeat the same with device-type in the second row.
   7. Select all cells of the table.
   8. Click the “Paragraph” drop-down to Advanced. Now choose Text Background Colors to be BG Primary.
   9. Click the “Paragraph” drop-down to Advanced. Now choose Text Foreground Colors to White (the last invisible option).
   10.  Click the “Save” button.

Step 27 – Navigate the Created Troubleshooting Guide in User View

Traverse Guide in User View.

1. Click the “Home” button in Interactive View. 
2. Click the “View” button to open the guide in User View in a new browser tab. 
3. Choose User and Device type combinations that cause the guide to auto-traverse towards Valid and Invalid Combinations.

Note, the “Skip using Logic Conditions” step is not visible in User View, as the guide skips over this step along a path based on placeholder values and the auto-traverse conditions.

The Yonyx user view is designed to be very easy for users to navigate, as it presents a straightforward, intuitive interface that works across all browsers and all devices. Users follow a specific pathway tailored to their needs, entering data through embedded forms if required, selecting responses, and viewing the next relevant guidance step. The intricacy involved in creating the troubleshooting guide in the form of a decision tree is completely hidden from users, allowing them to focus on their troubleshooting process without being overwhelmed by the guide’s underlying structure. This seamless experience ensures that users can efficiently resolve issues with minimal confusion.