Skip to main content

How we relaunched our help content to better serve our customers

Read Time 5 Mins
Customer Support

The best help content should be more like a level-headed friend than a risk-taking daredevil.

As a technical writer at Learnosity, my job is to coach, train, and advise the teams around me on creating the best documentation they can. But here’s my hot take: even the clearest, most useful documentation isn’t going to set pulses racing – nor should it.

The only documentation that’s likely to quicken the pulse – and not in a good way – is bad documentation.

This is a major faux pas for any company that offers high-end technology. As software increases in sophistication, so does the importance of having good support material. That’s why one of my first ports of call when I joined the team was to audit our documentation site and see where it could be improved.

Know your goal: Helping users to help themselves

Good documentation might not set the world on fire, but it does help people get more from great technology. That could mean bringing high-value but underused features to light, explaining new enhancements you’ve shipped, or just offering sharper content for more efficient troubleshooting.

But if you want your documentation to do any – or even all – of those things, then you need to take it seriously and approach it strategically.

When help content no longer helps

Having conducted a review of our own legacy documentation site, we found that it had taken on a life of its own as a messy blend of content aimed at very different user types. Some of the oldest content was even steering newer customers into the weeds by focusing their attention on low-level nuts-and-bolts-type tech that our products had long since outgrown.

"Good documentation might not set the world on fire, but it does help people get more from great technology." Click To Tweet

The docs site had also become a default shelter for homeless live code projects, which made it even harder to know where things were or where they should go. So we asked ourselves: if we were finding our own docs site confusing, what hope had our customers?

Spring cleaning your way to success

“Segmenting content would make it easier for us to optimize each strand for a better, more tailored customer experience.”

Our solution was relatively straightforward: split the existing docs site up into separate entities that matched the needs of our different customer types (i.e. content authors and developers).

For example, content authors using Learnosity to create assessments weren’t necessarily going to need or understand technical deep-dives aimed at developers – so why house that content in the same place?

Segmenting content would make it easier for us to optimize each strand for a better, more tailored customer experience. It allowed us to concentrate more on scrapping, reworking, adding, and organizing content that specific customer types needed the most.

Segmenting content helped keep things relevant to specific customer types.

For instance, we found that some help content was just too long. Users looking for quick answers had to first negotiate a maze of text. The workaround was to chop longer articles into more digestible bite-sized pieces and give these articles more descriptive headings. This made it quicker and easier for users to identify what content was useful and what wasn’t.

One becomes three

Since our support teams were already using Zendesk for communicating with customers, we felt the best way to improve customer self-service was by using Zendesk Guide as our knowledge base. This the would ensure a more integrated working environment. 

Our designers worked hard to customize the look of the help sites to bring them in line with the clean new aesthetic of our homepage. And with the expert backing of the support team, we reworked, migrated, and added new content, giving each site its own unique information architecture. 

In the end, here’s how we divided the three help sites:


Primarily aimed at developers and product managers, the Help site provides a vast knowledge base of concise (and subject-specific) articles and tutorials.

Author Guide

The Author Guide site is, as the title suggests, primarily geared toward content authors. To enable these users to get the most out of the available help content, we tagged all articles to make them more easily discoverable through search.


The Reference site also caters to developers and tech-savvy users with information on things like how to initialize each API; methods and events for each API;  dev troubleshooting; and release logs.

Empowering customers by empowering colleagues

While improving the help content experience for customers was always our number one goal, we also had to consider how we could maintain a high standard of documentation in the longer term.

The best way of doing so is pretty straightforward: keep contributors engaged by making it easy for them to update content.

This wasn’t the case previously. When using our old system, contributors would need to access GitHub via the command line and then manually edit the HTML. This wasn’t particularly difficult, but it was time-consuming and (very!) prone to error. In other words, the perfect conditions for disengagement.

However, a new WYSIWYG editor made creating and publishing articles quick and easy. With more control over the publishing process, contributors can continuously update content so that the right information is always available to customers – even after new product releases.

Headline successes

In short, here are the fruits of our collaborative labor:

  • We successfully created separate documentation sites for our different customer personas.
  • Zendesk Guide provides a far better user experience through elements such as user feedback mechanisms, visual rich text editor, and instant publishing. These are a delight for our non-developer documentation contributors.
  • We now have buttery-smooth documentation workflow integration for our team of support agents. This is an ideal outcome for them.
  • The barriers to creating tutorial-type documentation are now lowered so that anyone in the company can easily contribute. Importantly, the actual time required to make any change has been cut right down. This benefits technical and non-technical staff alike and leads to more proactive maintenance of the documentation content.
  • Collectively, these all contribute to higher documentation quality and more timely content.

Key takeaways 

For anyone embarking on a similar project, the following notes might come in handy:

  • When making a major change to your documentation set, also consider the possibility of switching platforms at the same time. This was transformative in our case.
  • Redirecting every page from old-to-new is hard. Your time might be better spent on other things.
  • When you’re refreshing the layout and design of your documentation, it’s important to also spring-clean the content. There’s no point putting a shiny new frame around a picture covered in dust.
  • The time cost of creating and editing documentation in your system is an important data point. If it takes too long to change things, or the simplest edit takes more than five minutes, people will instinctively avoid doing it. Cutting that time down brings people back as engaged contributors.

The primary job of help content is to empower customers to help themselves. Making your documentation as clear and discoverable as possible is essential to achieving this – especially if your solution sits at the more complex end of the scale (as Learnosity’s does).

The challenge down the line is to maintain that high standard even as your product evolves. This means treating your documentation as an essential part of your offering through regular reviews, updates, and, of course, customer feedback.

"The primary job of help content is to empower customers to help themselves. Making your documentation as clear and discoverable as possible is essential to achieving this." Click To Tweet

And to finish on that note, if you’ve got any questions, suggestions, or comments on our help content, we’re listening.

Edwin Dawson

Technical Writer

More articles from Edwin