Story of how we revamped our legacy Help Center

Published in

helpshift-engineering

6 min readOct 27, 2021

Helpshift is a customer service platform that enables you to provide a real-time conversational support experience for all of your users on all different platforms and devices. In addition to different types of support provided by Helpshift, we have a self-service Legacy Help Center filled with categories and FAQs that help end-users to solve their problems.

The Legacy help center is robust, but it’s outdated. The problems with Legacy Help Center are:

Not SEO-friendly
Old and non-human-centric themes
Difficult to customize — needs customers to involve engineers to make UI changes
Low discovery of popular or related articles.

We need to build a robust, more discoverable, and human-centric version of the Legacy Help center a.k.a. Help Center 2.0.

While exploring the tech stack for building Help Center 2.0, we have to consider the following points:

Customization: We are not going to have different Help Centers for every customer, instead we will have one that can be customized to the required look & feel. At the same time, it should take minimal effort to customize the Help Center.
Compatibility: The end-users for Help Center are going to be on various devices and platforms. So, we have to build it with high compatibility across devices and platforms.
Load Time: It’s simple, speed is important for a good user experience. Less load time, happier end-users.
SEO & Rich Results: These are two important factors that increase the quality of traffic via search engines. Help Center’s FAQs should render on Google’s search result page itself, for example under featured snippets.
Logic-less or Static UI: As mentioned in the previous point, Help Centers are FAQs with enhanced discovery. So, most of the content is static or logic-less.

A lot of frontend frameworks are available like React and Angular but they are built for advanced, data-heavy use cases. We wanted to use a tech that is very simple to use and met the above conditions. Templating Engines enables us to add dynamic logic to static HTML pages and keep CSS & JS separate and clean. There are different templating engines like Handlebars, Ember, Pug, etc. One of the most popular templating engines is Handlebars, which we are using for Help Center 2.0.

Handlebars

We are using handlebars, a templating language that satisfies all the above conditions.

Handlebars provide simple semantic & logic-less templates, which can be used to change the structure of a web page with dynamic content, hence easily customizable.
Handlebars compile templates into JavaScript functions that generate HTML, hence highly compatible.
For better load time & SEO, server-side rendering (SSR) is used and handlebars are considered as one of the best tools for SSR.

How does it work?

Handlebars take a template with variables & other Handlebars expressions (partials, helpers) and compile it into a function.
This function is then executed by passing a JSON object as an argument. This JSON object is known as context, and it contains the values of the variables used in the template.
On its execution, the function returns the required HTML after replacing the variables of the template with their corresponding values.

Example:

Template:

Data:

Generated HTML:

Rendering of Help Center

While rendering the Help Center, we have to think about how static resources like HTML, CSS, and JS will be customized, and how to make it responsive for different screen sizes.

HTML

We have already seen that we can use handlebars templates, and data specific to generate customized HTML.

CSS

Style customization mainly uses font-family, colors, and images. In a scenario where we want different styles, we can think of CSS Variables.

CSS Variables: It’s also called CSS custom properties, mainly used

to reduce code repetition
for runtime effects like theme switching

We can use Handlebars partials and have different variables, which will result in different themes. Let’s see an example:

Now that we have all these styles at the root level, we can directly use these variables for styling.

Isn’t this powerful? With a few lines of CSS variables, we are customizing the whole theme.

JavaScript (Web Components)

JS is used for performing logical operations, which we can write differently based on different Handlebar templates.

A website has various widgets for user interaction. In the context of Help Center, these widgets could be Dropdown, SearchBox, Feedback, Contact form, etc.

Now a few questions come to mind:

Would the widgets be compatible with different browsers?
What if we have complex widgets like search and dropdown?
Widgets should work when added at any place on a page, without breaking any functionality on the page.
Do we have to use some kind of framework only for widgets?

From the above points, we can say that widgets are independent components that should work correctly, irrespective of the parent page. In other words, they should be framework-agnostic. Luckily, we have something called Web Components.

Web Components

Web Components are a set of browser APIs that allow the creation of custom and reusable components that work across all modern browsers.

It mainly consists of Custom Elements & Shadow DOM.

Custom Elements: These are custom tags like HTML tags. Let’s use a feedback helper custom element.

Feedback Custom Element definition

In this custom element, we have created a component, which we can use at different places, and it’ll render a widget. But there is an issue. What if CSS/JS inside the custom element is overwritten by the parent page or vice versa.

For such cases, we need to sandbox CSS/JS. The web component provides a mechanism for it called Shadow DOM.

Shadow DOM: The shadow DOM is like a scoped subtree inside the custom element. It provides the following important features:

Isolated DOM: A component’s DOM is self-contained (e.g. document.querySelector() won't return nodes in the component's shadow DOM).
Scoped CSS: CSS defined inside shadow DOM is scoped to it. Style rules don’t leak out, and page styles don’t bleed in.
Composition: It let us design a declarative, markup-based API for our component.

Let’s create a shadow DOM for feedback helper.

Thanks to Web Components, we can create an independent and isolated widget. Let’s see how a typical Shadow DOM looks.

Feedback helper Web Component with shadow DOM

Responsive Web Design (RWD)

A set of practices that allows web pages to alter layout and appearance to suit different screen widths and resolutions.

Why does the help center need responsive web design?

We are building a product that is going to be used across different devices/platforms, and it should super easy to use.
SDK-X Help Center: SDK-X is a next-generation Helpshift software development kit. In this feature, we are rendering Help Center inside an app via web-views. It should match native SDK like performance and responsiveness.

There are a couple of best practices that can be followed to achieve RWD.

We can use fluid properties like, max-width, max-height or even responsive units like %, em , etc.
Media Queries: Responsive design was only able to emerge due to the media query. Let’s directly jump to an example

We can also use Flexbox, CSS grids, whenever required.

Conclusion

Using the above concepts and techs, we have built a Help Center black box that delivers the following functionality.

Customization — to change the look and feel as per requirement
Robust and responsive — can be used on most devices & platforms
User-friendly with better load time and SEO

A new version of Helpshift’s help center

Helpcenter 2.0 being a powerful product with a robust tech-stack, was adopted by quite a few of our customers on Day 1 itself and the number for adoption rate is growing ever since.

Few examples of how our customers have customized and are using Help Center 2.0 in their way. Zynga Player Support, Nordeous Support, Tencent Game Support.