My Portfolio / Information Architecture / Feedback Docs
Overhauling help docs for a better user experience
Aim: Evaluate the existing documentation for Pendo Feedback, map the content to feature functionality in the context of the end-to-end customer workflow, and update the content to match this workflow.
Problem
Oftentimes, technical writers are hired after a product has been in development for several years. The company I joined was an example of this. I was hired as the first senior technical writer for one of the company's growing products, tasked with fixing the existing product documentation.
Various articles had been haphazardly written by marketing managers, product managers (PMs), product operations managers, and engineers. As a result, the documentation for the product had several issues:
-
Chaotic categorisation and naming. The content was organised loosely around key topics, inconsistently named, and then ordered alphabetically (mostly).
-
Searchability. It was thus difficult to know where to start and there was no defined path for the visitor to follow. Article titles weren't easy to read or scan, and sections included up to 30 articles each.
-
Findability. Answers to common questions relating to specific scenarios and goals existed in the documentation, but there were no structural elements (navigation) providing clarity for where to find this information.
-
Context. Articles jumped straight into specific functionality and goals without grounding the reader first. Some articles included a single paragraph or answers to specific questions, without context.
-
Presumed knowledge. Much of the content assumed that the reader knew where to go or what features were called.
-
Accuracy and completeness. Content was chronically out of date and incomplete, both in terms of existing features and in terms of missing content.
-
Tone and style. The content was far below industry standards for technical writing, and included marketing and colloquial language.
The documentation landing page before the restructure
Process
1
Identify the "as-is"
I started by taking inventory of the existing content and mapping this against a customer workflow for using the product.
2
Define the "to-be"
I created a sitemap and evolving table of contents, with an aim to create digestible chunks of ordered information.
3
Update the content
I updated content, one workflow phase at a time, and whenever I could align new and updated content with releases.
1. Identify the "as-is"
I used Miro to map the sequence of tasks against existing articles. I included the relevant personas, customer and business goals, product touch points, common barriers, and content opportunities. The workflow was created and validated based on:
-
Working sessions with colleagues.
-
Search data analysis.
-
Survey responses collected using Pendo Guides.
-
Relevant requests submitted through Pendo Feedback.
-
Content analysis of NPS comments.
2. Define the "to-be"
I wanted to reduce the visual noise and leverage the order of articles to guide customers through best practice processes. To this end, I drafted sitemaps (in Miro) and created an evolving table of contents (in Confluence). I wanted to improve navigation and scannability by:
-
Creating new sections that reflected key phases in the customer workflow with the product.
-
Reducing the size of a section to include a maximum of eight articles.
-
Renaming instructional articles to include customer actions at the beginning.
-
Renaming informational articles to include key functionality at the beginning.
The table of contents was validated with SMEs and updated as appropriate. It included plans for new informational content for each phase of the customer workflow, making improvements to instructional content, merging content, and filling in content gaps.
3. Update the content
Release documentation always took precedence (for this and other doc sets I owned). Thus, many of the structural and style updates occurred during release documentation changes. Where possible, I also updated articles in order of workflow phases. On top of this, meetings with the Product Operations Manager were held on a regular basis to inform content for new articles that outlined best practice processes. Major decisions and updates were always communicated and discussed with stakeholders, including PMs and engineers.
61%
Reduction in articles
The number of articles was reduced from 109 to 43. This helped to ensure that information was findable, up-to-date, and in-context.
+10
New articles
2x
Increase in visitors
The reduced number includes new articles to fill in content gaps that should help customers understand the workflow and how functionality is related.
The number of visitors doubled compared with the same time period the year before. Visits to low-performing but important articles drastically increased.
Outcomes
The resulting product documentation consisted of eight sections, organised around the customer workflow, with between three and eight articles per section.
I requested a left-side navigation bar so that visitors could see all articles available to them, in order. This allows new customers to understand the expected sequence of activities without having to open each article, and allows existing customers to orient themselves without having to search for key terms, saving time and reducing frustration – not everyone enters through the front door.
Instructional content included an overview of key considerations and steps, then introduced readers to essential and basic tasks before moving onto more complex and case-specific tasks.
Additionally, industry standards for tone and style were applied to all the articles. The content was also updated in line with changes to the UI and features that hadn't been documented.
After the restructure, the number of visitors to the Feedback doc set doubled compared to the same time period the previous year before the restructure.
In terms of article performance, key content, like the Overview article for getting started, and The Feedback Workflow made it to the top ten list of most visited pages. Another key article, Tagging in Feedback saw double the number of visitors, which was important because it included newly written clarification about functionality and best practices in response to insights into what customers struggle with the most. Two new articles, written to clarify key aspects of the UI and functionality were present in the top ten most visited articles.
Challenges and learnings
The main challenge was finding the time amongst my other technical writing responsibilities to update the content as planned. On top of a growing workload, I took the opportunity to update articles and related content alongside every release.
Out-with release documentation, I decided to tackle foundational articles first, which tended to focus on best practices for different personas. This was challenging because a lot of these best practices happen outside of the product itself. This information relied on insights from SMEs, all of whom were busy in their day-to-day jobs. I needed to get them excited about the restructure effort and respect their time with planned working sessions aimed at answering specific questions.
From a more technical standpoint, I was also limited by the Zendesk theme. I couldn't create child pages or override the hierarchy of categories, sections, and subsections. I employed workarounds to deal with these issues, relying heavily on the order of sections and articles, summarising key steps in informational articles before introducing respective instructional articles.
Renaming, deprecating, and forwarding articles was also an involved process. I maintained a spreadsheet as an audit trail of changes to content, including links to each page (published and archived) in Pendo Analytics.