Stacy Taylor
Work About Blog

Auth0 Docs Information Architecture

Overview

A strong developer experience has always been a core part of Auth0’s DNA. Since our founding we have deliberately built a developer-first product and it continues to be a key part of our success to this day. Naturally, maintaining excellent developer documentation is an essential part of our strategy.

Auth0 Docs: Love ‘em or Hate ‘em

We had gotten a lot of feedback over the years from the developer community that our docs were fantastic and they were frequently cited as being a competitive differentiator.

Unfortunately, we also got a lot of feedback that our docs were terrible and difficult to navigate.

Discovery Interviews

To determine why some people loved our docs while other people hated them, I began conducting discovery interviews with our customers.

I learned that in general:

Developers who liked our docs

  • Had more pre-existing Identity and Access management (IAM) knowledge
  • Relied more on Google searches to find docs or community forum posts

Developers who hated our docs

  • Had less Identity and Access management (IAM) knowledge
  • Relied more on our sidebar navigation because they didn’t know the concepts well enough to choose good search terms
  • Ended up jumping back and forth between lots of open of tabs

Research Methodoloy

Discovery Interviews, conducted via Zoom

Participants

7 software engineers with varying levels of experience with Auth0

Process

Participants were interviewed about where they struggled with Auth0 docs, what they liked about Auth0 docs, and what they look for in developer documentation in general

Making Sense of the Mess

I performed a content audit of all 1000+ pages of docs, putting together a massive spreadsheet highlighting the problems in the IA. (I am precisely the kind of nerd who finds this sort of task highly enjoyable).

The biggest issue was that our sidebar navigation was manually generated, but our breadcrumbs were automatically generated based on the file structure of our CMS. Over time the two had diverged, leading to a number of mismatches.

two tree diagrams showing the sidebar navigation structure and the breadcrumb navigation structure
A tree diagram of the sidebar navigation (left) vs the breadcrumb navigation (right).

Roughly 25% of content was missing from the sidebar navigation, including some entire sections!

screenshot of a section missing from the sidebar navigation

The hierarchy of sections didn’t always match between the sidebar and breadcrumbs.

screenshot of a sections with mismatched hierarchy

Some content was in different sections in the sidebar vs the breadcrumbs.

screenshot of a section missing with mismatched content

75% of docs content had some sort of mismatch between the sidebar and breadcrumb navigation

Getting Stakeholders On Board

It turns out most people don’t find information architecture quite as exciting as I do. Go figure. I fought for this project because I believed that improving our IA would provide a solid foundation on which to build our docs.

Stakeholder Objection:

We should focus on SEO instead of IA because 70% of our traffic comes from search.

My Counter arguments:

  1. We didn’t know whether users were searching because that’s what they prefer or because our navigation was failing them.
  2. Our research showed that our target audience was more likely to rely on in-site navigation.

Stakeholder Objection:

Overhauling the IA will take too long and we may need to shift priorities partway through the project.

My solution:

I put together a project plan that we could roll out in phases and estimated the workload for technical writers and engineers for each phase.

Stakeholder Objection:

IA is boring and we should focus on something more visual and impactful, like a homepage redesign.

My solution:

Our visual design team was working on a rebrand. Incorporating branding updates while updating the navigation would make more of a splash.

Card Sorting and Wayfinding

I conducted open and closed card sorts for topics in our existing navigation menu to get a better understanding of participant’s mental models.

Most people fell into one of two groups:

Some users grouped topics by task, creating groups based on a user’s journey through setting up and configuring Auth0.

a screenshot of the card sorting results

Others grouped topics more by feature, creating groups around authentication users, securing their applications, or configuring different integrations.

a screenshot of the card sorting results

Research Methodoloy

Moderated open and closed card sorting conducted via Zoom

Participants

8 developers with varying levels of experience with Auth0 and 5 developers who were familiar with IAM but had not used Auth0

Process

Users were given 40 topics from our top-level navigation and asked to sort them into groups however they liked (open card sort). Next they were given the same topics and asked to put them into pre-selected groups (closed card sort)

To validate the results of the card sorting, I followed up with wayfinding tests for both a task-based IA and a feature-based IA.

Once again, different people had different mental models about how the topics should be grouped. Overall, however, more people were successful with the feature-based navigation and reported preferring that option.

Research Methodoloy

Unmoderated tree testing

Participants

Auth0 customers, non-Auth0 users, and Auth0 employees (to validate internally)

Process

Participants were shown two different versions of our sidebar navigation (task-based and feature-based) and were given five different topics to find using each version. Half were shown the feature-based version first and half were shown the task-based version first

"I preferred the [Feature-based] experience because the top bar navigation was segmented more and the headlines were much less ambiguous."

Design and Implementation

We made some small tweaks based on some of the feedback from our usability testing and then designed the new sidebar sections, which include Get started, Authentication, Manage Users, Customize, Secure, Deploy and Monitor, and Troubleshoot.

I paired with our frontend engineering team to iterate on the behavior of the new sidebar, how users would move from one section to another, and the mobile version of the navigation menu.

screenshot of the getting started page

Validation and Next Steps

Because there are so many potential paths through our documentation, it is difficult to quantify the precise impact of the information architecture change. However, the qualitative feedback we collected through follow-up interviews and our embedded feedback widget were overwhelmingly positive.

The next phase of this project was to create new landing pages for each new navigation category, which you can read about in my Landing Pages Case Study.

stacy.taylor@gmail.com