Search by Algolia
How to increase your ecommerce conversion rate in 2024
e-commerce

How to increase your ecommerce conversion rate in 2024

2%. That’s the average conversion rate for an online store. Unless you’re performing at Amazon’s promoted products ...

Vincent Caruana

Senior Digital Marketing Manager, SEO

How does a vector database work? A quick tutorial
ai

How does a vector database work? A quick tutorial

What’s a vector database? And how different is it than a regular-old traditional relational database? If you’re ...

Catherine Dee

Search and Discovery writer

Removing outliers for A/B search tests
engineering

Removing outliers for A/B search tests

How do you measure the success of a new feature? How do you test the impact? There are different ways ...

Christopher Hawke

Senior Software Engineer

Easily integrate Algolia into native apps with FlutterFlow
engineering

Easily integrate Algolia into native apps with FlutterFlow

Algolia's advanced search capabilities pair seamlessly with iOS or Android Apps when using FlutterFlow. App development and search design ...

Chuck Meyer

Sr. Developer Relations Engineer

Algolia's search propels 1,000s of retailers to Black Friday success
e-commerce

Algolia's search propels 1,000s of retailers to Black Friday success

In the midst of the Black Friday shopping frenzy, Algolia soared to new heights, setting new records and delivering an ...

Bernadette Nixon

Chief Executive Officer and Board Member at Algolia

Generative AI’s impact on the ecommerce industry
ai

Generative AI’s impact on the ecommerce industry

When was your last online shopping trip, and how did it go? For consumers, it’s becoming arguably tougher to ...

Vincent Caruana

Senior Digital Marketing Manager, SEO

What’s the average ecommerce conversion rate and how does yours compare?
e-commerce

What’s the average ecommerce conversion rate and how does yours compare?

Have you put your blood, sweat, and tears into perfecting your online store, only to see your conversion rates stuck ...

Vincent Caruana

Senior Digital Marketing Manager, SEO

What are AI chatbots, how do they work, and how have they impacted ecommerce?
ai

What are AI chatbots, how do they work, and how have they impacted ecommerce?

“Hello, how can I help you today?”  This has to be the most tired, but nevertheless tried-and-true ...

Catherine Dee

Search and Discovery writer

Algolia named a leader in IDC MarketScape
algolia

Algolia named a leader in IDC MarketScape

We are proud to announce that Algolia was named a leader in the IDC Marketscape in the Worldwide General-Purpose ...

John Stewart

VP Corporate Marketing

Mastering the channel shift: How leading distributors provide excellent online buying experiences
e-commerce

Mastering the channel shift: How leading distributors provide excellent online buying experiences

Twice a year, B2B Online brings together America’s leading manufacturers and distributors to uncover learnings and industry trends. This ...

Jack Moberger

Director, Sales Enablement & B2B Practice Leader

Large language models (LLMs) vs generative AI: what’s the difference?
ai

Large language models (LLMs) vs generative AI: what’s the difference?

Generative AI and large language models (LLMs). These two cutting-edge AI technologies sound like totally different, incomparable things. One ...

Catherine Dee

Search and Discovery writer

What is generative AI and how does it work?
ai

What is generative AI and how does it work?

ChatGPT, Bing, Bard, YouChat, DALL-E, Jasper…chances are good you’re leveraging some version of generative artificial intelligence on ...

Catherine Dee

Search and Discovery writer

Feature Spotlight: Query Suggestions
product

Feature Spotlight: Query Suggestions

Your users are spoiled. They’re used to Google’s refined and convenient search interface, so they have high expectations ...

Jaden Baptista

Technical Writer

What does it take to build and train a large language model? An introduction
ai

What does it take to build and train a large language model? An introduction

Imagine if, as your final exam for a computer science class, you had to create a real-world large language ...

Vincent Caruana

Sr. SEO Web Digital Marketing Manager

The pros and cons of AI language models
ai

The pros and cons of AI language models

What do you think of the OpenAI ChatGPT app and AI language models? There’s lots going on: GPT-3 ...

Catherine Dee

Search and Discovery writer

How AI is transforming merchandising from reactive to proactive
e-commerce

How AI is transforming merchandising from reactive to proactive

In the fast-paced and dynamic realm of digital merchandising, being reactive to customer trends has been the norm. In ...

Lorna Rivera

Staff User Researcher

Top examples of some of the best large language models out there
ai

Top examples of some of the best large language models out there

You’re at a dinner party when the conversation takes a computer-science-y turn. Have you tried ChatGPT? What ...

Vincent Caruana

Sr. SEO Web Digital Marketing Manager

What are large language models?
ai

What are large language models?

It’s the era of Big Data, and super-sized language models are the latest stars. When it comes to ...

Catherine Dee

Search and Discovery writer

Looking for something?

facebookfacebooklinkedinlinkedintwittertwittermailmail

As a member of Algolia’s documentation team, I am often asked: “What tool are you using to build your documentation?” Of course, I answer the question, but I am often tempted to say that it’s probably the least valuable piece of information I can provide.

In this post, I am going to give you some of that information: what things you should care about when building your docs, and how those things will make the choice of tool the least important thing.

Documentation is usually composed of two big parts: the content and the software rendering it. You might have guessed where I am going with this: a quality README.md stored on GitHub can be far more efficient than over-engineered documentation that is well displayed but has issues with content.

The perfect tool is not out there

There are plenty of ways to build API documentation: static website generators (Jekyll, Hugo, Middleman), web frameworks (Ruby on Rails, Laravel, Django), dedicated doc tools (Docusaurus, Read the Docs, Sphinx), SaaS products (HelpDocs, Corilla), and that’s just the tip of the iceberg — there are so many more.

Depending on the one you choose you’ll have more or less flexibility, and more or less work to build and maintain. All tools will let you decide to a certain extent what you can do, and constrain you on the other end. I don’t believe there is a tool that can fit 100% of the needs in the long term. Documentation is something that needs to evolve, and you may have to change your tools several times as you outgrow certain constraints and have new needs.

Two years ago, we moved away from an internal tool that was aggregating content from GitHub ReadMes, a database and an external software managing our FAQ. This change took us full two months, and this is not counting the months of preparation prior to making the change.

By far the most time consuming task was to undo the formatting that our original tools required us to make. We had no consistency — some were Markdown, some were Markdown with custom extra features, some were plain HTML — and so while moving away from our previous tools, we had to edit thousands of files manually in order to unify everything.

Put the focus on making the tool fit your content (not the other way around)

Instead of focusing on which tool to use, a better option is to focus on whether you are doing everything possible to be as little software-dependent as possible. If you can respond to: “Can I switch easily to a new tool?” with a “Yes!”, then you are on the right track.

Build all components to be software-independent

While developing custom components, it’s good to keep in mind that they should be as little dependent on the software as possible.

Now, to answer that question from the beginning of the article…It’s been two years since we’ve been using Middleman for our main documentation. It’s doing the job, but it has some downsides and we’ve had to customize it quite a bit to our needs.

Here are some of the things that we added/modified:

  • Custom sitemap
  • Custom data files system
  • Custom snippet generation
  • Injections of custom metrics from Google Analytics for ordering purposes (for example the FAQ entries listed in https://www.algolia.com/doc/faq/ are the most viewed ones)
  • Ability to have a snippet file that can be auto-injected into any content file
  • An Algolia indexer

These customizations are done in a way that we can reuse them in any project. The modifications represent ~800 lines of custom code, which is rather small for documentation like ours, but it enables us to be able to move data files to any other software in a matter of days rather than months; this is us adapting the tool to our content.

Keep the content properly structured

What is even more important is how you organize your content so that you can re-organize it programmatically when needed, or transform it so it fits another tool.

The more structured the information is, the easier it is to:

– reuse it across different parts of the documentation
– change the organization system itself when needed

Two tips on that front:

  1. 1. Keep the content centralized

As mentioned earlier, our documentation comes from a system that was split in many different parts. Today, we have documentation in a single repo that you can run independently from the main website. This removes dependencies and allows us to focus on content and doc-specific modifications. It also give us the ability to iterate more quickly both on content and code parts.

  1. 2. Choose the right file format

Also very important is where you write your content. When using a static website generator, it is “the norm” to put all content inside the Markdown files. This can work for small docs, but when your documentation starts growing above hundreds of pages, with different types of content (guides, tutorials, reference, FAQ), and you are seeking consistency, using structured data files is a better approach.

That’s why at Algolia we documented all methods and parameters in yml files and not Markdown files. While we ended up with Markdown inside yml, which can seem a bit counter-intuitive, it is quite useful. It also allows you to reuse the content in different ways across the website.

API documentationThe two pages above are generated from the same yml file. When editing, this makes it very easy to keep consistency between different parts of the website.

API documentation

So by focusing in this way on content first – its needs, structure, maintainability – and then finding and customizing the tool, you can come up with a documentation that is easy and quick to evolve.

Once this is in place, a good next step is to have your team and customers contributing content. Which leads me to …

Bonus tip: get more contributions from the team and your customers

….and make those contributions as frictionless as possible.

There are a few actions we took to achieve this. When logged in as an admin, next to every section or code snippet we have an edit button that links to the correct file in GitHub, enabling admins to modify the content he or she is currently viewing.

Let’s take an example of a new developer joining the team. One of the first things they are going to do is learn about the product by working with it. The easiest route for that is using the documentation. While they are using it, they will notice typos, unclear bits, undocumented features…if they have to think about where to provide feedback, or how to edit the file, there is a high chance that they will do nothing and switch to another task.

And if that’s true for your team, it’s even more true for customers. It is very unlikely that a user who noticed a typo will look around the website for the support email to tell you that they found something wrong.

This is one of the reasons we have the following big form at the bottom of every documentation page and also accessible from every section of the content:

API documentationAPI documentation

The customer cannot miss it and that’s the point: if they see it once they know it’s there and the friction to contribute is low.

This also has the benefit of giving a great developer experience to our customers. When someone reports an issue on the doc, it goes straight to our regular support channel, where we have a good response time. We also fix and deploy a majority of the issues within the same day. A company that takes immediate actions on feedback gives an impression of care (one of our core values), and that’s exactly what we are aiming for.

When someone in the team creates or updates a PR, the change will be rebuilt and deployed to a new domain. To achieve that, we use the continuous deployment feature of Netlify, which brings several benefits. The main one is ability to preview, not only for the person doing the PR, but also for the person reviewing it, because they don’t have to deal with running the doc locally for small changes.

This is just one example of how to reach out to your readers. It creates a virtuous cycle where everyone (team + customers) contributes more and more, and enjoys doing it.

In short…

There are so many things to consider before worrying about which tool to use. Naturally, you do have to start somewhere and choose a tool, so I advise you to choose the one you and your team are most comfortable with. Just keep in mind to focus on the content, and adapt the tool to the content, not vice versa.

We’d love to hear your feedback and other experiences with this topic: @maxiloc, @algolia.

About the author
Maxime Locqueville

DX Engineering Manager

github

14-day free trial

Create a full-featured search experience in no time.

Get started
14-day free trial

Recommended Articles

Powered byAlgolia Algolia Recommend

API Documentation 2.0: From Browsing to Search
product

Peter Villani

Sr. Tech & Business Writer

ManoMano's "make or buy" decision grid
customers

Pierre Fournier

Chief Product Officer @ ManoMano

Indexing Markdown content with Algolia
engineering

Michael King
Soma Osvay

Michael King &

Soma Osvay