14-day free trial
Create a full-featured search experience in no time.
Sorry, there is no results for this query
Feb 22nd 2019 engineering
This is the second 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 the writing choices.
Many docs are written by and for developers. This works fine when your readers are developers who require straightforward, immediate information, like details about method parameters, code snippets, and error messages. However, when your company grows not only in customer base but by offering more business-related features, then dictionary-style text – or what is often called reference material – does not sufficiently cover the broader needs of building complex applications with multiple features and best practices. Best practices, for example, are critical: correct and efficient feature implementation is the only way that clients get the best out of what your company has carefully designed.
Algolia’s technical writing team has gone in this direction. Our documentation now covers a broad range of subjects, like synonyms, intent detection, NLP, analytics, personalization, and merchandising – all of which impact business as well as implementation. Our readers include not only developers, but CTOs, product managers, and marketers. We therefore need to support readers with different goals and profiles.
But every reader has the same goal: to learn about what Algolia offers and to make the best of their investments in both time and money.
Change was needed. We were not giving every subject the best coverage, and related information was not always grouped together coherently. Some readers wanted more focus on problem-solving, with examples, code, and technical detail; others wanted more clarity on features, with use-case analysis and benefits presented in clear, non-technical language.
To add to that, our documentation was not always user-friendly: it was jargon-filled, with text too sparse and low-level to be easily readable by all of our readers. The language we used sometimes alienated or intimidated our readers.
We addressed these concerns by including more accessible word choice and more storytelling in the content flow of each page.
Essentially, we decided to take a progressive approach, where everything – navigation, page structure, and language – starts from the familiar and gets progressively more complex, with clear signs along the way where to find code or to go more in-depth.
In the end, we believe our readers – whatever their purpose or profile – can come to our docs and get what they need.
Our first concern was language. Previously, we were not using words and phrases that everybody could understand. We relied a lot on jargon, which had the dual problem of assuming that everyone who read our content was highly technical and also good at reading our minds.
Take a word like replica. On its own, it means nothing to a first-time reader. It’s an Algolia-centric term: we own its meaning when we speak it. We use it in a very specific way that differs from its dictionary meaning. However, we need to use it: there’s no better word for capturing the idea of “a duplicate index that sorts results differently from other indices”. Granted, that sentence needs a lot more context – we need to define the terms “index” and “sorts”, otherwise, database administrators might come away with the mistaken understanding that an Algolia index sits on top of a database table, whereas in Algolia, an index is the data source itself, and sorting is a complex subject at Algolia, requiring its own page. You get the idea – we stopped taking anything for granted.
Good word choice follows the general recommendation that technical documentation use plain language. Our approach, therefore, starts with a common word before using a more technical term. A word needs an introduction, like a character who needs to be introduced before speaking or acting.
We try to define all terms. Some words require only a single word or phrase, like “attributes (key/value pairs, fields, information)”; others need a bit more context, like “Searchable attributes (a select group of attributes used for searching as opposed to displaying, filtering, or ranking)”. And some terms (relevance) need a full page (that required days of research and interviews with key Algolians, including our founder and CTO). But the result was worth it, because all of these terms are core concepts and many of them have multiple nuances depending on the context.
We considered the first paragraph of every page as an effective method to engage the reader. We asked – What do we want every reader to see when they land on one of our pages? Our answer was: A simple statement or description of the problem that the page was going to solve.
This problem-solving approach is consistent with using a clear vocabulary and defining terms. We believe that going directly into a problem puts the reader into a familiar setting and encourages them to continue reading, to find out how to resolve the problem. I say “problem”, but it could be a need or a common use case. Problem-solving speaks directly to any reader interested in solving their own problem. This approach can also appeal to the curious who is looking to opt into Algolia or to enhance their existing solution.
We tried to stick with one example per page and to thread that example into the general treatment of the problem/solution. We were aware that not every example applied directly to a reader’s particular situation, but we thought that a well-chosen example would nonetheless enable every reader to see how a specific problem gets resolved and be able to adapt it to their own situation. In fact, one page presented several examples, from movies to recipes, to actors, to books, and back to movies, with some repeating characters, like Charlie Chaplin, Harry Potter, and blueberry pie. The page finally finished by combining movies and actors in the same index. For this page, each example was important to explain a different aspect of the same storyline, which was that formatting your data has many nuances and requires different choices.
Going beyond the first paragraph, we considered the whole page – What do we want our readers to see? We came up with three kinds of content: a summary overview, a deeper understanding, and an implementation guide with code examples.
Before designing the pages, however, we needed to address two main concerns:
We had thus given ourselves a difficult but not impossible task: to satisfy two very different concerns – on the same page, with the same words and same conditions. The solution we came up with was two-fold:
In short, we wanted to give all readers, developers included, a clear description of a problem, with examples and descriptions of the feature(s) used to address it, and obvious navigation for more info or code. To do this, we set up a 3-page approach:
As stated at the outset, what we are describing here is a progressive approach to documentation that is present at every level – architectural, page format, content flow, and words and phrases. Every part of our documentation starts with the familiar and moves towards the more technical and complex, with the hope that the familiar will drive the understanding of the technical and complex.
Algolia has worked hard over the years to offer features based in common sense. We wanted to mirror that common sense in our documentation.
The redesign of our docs involved more than just a rewrite. Our next article focuses on the look and feel of the new architecture, more specifically, on the decisions we made during the UX and UI phase.
Create a full-featured search experience in no time.
Powered by Algolia Recommend