Red Hat: improving product documentation
This was a team project done in collaboration with Red Hat—an industry leading enterprise software company. The goal was to understand how Red Hat customers learn, so we can improve Red Hat’s ungated product documentation experience.
Date
Spring 2023
Duration
4.5 months
My Role
UI/UX Designer
Table of Contents
Project Goals
- Solve existing pain points.
- Enhance the documentation experience to better assist customers seeking to learn.
- Produce a Figma prototype demonstrating the improved experience.
- Provide actionable recommendations for Red Hat's UX team to consider.
Research: understanding how their customers learn
Red Hat wanted us to investigate how their customers learn their products; they wanted to know whether Red Hat's product documentation experience needs improving. We interviewed interns, fresh graduates, and experienced developers to understand how they learn products their jobs. The interviews were composed of two parts. The first part was a traditional Q&A, and the second part—which I was in charge of—was an observational task analysis of interviewees navigating the existing experience.
Current product documentation landing page
Findings
Product documentation is essentially an instruction manual; it's often a developers first point of reference. Thus, it is crucial that the experience is straightforward and easy to use. We approached this project afraid that we might uncover big navigational issues with the documentation experience; however, users we observed had no problems navigating the site. They successfully found the products we ask of them, and rated the experience as rather straightforward.
We discovered that developers all have their unique approaches to learning. Less experienced developers preferred learning with different mediums (i.e. videos, podcasts, walkthroughs), but more experienced developers preferred learning through documentation only. But one thing holds true for all developers: time is of the essence.
Example user persona: an experienced developer
Example user/customer journey map: an experienced developer without much Red Hat experience
Prototyping: not reinventing the wheel
Overview
The design phase was guided by the following three “how might we...?” questions narrowed down from our research:
- How might we incorporate multimedia into product documentation?
- How might we show code snippets/samples relevant to the learner?
- How might we improve the landing page experience?
Based on the research, the existing experience didn’t need an overhaul. Users had no issues navigating the site, so it didn't make sense to make drastic changes; however, there were still opportunities for minor changes to speed up navigation, augment the experience for developers of all levels, and better guide readers. Thus, I had three goals as a UX designer during the design phase:
- Give users a choice on how they want to consume information. Developers learn differently, so the documentation experience should reflect it.
- Add the features that were repeatedly asked for during the research phase: a search bar, more code samples, and better version management.
- Test the ideas/implementations.
-1.png)
Low-fidelity prototype
Low-fidelity prototyping
The low-fidelity prototypes aimed to address the three “how might we...?” questions. I added a search bar to filter the products on the landing page in response to the task analysis. Quick access links, dependencies, and version control were added. The goal: speed up navigation, and clarify prerequisite knowledge and version compatibilities. A new code sample hub was added because developers raved about the importance of code samples.
The most important addition to the experience was the giving developers a choice of how they want to consume information. Since developers learn differently, our team wanted the new experience to cater to a wider audience. Visitors can toggle multimedia (i.e. video, podcasts, images) on or off depending on their personal learning preferences.
The most important addition to the experience was the giving developers a choice of how they want to consume information. Since developers learn differently, our team wanted the new experience to cater to a wider audience. Visitors can toggle multimedia (i.e. video, podcasts, images) on or off depending on their personal learning preferences.
View prototype
↗
Testing #1
We tested the low-fidelity prototypes with developers that had less than two years of professional experience. Our testing revealed that the new search bar sped up navigation by 20%. Developers liked the way they can quickly change the product version, and appreciated the new code samples hub.
However, the addition of a multimedia toggle, which we called “enhanced mode” at the time caused problems. The idea of the toggle was positively received, but developers struggled to find the toggle; they were also left dumbfounded by the ambiguity of "enhanced mode".
However, the addition of a multimedia toggle, which we called “enhanced mode” at the time caused problems. The idea of the toggle was positively received, but developers struggled to find the toggle; they were also left dumbfounded by the ambiguity of "enhanced mode".
-1.png)
High-fidelity prototype
High-fidelity prototyping
The high-fidelity prototypes addressed the issues with the low-fidelity prototype. Placeholder items in the low-fidelity prototype were replaced with components from Red Hat's PatternFly design system. The biggest issue I tried to fix was the confusion surrounding the “enhanced mode” toggle. After some testing, I settled with a binary toggle paired with the “show multimedia” label. A few minor changes were also introduced, such as a chapter outline at the top of each documentation chapter and an additional resources section at the end of each page.
View annotated screens
↗
View prototype
↗
Testing #2
The second round of user testing was mostly directed at the “enhanced mode” toggle. The testing was moderated, and we worked with experienced developers (5+ years). I ran a comparative study where I showed participants three options—a dropdown menu, a checkbox, and a toggle. I had them choose their preferred implementation. Developers unanimously chose the binary toggle as the best option; They liked the toggle being named “show multimedia” instead of "enhanced mode". Testing also demonstrated that developers, regardless of experience, wanted multimedia to be shown by default. They argued that hiding multimedia as default felt like something was being taken away from them, and they would be less likely to notice that multimedia is available to them.
-1.png)
Revamped documentation page (left: multimedia hidden; right: multimedia shown)
Next steps
The next logical step in this project is to employ the changes and collect quantitative data. The data will indicate whether the toggle is being used by site visitors. Due to time constraints, we never had the opportunity to explore ways to better demonstrate the link between all the Red Hat products. Currently, each product’s documentation stands independently. However, the reality is many Red Hat products are interconnected and developers may not be aware.
What I learned
Often times when I think UI/UX design, I think of redesigns and overhauls. A good metaphor would be a house makeover. However, this project was a reminder that sometimes only minor changes are needed. And as a designer I should embrace that. Small changes can still make a major difference; a small change can be the difference between a good and great experience.