Redesigning Our Docs – Part 1 – Why

This is the first article in a seven-part series of blogs that describe our most recent changes to the architecture and content of our documentation. 

In December 2018 we released a major iteration of our technical documentation. This is the first part in a series of posts that will retrace this adventure from the genesis of the project to what’s coming up next by describing the writing, UI/UX, and technical choices we made.

A key objective at Algolia is how well we improve Developer Experience (DX). Currently, there are around twenty people involved in the various squads regrouped under the DX umbrella, five of whom are dedicated to our technical documentation website.

Implementing Algolia in no time and with the least amount of friction as well as being able to get the most out of it is the core mission of the documentation squad. We see our documentation as a living thing. We will never be done with it, and it will continue to evolve as long as we have user problems to solve.

In 2017 we had our first big iteration involving a lot of people internally. We focused mostly on producing missing content and making a clear distinction between concepts and tutorials. When releasing it, we knew we had created a solid base on which to build, but we also knew that there was a lot more to do.

Discovering problems

At the beginning of 2018, six months after our last docs iteration, we decided to organize a full-day workshop with participants from various Algolia squads. At that moment we had a few intuitions regarding problems that we wanted to confirm. That day gave us the opportunity to conduct several interviews with various documentation users, and to reflect on their feedback as well as to map the user journey of someone trying to implement Algolia using our docs.

Eventually, at the end of the day, we uncovered several areas that needed improvements.

• Our users couldn’t grasp easily what Algolia was offering and what it meant to implement Algolia search when landing on our documentation. You had to choose from the start whether to read our concepts or follow one of our end-to-end tutorials.
• Our users were confused because our technical documentation was spread around 14 websites. We had one main documentation and a lot of different community websites for every project that popped-up the past few years at Algolia such as our InstantSearch libraries or our integration plugins. If you wanted to build a front-end implementation of Algolia you had to go back and forth between two different websites that followed different guidelines.
• We were using a lot of Algolia jargon that was not helping our users project themselves into our product. We were often using feature names as titles instead of guiding our users toward what the feature was used for.
• We were addressing all our audiences in the same way. We didn’t have a clear strategy about organizing and writing content to address both a non-technical and technical audience as well as handling the different skills or experience developers can have. Often it was resulting in a deceptive experience where people couldn’t find the content they should have easy access to.

Three key principles

To resolve those problems, we decided to completely change the philosophy behind our documentation, which resulted in three main choices:

A single website for all Algolia documentation.

We decided that algolia.com/doc should be our unique entry point for all Algolia technical documentation. We decided to start by bringing back InstantSearch, our front-end libraries that provide UI widgets. Now, in the same place, our users can go through all the steps of an Algolia implementation: from pushing their data to creating the kind of search and discovery they want on their website. More than just providing a better flow, this integration of the front and back end helps with the quality of the content now that they share the same architectural and writing structure.  

Moving away from a section-centric documentation

Instead of asking our users to choose between reading concepts or doing A-to-Z tutorials we introduced a sidebar navigation that walks them toward all the steps of an Algolia implementation and how to make the most of their search.  

Addressing all our audiences

Our technical documentation is not read by only one single profile but indeed many. From the decision maker who wants to quickly evaluate Algolia’s offer, to the curious who wants to know if X is possible with us; from the marketers who are trying to improve and fine tune their search to developers in the process of implementation. For the developers, some are newcomers looking to have their first Algolia implementation up and running within minutes and others are advanced users who go back and forth with the documentation when looking to improve their current implementation. And let’s not forget to mention Algolians themselves who internally rely on our documentation to serve our customers.

One major shift was to introduce the concept of hubs. No matter the profile of our users, every topic they arrive on when navigating with the sidebar should be accessible. Then, depending on who they are, they will have the ability to deep dive into our content. It could be reading some how-to’s if they are developers interested in copy-and-pasting some code snippets or exploring in-depth guides when looking to master a specific subject.

Those three key principles drove all later choices we made, whether it be the information architecture we put in place or the user experience we wanted to offer. Our next post in the series will dig more into the specific writing choices we made that serve both Technical and Non-Technical Readers.