Revamping a developer documentation hub - Renée Carignan (They/Any)

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

Within my first year, I migrated 90% of Heap’s support content, mostly meant for non-technical readers, from an old developer docs portal into a brand-new Help Center. Once this project was complete, I turned my attention to remaining 10% of content, still in the old CMS (ReadMe) to revamp into a proper developer documentation hub.

Problem

Once the majority of non-developer content had been migrated out to the Help Center, I talked to members of the team about the pain points for developers using our developer documentation. I distilled that feedback into the following areas of focus for the project.

#1 No clear indication that this is a ‘developer’ hub for customers

Following the content migration, we received feedback that it wasn’t clear to some visitors that this site had been kept for exclusively developer content; some thought it was just leftover content from the migration.

Here is what the developer site looked like at that time. Aside from one line referring them to the Help Center, the UX looked mostly the same as it had before the content migration.

#2 Poor information architecture

After the migration of 90% of the original docs, I organized the remaining 10% into the following sections:

Configuration Guides
FAQs
Changelogs

While the changelogs category was pretty self-explanatory and not subject to change, customer-facing teams gave feedback that the configuration guides and FAQs categories were confusing – they lumped together a bunch of relatively unrelated docs, making these headers relatively useless.

There was also a need for new developer documentation which didn’t fit into the current architecture. However, engineering needed bandwidth from the docs team to get their drafts of this content revised and published. Likewise, the docs team needed engineering bandwidth to validate the technical accuracy of certain bits of content that were dangerously out-of-date.

#3 No clear internal guidelines on which site should host which types of content

After the Help Center launch, there was a discussion about where certain ‘in-between’ docs, which contained both developer and non-developer content, should go. There were some docs we decided to migrate (or not) which were coming up repeateadly as feeling like a better fit for whichever site they weren’t in.

Part of this project involved defining the purpose and audience for each site and the criteria for when a new doc should be added to the developer docs instead of to the Help Center.

Approach

Gathering Stakeholders

To define the difference between “technical” and “non-technical” content, I enlisted the help of stakeholders from teams with varying levels of technical expertise based on their general interest in, and bandwidth for, the project.

One Engineering Manager (for co-ownership of technical content)
One Product Manager (for product roadmap perspective)
One Designer (to decide what layout changes are needed)
One Frontend Developer (for dev perspective and to implement CSS changes)
One Professional Services Consultant (for perspective on technical onboarding)
Two Solutions Engineers (for the technical customer perspective)

Benchmarking Success

With the pain points defined and stakeholders gathered, I set to work outlining how to measure the success of the project. To start, I wrote out the vision for a stellar developer docs portal.

A UX (branding and copy) that makes it clear this is a developer docs site (not a Help Center).
An intuitive and scalable information architecture designed to grow with our dev docs.
A clear definition of what content goes in the dev docs, and what goes in the Help Center, to make future content decisions easier for us and set expectations for customers.

I also defined the following quantitative success metrics for the revamp.

A decrease in ‘no’ 👎 answers to the ‘was this doc helpful’ 👍👎 survey in each doc.
A decrease in customer outreach related to developer docs ex. saying they couldn’t find information in the dev docs, or asking questions that were already in the dev docs.
An increase in views of developer docs that were previously less discoverable.
An increase in conversion from any dev docs pageview to a click on (or search for) an actual doc.

Craft Purpose & Ownership Statements

To address the confusion on what are “technical” vs. “non-technical” docs, I set about drafting purpose and ownership statements for the developer docs portal. These describe what the developer portal is and is not, and how co-ownership will be managed between docs and engineering.

Purpose Statement

To make this statement easy to read and skimmable, I organized content types for each site into bullet points. I also talked about what’s out of scope for the developer docs.

Ownership Statement

I wrote this to describe how developer content would be co-managed between docs and engineering going forward. I also aimed to keep this clear, concise, and skimmable.

Research & Recommendations

To figure out how to improve the site UX, I reviewed the developer docs of our competitors and industry leaders, including homepage elements, page layouts, and interactive elements. I took notes on what features made their docs UX great so we could adapt them.

At the end of this process, I had a 50+ page long Google doc of notes (which no one wants to read!). To make it easier for the team to review and give feedback, I condensed my recommendations into a one-page summary, divided into three sections:

UX/Site Layout
Information Architecture
Content

As I went through the project, I checked off recommendations that were acted on, including:

To make the purpose of the site crystal clear, I updated the site URL from docs.heap.io to developers.heap.io.
Designed and added a special ‘Heap developers’ logo to replace the traditional Heap logo in the top navigation.
Revised the confusing information architecture into a task-oriented taxonomy, which included installation, tracking, and identity management.
Updated top navigation headers with clearer titles and link to the engineering blog.

These recommendations were unanimously agreed to, so I set about getting into the revision phase.

Information Architecture Part 1

To start outlining the new information architecture, I separated out what would stay in the developer docs (as defined by our purpose statement) and what needed to move into the Help Center.

To support discussion about contentious hybrid docs, I set up a table listing out each one, whether or not it would be moved, and my reasoning for keeping or moving it. This provided a place for the team to share their thoughts on each one, and see other teammates’ feedback for consideration.

Here’s a sample of some of the rows of the table:

Note: SE stands for Solutions Engineer.

User Testing

Since the primary audience for the developer docs portal was developers, I booked time with Heap’s five newest engineering hires to conduct the following tests:

An open card sort where engineers sorted docs into groupings based on what made sense to them.

A tree test where engineers navigated a draft of the information architecture to complete tasks. To better understand where devs might go looking for information, I asked the engineers to have the following links open and use whichever resource made sense to them.

help.heap.io
docs.heap.io
A search engine of your choice

To come up with the list of tasks I’d ask them to complete, I checked in with customer-facing teams about the most common developer questions they get asked. Here’s the task list:

You’re looking for Heap installation instructions for Android.
You’re setting up Heap for the first time, and you’re looking for information on how to identify users across platforms and logins
You’re looking for information on how to make sure Heap does not capture certain PII (Personally identifiable information) to comply with data privacy legislation.
You have data that you know just can’t be right. Where do you look for information about this?

A highlighter test where engineers read samples of docs content and highlighted what was confusing to them. To make it easier to share ideas, I took notes during review sessions and added them to a copy of the doc on a shared screen.

I used Optimal Workshop‘s free plan (at that time) to conduct these tests with up to ten participants. I conducted sessions remotely and had the participants share their screen while I recorded so I could review their journey and take notes later.

Information Architecture Part 2

In total, twelve participants across different teams completed the card sort. I reviewed each result and noted the most common groupings:

Installation Guides
Tracking-related docs
User management docs
Changelogs/Release Notes
Platform-specific groupings (web, mobile, react native, etc.)

Two of these, installation guides and tracking docs, resulted in large categories which needed to be further broken up to make them easier to scan. I had some working sessions with stakeholders to design the final information architecture:

Native (later renamed Standard to align with inclusive writing guidelines) Installations
3rd Party Installations
Self-Hosted Installations (private)
React Native
Managing Identity
Custom Event Tracking
Custom Tracking on Pageviews
Advanced Configurations (private)
Changelogs

Feeling much more well-organized and intuitive than the first pass, this architecture draft was quickly met with unanimous stakeholder approval.

Content Migration

With the information architecture set, I was finally ready to move stuff around! I went about this in following order:

Moved 16 docs from the Help Center into ReadMe (mostly installation guides).
Moved 5 docs from ReadMe into the Help Center (all hybrid guides).
Reorganized content within ReadMe to based on our new architecture.

I also updated the developer docs subdomain from docs.heap.io to developers.heap.io. To avoid breaking a bunch of doc URLs from other places, I mapped out the old and new URLs in a spreadsheet, and shared it with engineering to set up dns records.

Last but not least, I queued up all of the docs that would be moving from one subdomain to another as drafts to make it easy to publish them all in their new locations in just a few clicks.

Launch Day

Based on average site traffic, I planned the launch day, where we would officially redirect all URLs, on a Monday morning at 6am PST. This gave me a whole day for urgent same-day fixes, and the rest of the week for less urgent site updates.

This was my launch day checklist:

PRE-LAUNCH

✅Queue up various docs to be moved as drafts in the Help Center and in ReadMe

✅Coordinate DNS certificate for URL redirect

DAY OF LAUNCH (6am PST)

✅Reorganize content in ReadMe and publish new articles

✅Publish new articles in the Help Center

✅Set up redirects in ReadMe and the Help Center

✅Delete all ReadMe articles moving to the Help Center

✅Delete all Help Center articles moving to ReadMe

✅Spot-check redirected URLs to ensure they are working

✅Check that nice reply (our thumbs up-thumbs down) survey works

✅Update top navigation links across heap.io and help.heap.io

✅Replace Heap icon with Heap Developers icon in the developer docs hub

✅Announce launch in Slack! 🚀

POST-LAUNCH

✅Update lower-priority doc URLs

✅Follow up on all announcement feedback

This list acted as a living project management tool as I quickly updated and checked off items, and kept all of us focused on the excitement of launch day, which went off without a hitch. 🎉

Outcome

As a refresher, here’s what the dev docs looked like before this project:

Post-launch, the new dev docs looked like this:

These updates made for a much nicer UX. Top navigation elements were clearly titled; the developers.heap.io subdomain and Heap developers icon clearly branded it as a developer hub; and a heap of new documentation was added and organized in the full sidebar.

Feel free to explore the current developer documentation for yourself at developers.heap.io.

Results

The new developer documentation portal was a hit, both internally and externally. Three months-post launch, we measured the project’s success as follows:

A decrease in thumbs-down 👎 clicks in the ‘Was this information helpful’ sections of our docs.
A decrease in write-ins referencing a poor experience with our support documentation.
Pageview analytics showed a spike in views of certain docs that were previously less discoverable via search.
Funnel metrics show an increase in conversions from the homepage to a dev doc.

The increase in views of several of the most popular developer guides, including the #1 most popular, Using Identify, inspired me to do a rigorous review and revision of these guides. My process for this is documented in Revision of a popular developer guide.

Organization & Role