Organization & Role
Heap is a digital analytics platform. As their founding documentation strategist, I’m responsible for the user experience, information architecture, content strategy, and all content within the Help Center and developer/API docs.
Project
Prior to my joining Heap, there was no customer-facing documentation about what to do when one’s Heap account was locked – a sensitive question primarily answered by Sales and Support.
Problem
One of my regular tasks at Heap is to review support tickets, which allows me to spot opportunities to shore up gaps in documentation related to common customer questions. This was one such opportunity.
In conversations with Sales and Support, I learned the main reason why this question had never been answered publicly is that it can happen for a variety of reasons, and the follow-up required varies based on each one. It also sometimes requires having a difficult conversation about delinquent payments or account usage. I took it upon myself to talk to each team and coalesce the reasons into one FAQ to give customers searching for these answers a starting point.
An interesting dilemma that came up while writing this FAQ was deciding which term to use to describe the entire Heap account. Up until then, we were using this term to reference two different things:
- Individual users’ accounts within the company account
- The company account
To differentiate the broad company account from users’ accounts, I set about brainstorming the most intuitive term to choose and stick with. I’ve fully unpacked that discussion in the Aligning on Terminology section below.
Approach
Outlining Content
To tackle the problem of gathering all the reasons why a customers’ workspace would be locked, I combed through support tickets and Salesforce cases to generate a list of reasons why a customer might be locked out of Heap. Once I’d done so, I pinged members of Support and Sales to confirm which reasons we could publicly discuss. Once I had this, I set about drafting the copy.
Establishing Voice & Tone
An account is most commonly locked for financial reasons; either a customer whose free trial ran out, or a paying user whose payment info didn’t work. Given the sensitive nature of the topic, I kept the tone of the FAQ neutral and straightforward. There’s a time and place for the use of humor; a payment issue is not one of those times.
With this in mind, the FAQ starts with a list of the main reasons this may occur, immediately followed by the steps to move forward for each of those reasons.
There was one last use case to account for; a rare one, but one that did occur occasionally. I opted to add it at the bottom so it would stand out from the other reasons.
Aligning on Terminology
To bring the team together on the most accurate term for the greater account, I reviewed existing content to identify the most common terms already in use. Through this process, I discovered the terms account, domain, and app were the most popular choices, with account and domain favored for customer-facing content, and app mostly for internal use among more technical teams.
Next, I checked our competitors and SaaS industry leaders to see how they referred to the greater account. I was inspired to add workspace to the list of possibilities via Slack’s use of the term.
Last but not least, I pinged individual team members with the most expertise in our voice and terminology for their thoughts, being careful not to give suggestions to avoid bias. Some interesting suggestions were generated, such as organization.
Having generated a list of ideas, I posted to #heap-writers (our channel for writers across all teams to chat) to build consensus around one term to add to the style guide.
Folks from Design, Engineering, and Success jumped in. I had expected (and prepared for) more debate than actually occurred by mapping out the pros and cons for each name in a private doc.
As the thread unfolded, we pretty quickly solidified workspace as the most accurate term, and it was added to our writing guide. Huzzah for consensus and consistency!
SEO
Despite our internal alignment about workspace, I noticed via Google Search Console that ‘account locked’ was the most popular phrasing for this type of situation. To make sure this FAQ would be as discoverable as possible, I optimized the metadata for this FAQ to align with searches for ‘account locked’ (and other alternative phrasings) to make sure this would appear in those searches.
Outcome
This isn’t the type of FAQ one expects (or hopes) to become popular – the views have ranked fairly low compared to other FAQs, which is a good sign. Monitoring the SEO, it appears that all the right search terms that should lead to this FAQ are doing so, which is what matters most.
Post-publication, Support reported that future messages about this issue were more precise in elaborating on their experience encountering it, and several referenced the FAQ. This is the very best feeling for a documentation writer.
See the current version here: Why is my Heap workspace locked?
