Start building for free
Create a full-featured search experience in no time.
Sorry, there is no results for this query
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.
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.
To resolve those problems, we decided to completely change the philosophy behind our documentation, which resulted in three main choices:
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.
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.
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.