Tip: How to implement Zendesk's troubleshooting guide

A troubleshooting guide (a.k.a Guided path) is an interactive learning article that provides specific steps to self-diagnose an issue or to complete a series of configuration tasks.

Tech stack

• JavaScript
• CSS
• HTML
• Bootstrap
• jQuery
• FontAwesome

The troubleshooting guide consists of two main components: 

• progress bar
• sections

Progress bar

The progress bar tracks the user's progress when completing a series of tasks. It starts in an inactive status, characterised by the grey color:

At the very core, the bar is a series of highly stylized HTML <li> elements. It rests inside a DIV that works as a container and carries a CSS class that positions the bar on the page and keeps the circle elements and their descriptive text at a fixed distance.

Inactive and active states of the bar are applied via CSS using a recurring pattern:

selector:psuedo-class

Using this pattern allows for more dynamic management of styles.

When the bar is activated, it signals so by changing color, and filling in the current step, the related portion of the progress bar, and the beginning of the next step:

The color shifting and progression are accomplished via CSS using a:

 'nth-child()' pseudo-class

When all the steps are completed, a different CSS is applied and the color of the bar changes entirely:

Sections

Sections consist of collapsible elements, also known as accordions. Their function is to contain and organize the content on the page.

The core of the section is the Collapse Bootstrap component.

At a glance, each section contains:

• Title
• Subtitle
• Arrow icon (animated to rotate via CSS)
• Button

CSS styles are used to determine the style and arrange the position of the elements inside the component.

Clicking on title or subtitle causes the component to expand:

The toggle effect is part of the core functionalities of Collapse, and it's achieved in this implementation via data-target attribute:

data-target="#collapse-virgil-one"

As we are dealing with multiple targets, we also need to match that with an ID:

<div id="collapse-virgil-one" class="collapse">
<p class="virgil-card-text wysiwyg-text-align-left">
Triggers and Automations, or business rules, are the features
that control email notifications in Zendesk Support. A trigger
that is not set up correctly can lead to an email notification
at the wrong time, or not sent at all.
</p>

The buttons inside the component can be clicked and change both the color and the text inside them:

Buttons also have a unique relationship with the track bar, as clicking them activates the color shifting of the bar:

The style-shifting in the bar elements and the buttons as well is handled in JavaScript by a series of functions that add/remove classes dynamically from the HTML elements:

This pattern is used throughout the implementation to handle color-shifting dynamically.

Sections and Tack bar elements are modularised, and they can be used separately. You can use sections without the track bar, and they would behave and work perfectly fine. In that scenario, it'is best to remove the buttons, as there is no bar to interact with.

The last section is a bit special, in that it houses a reset button that becomes visible only if all the previous steps have been completed:

The reset progress button has two functions:

1. Scrolls the page back to the top.
2. Reloads the page, thus resetting the progress of bar and section.

Both functionalities are handled via two separated functions in JavaScript. 
Resetting the progress allows users to repeat the learning experience as many times as they need.

Other functionalities

The troubleshooting guide is intended as a step-by-step tutorial where each step must be checked before the next one. This is handled via JavaScript and a series of conditional checks that ensure a button is not clickable unless the previous one was clicked.

The guide's sections do not need the bar to be present to work as intended, and buttons can be removed as well, leaving just the accordions, that look and behave as expected.

Steps can be added to the progress bar, as well as sections. There is no real limit to how many steps and sections can be added, but usually, five (or less) to eight is a good compromise.

The implementation is fully responsive, for a great mobile experience.