Joy-to-use Tech Docs

Usability & Navigation

Site navigation is the #1 issue for Appian Docs.

—user survey (n=118)

—user survey response

Improving the navigation structure of the site is a major opportunity for increased customer satisfaction and user trust.

95% of Appian Docs users describe the “ideal docs site” as “like a book, with chapters and topics.”

On a website, this hierarchy is reflected through breadcrumbs, a feature supported by many modern docs sites.

Unfortunately, Appian Docs uses collections (illustrated below) and cannot support breadcrumbs at all.

I adapted and focused instead on unifying and enhancing the site's information hierarchy. With product knowledge from my PO, Google Analytics data on the site's traffic, and observation studies on how users interact with the site, I identified the highest-impact and most-used components on the site. I targeted the topmost Navigation Bar, the left-rail Content Browser, and the right-rail Table of Contents (TOC).

Improving Site-Wide Navigation

The topmost navigation should provide users with enough information so that they know where to go. Additionally, this navigation should scale with the site—prepared to support more content without sacrificing understandability.

The outdated navigation bar grows vertically as new releases are added, cluttering the interface and is difficult to parse.

My UX collaborator and I reviewed 20+ documentation sites for their approach to navigation menus with large numbers of links/items.

Competitive Analysis

• Full-width expansion, making use of the viewport’s entire width.
• Group related content together within the navigation bar.
• Include context/description for links/items.

Adopting a similar approach to Appian Docs, I also introduced nesting levels for increased scalability.

But how can we ensure navigation remains usable on smaller screens?

About 15% of Appian Docs users (~20,000 people) access the site on tablets or mobile devices. 

On smaller screens, visible items are enlarged and lose context (a “parent” item, for example).

To address this, I added breadcrumbs to the navigation bar. Breadcrumbs strengthen users’ mental map of the navigation hierarchy and eliminates the need to remember their precise location within this menu.

Validation: User Testing (n=6)

Participants: 3/6 daily Docs users, 2/6 monthly user, 1/6 new user
Task: Navigating to a specific page about an Appian product of interest.
Results:

• 6/6 participants used the Navigation Bar to find the page.
• 6/6 participants found the page of interest.
  
• 2/6 mentioned using search as a secondary navigation.
• Participants found “breadcrumbs” helpful.

"On my phone, as I click I forget where I am, so breadcrumbs are really helpful."

Final mobile Navigation Bar design, ready for developer hand-off

In-page Reading Experience Make-over

“I’m not sure how these [navigation rails] are different from each other, so I usually don’t use them.”

I began the redesign with a competitive analysis of 10+ sites and a design audit of both components.

Competitive Analysis

• Collapsible content browser that allows users to focus on current page.
• Indicate hierarchy between items through consistent use of margins, paddings, and colors.
• TOC is expressively named ("On this page", "In this article", or "Contents").

Design Audit

• Unclear information hierarchy due to the rails' similar designs.
• Varied font sizes, weights, and high-contrast colors contribute to visual overload.
• Lack of design analogies. The TOC does not explicitly elicit "scroll" behavior with the page, leading to user surprise.
• Low-impact title (with the current page's title) leads to user confusion about its purpose.

Design Decisions

Consistent font sizes but with varied weights, colors, and indentation communicate information hierarchy across articles and topics.

Component design for Content Browser

Lower-contrast colors and controls to collapse the Content Browser help reduce visual overload.

Lower-contrast colors and controls for collapsing Content Browser

Employ the scrollbar analogy for the design of the TOC component, signaling its purpose (vertical scrolls that allows navigation to contents on the page).

Scrollbar analogy employed in TOC

Validation: Mid-fidelity User Testing (n=4)

I wanted to verify that the visual design of these components align with users’ expected interactions. I observed the participants' interactions on the site as they explore it freely.

Familiarity with Appian Docs: 2/4 daily users, 2/4 monthly users
Task: Explore the prototype freely, acting on their impulse
Results:

• All participants recognize that the TOC and Content Browser support navigation, but for different purposes.
• 4/4 participants expect clicks on the TOC will allow scroll to different sections within the page.
• 3/4 participants expect the TOC to scroll and collapse/open sub-sections as they scroll on the page.
  
• 4/4 participants expect clicks on the Content Browser will lead them to different pages. 

Validation: High-fidelity Mobile User Testing (n=6)

Familiarity with Appian Docs: 3/6 daily users, 2/6 monthly user, 1/6 new user
Task 1: Exploring content related to the current page.
Task 2: Finding specific information on the current page.
A/B Options:

Option A: "Dropdown"

Pros:

• Intuitive dropdown interaction for Content Browser.

Cons:

• Crowded top-right touch area.
• Version dropdown within a page may suggest it only affects the current page, not the entire product topic.

Option B: "Sidebar"

Pros:‍

• More accurate representation of how version dropdown affects contents.

Cons:

• Less common interaction pattern (secondary sidebar), may be difficult for older users.
  
• Less discoverability for version dropdown

Results:

Users prefer Option B.
‍The more interactive design is not the more effective.

Option A: "Dropdown"

More interactive, but allows for greater margin of error in interaction and less accurate understanding of Appian release versions. Lots of questions about versioning and "Didn't mean to click on that!"

Option B: "Sidebar"

Less interactive, but communicates better touch targets and conveys more accurate understanding of Appian release versions. We hear multiple "I like this more now that I've clicked on it and found out where the version dropdown is."

"I like this [Content Browser] more! It's a better mental model."

—user testing participant

Accessibility Review

Design Audit

• Overlay modal has no visible exit controls.
• Pressing “ESC” key does not exit the overlay modal.
• Content behind the modal retains interactivity.

Outdated Zoom-in functionality does not support keyboard access and lacks visible controls.

This accessibility issue does not just affect screen-reader users, but any users who rely on keyboard shortcuts to view diagrams/screenshots to understand complex concepts—a crucial and common scenario for enterprise offerings.

Validation: Low-fidelity Elicitation Studies (n=4)

• Participants: 4 participants, aged 20-45.
• Task 1: I show each participant a static prototype of Appian Docs and ask them to gesture how they would zoom-in to the image.
• Task 2: I show each participant a static prototype of Appian Docs and ask them how they would exit the zoomed-in view.
• Results: Participants' expected interactions are compiled below.

Participants' expected interactions to zoom-in and exit overlay modal.

The final design employs the most commonly expected interactions. I worked closely with developers to ensure that accessibility features were included in the design spec for development.

Design Decisions

• Visible button with “Expand image” label allows the user to open the overlay with enlarged image. Clicking on the image or using [Keyboard “focus” + “Enter”/”Return”] will also open the overlay.
• Overlay includes the “exit” button on top right. Overlay can also be exited by clicking on the greyed-out area outside of the overlay.

Interaction Design

The code box on Appian Docs is one instance of high-traffic components that are functional, but a pain to use.

Imagine: you are visiting Appian Docs to find code snippets that fit your use case. As you parse through long pages, you miss the code snippet a few times and become overwhelmed by the visual clutter. You'd find yourself thinking “can’t wait to get this over with.”

Design Audit

• "Copy" icon is uncommon and unintuitive.
• Close "stacking" between code and the "copy" icon can occur.
• Visually overwhelming due to high color contrast and lack of white space.
• Lack of motion design contributes to overall "janky" feel.

I analyzed 5 competitors' docs sites for their approach to find out: what makes a code box a joy to use?

Competitive Analysis

• Utility bar above the code section, separating functionalities (copy, reporting errors, switching to dark mode, etc.) from contents.
• Unified color scheme, with minimal color contrast between the code section and the utility bar.
• Common design for “copy” icon.
• Employ motion design and subtle visual indicators for interactions.

With insights from competitive analysis, the new code box is a complete UI refresh, featuring:

Design Decisions

• Updated low-contrast color scheme.
• More common (expected) "copy" icon.
• Anti-clutter tooltip design with thoughtful hover-state transitions.
• Programming language indicator.

Validation: High-fidelity Usability Testing (n=4)

Participants: 2/4 in non-technical roles (limited familiarity with Docs), 2/4 software developers (intermediate familiarity with Docs).
Task: Typical task in Appian Designer that requires programming.
I observed participants interacting with the code box as part of this task.

All 4/4 users found the code box intuitive to use.

When prompted, most found the design utterly unremarkable (“I guess it just looks like that…”)—but one participant appreciated the language indicator, as they were unfamiliar with programming.

"I wasn't sure if I'm copying the right language example for [code snippet], so [new design] really helps."

This suggests that what seems boring to experienced users can be reassuring and user-friendly for new users. Boring can imply ease and trust.