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 & Problem
The Using Identify guide was the #1 most-viewed developer guide. However, we received developer feedback that the layout of information was confusing, which prevented developers from successfully implementing the APIs and forced them to reach out to support.
The process of updating this specific guide reflects my overall process for updating developer content in collaboration with our developers, so I decided to write it up as a portfolio piece.
Approach
For context, I have a basic background in coding. I’ve built a few web apps in JavaScript and used some APIs. Though I understand API basics, I don’t have as much experience as a full-time developer.
To leverage my docs expertise and our developers API knowledge, the general process of collaboratively updating developer docs is broken into two phases:
- An asynchronous review of the current doc by a developer, who suggested edits as a subject matter expertise.
- A (solo) rewrite by me to incorporate the developer feedback and make additional edits for voice, tone, and terminology.
Since our docs team was in the habit of regularly conducting docs user testing, I used this as an opportunity to uplevel the accuracy and usefulness of our most popular developer g uide.
Subject Matter Expert Reviews
To get feedback from the perspective of the target audience for this guide (experienced developers who were new to Heap) I booked user testing sessions with our five newest developer hires. During the sessions, I asked them to apply the steps in the guide and share points of confusion, highlight content that helped them the most (to avoid changing it) and anything else that came to mind.
As they spoke, I added comments and suggested edits to a draft copy while sharing my screen. This helped to confirm my understanding of what they’d said, and inspired us to live brainstorm ways to improve the weaker parts of the guide.
Conducting a live session also made it easy for me to quickly fact-check things I didn’t understand, such as developer-specific language. For example, the termNSUserDefaults became a hot discussion point, since it’s iOS specific, though the rest of the guide was focused on web. We brainstormed ways to include relevant content for multiple platforms in a way that would help readers.
I opted to use a fresh doc copy for each session so that each developer would not be influenced by comments and edits from previous sessions. Once the sessions were done, I synthesized all the feedback into one copy, noting points where multiple devs gave the same feedback. Fortunately, there was no conflicting feedback, which made it easy to move onto the next step.
Voice, Tone, & Terminology Audit
With the subject matter expert reviews complete, I did my own revision for voice, tone, and terminology. Heap already has a writing guide (collaboratively developed by marketing, design, and me) so I reviewed and applied the principles to this guide.
Outcome
The guide received a much-needed overhaul, which included the following changes:
- Removed redundant explanations across different parts of the guide to make it more concise and straightforward.
- Moved the most universal use case (which 80% of customers implemented) to the very top of the examples section.
- Removed an extended, nuanced edge case that was more likely to confuse developers than help them. The content was saved internally for the support team to reference and share with customers as needed.
- Updated all screenshots to show only what’s relevant to the example – many of these were too zoomed out, making it difficult to tell what was actually relevant.
- Moved one important callout about a mistake which could break their implementation to the very top, highlighted in red, along with a link to a section at the bottom with more details.
Last but not least, I opted to split this guide from one doc into two. The first guide retained the core content. The rest, which branched off into focusing on A/B testing use cases, was moved into a new doc on A/B Testing.
Since launch, these two docs have received a high volume of views and upvotes. New hires tasked with test implementations have referenced it as a bedrock for their understanding of identity management.
You can see the latest version of this guide here: Track user identity
