Information architecture
Fluent documentation site
Background
The next evolution of Microsoft's Design System, Fluent 2, is a more comprehensive system than its predecessor. Inclusive of a new design language, a new token system, and new assets, Fluent's next step means even faster product creation for its subscribers. If they could figure out how to use it.
I worked with a UX designer to define the initial information architecture (IA) of the Fluent 2 documentation site (docsite). The goal was to use the site as an avenue to solve user pain points about the whole design system. Therefore, it needed to be flexible and robust enough to handle the complexities of a large, multi-platform system. It also needed to be navigable and intuitive.
The info here is a deep dive into the process of creating the Fluent IA. Feel free to skip around.
What I did
Identify user pain points
Before setting out to map the site, it was important to understand what people needed from it. Various studies pointed to several opportunity areas for the Fluent Design System as it matured. Specifically, some pain points that I wanted to help address with the IA included:
Inconsistent terminology across the system
Unclear source of truth
Lack of comprehensive experience guidance
Lack of enforcement throughout the system
Audit the challenges
My next step was to wrap my arms around all of the information that already existed and where it lived. A quick mapping exercise pointed to a diverged documentation experience for design and development subscribers. A design system's main goal is to bridge the gap between design and development partners. Fluent's documentation was doing the opposite.
Moreover, none of the existing documentation considered a user who might wear a designer and developer hat. The current map would require that user to switch contexts and sift through multiple destinations to get a complete view of the system.
Worse, a decentralized system would be hard to enforce, therefore undermining the consistency design systems strive for. The complexity and potential for deviation multiplies if that user needs to build experiences for more than one platform.
With this information in hand and a clear idea of our users needs, I started drafting a list of information that the docsite had to account for.
Information extending from the system, including
Child documentation systems built off Fluent, called extensions
Fluent-adjacent tooling and resourcing
Information about the system, including
Differences between Fluent 1 and 2
Information on processes like contribution, feedback, and migration
Regular release information, like roadmaps and changelogs
Information in the system, including
The new Fluent design language specifics and rationales
New platform-specific Fluent components
High level experience guidelines and patterns, like empty states and errors
Information extending from the system
To establish Fluent as a hub and source of truth, it was important to make other resources and documentation accessible. This information didn't have to be embedded on the site but it had to be easily findable. I highlighted in the IA where it's useful to link off to other places to make our users' navigation journey easy.
Information about the system
Next, we defined useful information about the system.
Users need to know about changes to the system and what to expect. An About Fluent section offers information that changes often, like release notes and roadmaps.
A Get started section then provided instructional guidance for Fluent processes, like how to set up environments and contribute back to the system.
Many of these processes are still being built and aren't currently on the site. However, the IA sets a path forward for them once they're production-ready.
Information in the system - Design Language
My colleague drafted an initial IA in which all of the design language pages had an introduction followed by sections for each platform.
However, the rationale for the design language topics is platform-agnostic and only some pages have platform-specific information. I suggested simplifying the IA and including a tab switcher to indicate where there were platform specifics on each page, like different type ramps. That allows users to opt into the information they need.
On each page where this happens, I call out Fluent's principle of being native on every platform to reinforce the rationale.
Information in the system - Shared experiences
As the system matures, it will host high-level experience guidance that can be conveyed by many Fluent components. Cohesive patterns for communicating feedback and errors or building first-run experiences are integral to a good design system. Fluent doesn't currently have any of that information available. However, knowing its criticality and the appetite for it among users, I made sure to incorporate it into the IA.
Information in the system - Component pages
All of the information in the component pages is platform-specific, so the IA splits the component section by platform. Most of our users build for one platform at a time. Splitting the component section was a good way to surface the information makers needed to build their experiences.
Each component section has an overview page that serves multiple purposes.
Provides helpful resources for that platform that sit off the site
Provides visuals for each components
Provides a short description of what the component does without having to click into each page
Let people switch contexts
Though most users build on one platform, we didn't want a solution that left out the subset that might want to hop around. The interaction for switching between platform sections on the site had to be obvious, both in its location and its function. We looked for methods that were as frictionless as possible for switching contexts.
The site offers two options.
From the left navigation, a user can switch to a different platform's overview page.
The second option is context-specific. A user can switch to a related item on a different platform via a link at the bottom of a component page.
This treatment allows users to stay focused at a granular level instead of having to start the journey from the top.
It also allowed us to surface some quirks of the system (like naming inconsistencies across platforms) that might otherwise hinder findability.
Component page IA
The proposal for the Fluent 2 component pages works on a three tab system. The first tab, Usage, frontloads all the information a user needs to decide whether this component is right for them. This information is pertinent to both design and development users and helps makers answer these questions:
Is this the right component?
Should I opt for something else?
How do I use it correctly?
The information on the Usage tab is prominent because it leads to the most usable and accessible implementation of that component.
The Style and Implementation tabs each offer reference information. The style tab includes redlines and padding information, as well as token allocations. The Implementation tab provides prop tables and code guidance. Users don't need to make decisions on this information, but it is integral in their creation process.
Outputs and outcomes
The team and I created a sitemap that was the baseline for the first implementation of the Fluent 2 site.
The led to various outcomes
While building the site, the team was aligned on goals with a shared understanding of the system
After site launch, users are asking fewer questions about where to find information and what the source of truth is
This mental model is spreading throughout the organization as a standard for documenting design systems, creating even more predictable and navigable patterns
