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.
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.
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?
“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.
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.
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.
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.
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.
In short, here are the fruits of our collaborative labor:
For anyone embarking on a similar project, the following notes might come in handy:
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.