This is the third article in a seven-part series of blogs that describe our most recent changes to the architecture and content of our documentation. We focus here on user testing and the decision-making process behind our UX/UI choices. 

“Start with the problem. And don’t think about the solution until you know the problem you are trying to solve.”

These were the words spoken by Sasha Prokhorova, our Product Designer, as we went about redesigning our docs. 

For us, it was pretty obvious. While our docs were packed with great information, we were never sure our readers knew what to expect. There was an imperfect blend of text and example code, and we often mixed unrelated information on the same page. Furthermore, we did not provide easy navigation: the words we used in our menus, as well as the way we organized our subjects or displayed hyperlinks and calls to actions, did not always match our readers’ expectations.  

By the time Sasha arrived, we had already begun to solve the problem. We had redesigned our docs (at least on paper) to include a new menu structure, a changed hierarchy, and new page layouts to mark more clearly the difference between text and code. Said another way, we adapted our architecture and content to the different purposes of our readers.

Clearly, she had her hands full. She was facing a group of experienced developers and technical writers who had already formulated a clear idea of the problem and its solution.

What was she going to teach us?

Well, from that first day to the final delivery of her UX design, many surprises were in store for us. In the end, even if our original analysis of the problem and solution did not change dramatically, many additional facts and details came to the surface during the product design phase that forced us to reconsider some of our original assumptions. Which reminds me …

“Don’t act on assumptions,” she said.

Playing cards with the Product Designer

So Sasha tested our assumptions, introducing us to a number of UX tools:

• Card sorting helped us improve our new hierarchy and vocabulary. We asked random users to put our main subjects into their own wording and categories. While some choices confirmed our initial intuitions, some choices surprised us.
• Team workshops gave us time to reflect on the navigation and new page layouts. For example, we spent a full day designing one of our most critical page layouts. Each member of the team proposed a design and then we selected the best aspects of each design and put together a new page layout.
• Early user research with advanced users gave us exceptional insights into our current documentation – the good and the bad.
• In-person interviews with external users gave us an unbiased look at our new architecture.
• Unmoderated video user testing with anonymous users who were video-taped as they used our docs and responded to a user survey. This final round of tests provided us with invaluable insights on specific areas of content, offering insights into our vocabulary, content flow, topic approach, and the quality of our code and examples.

After six-months of collecting such user feedback, and going back and forth with different proposals, we delivered a final UX design – again, on paper – to our UI designer. The team – exhausted by the leg work as well as by the abstract nature of upfront design – were happy to finally move forward and see this hard work be given a vibrant third dimension by our keen-eyed UI designer.

The story thus moves on to the UI phase.

But… What makes great docs, from a UI perspective?

UI work isn’t only about making things pretty, it’s also about questioning the way we interact with any given website, and how visually we can make documentation clear and easy to use, and more natural. So after rewatching the user-interview videos we had recorded during the UX phase, we were able to empathize with our audience. For example, seeing navigation habits like the well-known Cmd/Ctrl-F to track down pieces of content on a page, or discovering developers’ appetite for simplicity (which springs from their use of not very UI-centric code editors and command-line consoles), convinced us that we needed to directly address these expectations—especially as Algolia is quickly becoming a tech leader.

Don’t try to guess, just ask.

UI can be approached in the same way as UX. You’ll have gut feelings about design choices, relying heavily on well-known UI patterns that you can rightfully assume are good practices. However, every website comes with a specific set of challenges, and in this case, some of them are way too important to ignore by relying purely on assumptions. From being able to switch programming languages and interact with code snippets, to handling versioning, to showcasing libraries made of complex components, …, we needed more information about what works and what doesn’t.

Luckily, developers love to explain why they use a specific service among others, so we tried to leverage that. While benchmarking other online documentation, and annotating a bunch of UI layouts and ideas, we launched a call for feedback on Twitter, which became a golden thread of the most appreciated documentation on the web. The response was phenomenal, we quickly learned what makes for state-of-the-art documentation: in-depth code examples, clear writing, good readability, learning curves, an inline console to interact with, and lots more. Extracting these answers, and tagging every argument, we started to expose trends that gave us clues about what resonates with people when using docs.

Hey #developers folks — I've got a request for y'all!
As we are constantly trying to improve our developer experience here @algolia, we want to empower you with the best docs possible.
👉 Would you share your favorite #documentation, and the WHY behind? 📄💻 pic.twitter.com/frNd19BHQb

— Nicolas Mzrd (@NicolasMzrd) September 3, 2018

Templating.

Our documentation is a collection of templates written in markdown language which are used to generate static web pages. So in a joint effort with the writing team, we started listing every kind of content we wanted to display, to see what they contain, and to attach high-level objectives and expectations to each one. A bit like Design System builders, you don’t start with a bunch of small components that hopefully work together as a whole; instead, you start with one template, focusing heavily on the objectives that you want to achieve, and making sure to avoid elements that discourage readers from learning. We were sure that, if well-designed, this page would set the global direction for our entire UI.

Taking the best out of online media.

Documentation is meant to host a massive amount of information and to cover complex topics that end up generating long pages with lots of different kinds of information. In that way, it was quite apparent that we needed to follow the standards of the media giants who are continually optimizing their webpages for optimal readability, to make it easier for its readers to consume huge volumes of information.

Therefore, as a foundation for the entire UI, we decided to start with one of our heaviest pages, which included tons of UI components like long text areas, alerts, warnings, side notes, code snippets, links to additional resources, a feedback form, and videos. The idea was that if we could find a design that worked for this page, it would work for 90% of the docs.

Usability over aesthetics – some best practices.

• Using a pretty narrow content-width to display short lines of text makes it easier to read than having full-width sentences that get lost in your eyes and tire you when going from one line to the next. Best standards are to keep within 600 and 700 pixels wide. We chose to stay in the middle, keeping an average of 150 characters per line.
• Our technical writers already did an amazing job at splitting their content, giving us small paragraphs to work with instead of delivering huge walls of text. Most users are fine with scrolling by now, especially developers who are big fans of Cmd/Ctrl-F navigation, and who prefer having everything on a single page. Let your content breathe, make it readable by understanding how your intended audience likes to read.
• To make long reading sessions comfortable, we went for a font size that is easy on the reader’s eyes. For example, users should not have to zoom in to read, especially not an audience that will skip over your product if it’s not up to their standards. Don’t let them break your layout because they feel the need to zoom in and out. Usability over aesthetics.
• We designed with accessibility in mind: do not rely on colors that attract attention; make sure your color scheme is bringing value and comprehension to color-blind people; and finally, check your main contrast ratio to ensure good readability even on low-resolution screens.

After dozens of tests, we finally reached a balance that was pleasing to developers and aligned with the branding of our company—thus, delivering a consistent message with the same tone and atmosphere of all our online content.

The component showcase challenge.

One of our greatest challenges, from a design point of view, was the InstantSearch component showcase. This showcase needed to accomplish several goals: allow users to experiment with the full library of interactive components; serve as a hub for the documentation behind each component; and highlight each component’s possible variations. In a bit more design-speak: it needed to work as a whole, while highlighting each component individually, and still visually make it clear that each component can have several variations.

Here is what we came up with during our kickoff meeting:

Literally, boxes in boxes in boxes. Though this first draft was definitely good at displaying the global information hierarchy, there were some challenges. There needed to be a way to know at first glance that it was a search demo, in order to encourage users to experiment. And it needed to clearly identify each component as a single entity with a precise goal.

We’ll spare you all the UI explorations. Essentially, we followed the Information Architecture choices we made during the UX phase, making sure that our design actually fit our audience’s expectations.

We see the world through our own eyes: work experiences, education, culture,… We are all biased in the way we perceive a design. To balance this, you need to dig into what your audience uses today to accomplishes its tasks, and to build on top of that. This is supposed to be an iterative process for everyone, not a total disconnect with everything they knew before. In other words, don’t re-invent existing and well-known patterns: build on top of existing ones, while trying to adapt them to your own use-cases, and making them more valuable for the final users—even though you didn’t necessarily invent something on your own.

 

Having addressed the problem of the whole, we focused on bringing subtle but obvious detail for each component and its variations. Splitting apart each component into individual containers was the first step to visually expose them individually. It was also important to add a small tab menu for each one, enabling users to switch between components and still interact with the demo as a whole. Finally, adding a hover state on each block solved the access-to-docs issue, thus avoiding flooding users with a tsunami of individual links constantly visible for each component.

Next steps: optimization and iteration.

Now that the new design has been rolled out, it’s all about keeping an eye on our important metrics, making sure the main issues were correctly addressed and that our decisions will impact the business positively.

We couldn’t say more about how important it is to keep track of all feedback—good or bad—to continuously map the overall experience and performance of your design. This enables you to know where the strengths and most-used areas are in your UI/UX. Even when the project is done, it is good to know which issues remain, and to have them simmer in the back of your mind as you passively think about solutions. At the end of the day, keeping some sort of customer journey up to date will help you identify and communicate quick wins, and clean up negative perceptions with only a few resources.

Stay tuned for more iterations—we have a lot of exciting changes coming your way! But before we go to the future, let’s get technical and see the UI’s new performance-driven CSS architecture.