Search by Algolia
Vector vs Keyword Search: Why You Should Care
ai

Vector vs Keyword Search: Why You Should Care

Search has been around for a while, to the point that it is now considered a standard requirement in many ...

Nicolas Fiorini

Senior Machine Learning Engineer

What is AI-powered site search?
ai

What is AI-powered site search?

With the advent of artificial intelligence (AI) technologies enabling services such as Alexa, Google search, and self-driving cars, the ...

John Stewart

VP Corporate Marketing

What is a B2B marketplace?
e-commerce

What is a B2B marketplace?

It’s no secret that B2B (business-to-business) transactions have largely migrated online. According to Gartner, by 2025, 80 ...

Vincent Caruana

Sr. SEO Web Digital Marketing Manager

3 strategies for B2B ecommerce growth: key takeaways from B2B Online - Chicago
e-commerce

3 strategies for B2B ecommerce growth: key takeaways from B2B Online - Chicago

Twice a year, B2B Online brings together industry leaders to discuss the trends affecting the B2B ecommerce industry. At the ...

Elena Moravec

Director of Product Marketing & Strategy

Deconstructing smart digital merchandising
e-commerce

Deconstructing smart digital merchandising

This is Part 2 of a series that dives into the transformational journey made by digital merchandising to drive positive ...

Benoit Reulier
Reshma Iyer

Benoit Reulier &

Reshma Iyer

The death of traditional shopping: How AI-powered conversational commerce changes everything
ai

The death of traditional shopping: How AI-powered conversational commerce changes everything

Get ready for the ride: online shopping is about to be completely upended by AI. Over the past few years ...

Aayush Iyer

Director, User Experience & UI Platform

What is B2C ecommerce? Models, examples, and definitions
e-commerce

What is B2C ecommerce? Models, examples, and definitions

Remember life before online shopping? When you had to actually leave the house for a brick-and-mortar store to ...

Catherine Dee

Search and Discovery writer

What are marketplace platforms and software? Why are they important?
e-commerce

What are marketplace platforms and software? Why are they important?

If you imagine pushing a virtual shopping cart down the aisles of an online store, or browsing items in an ...

Vincent Caruana

Sr. SEO Web Digital Marketing Manager

What is an online marketplace?
e-commerce

What is an online marketplace?

Remember the world before the convenience of online commerce? Before the pandemic, before the proliferation of ecommerce sites, when the ...

Catherine Dee

Search and Discovery writer

10 ways AI is transforming ecommerce
e-commerce

10 ways AI is transforming ecommerce

Artificial intelligence (AI) is no longer just the stuff of scary futuristic movies; it’s recently burst into the headlines ...

Catherine Dee

Search and Discovery writer

AI as a Service (AIaaS) in the era of "buy not build"
ai

AI as a Service (AIaaS) in the era of "buy not build"

Imagine you are the CTO of a company that has just undergone a massive decade long digital transformation. You’ve ...

Sean Mullaney

CTO @Algolia

By the numbers: the ROI of keyword and AI site search for digital commerce
product

By the numbers: the ROI of keyword and AI site search for digital commerce

Did you know that the tiny search bar at the top of many ecommerce sites can offer an outsized return ...

Jon Silvers

Director, Digital Marketing

Using pre-trained AI algorithms to solve the cold start problem
ai

Using pre-trained AI algorithms to solve the cold start problem

Artificial intelligence (AI) has quickly moved from hot topic to everyday life. Now, ecommerce businesses are beginning to clearly see ...

Etienne Martin

VP of Product

Introducing Algolia NeuralSearch
product

Introducing Algolia NeuralSearch

We couldn’t be more excited to announce the availability of our breakthrough product, Algolia NeuralSearch. The world has stepped ...

Bernadette Nixon

Chief Executive Officer and Board Member at Algolia

AI is eating ecommerce
ai

AI is eating ecommerce

The ecommerce industry has experienced steady and reliable growth over the last 20 years (albeit interrupted briefly by a global ...

Sean Mullaney

CTO @Algolia

Semantic textual similarity: a game changer for search results and recommendations
product

Semantic textual similarity: a game changer for search results and recommendations

As an ecommerce professional, you know the importance of providing a five-star search experience on your site or in ...

Vincent Caruana

Sr. SEO Web Digital Marketing Manager

What is hashing and how does it improve website and app search?
ai

What is hashing and how does it improve website and app search?

Hashing.   Yep, you read that right.   Not hashtags. Not golden, crisp-on-the-outside, melty-on-the-inside hash browns ...

Catherine Dee

Search and Discovery writer

Conference Recap: ECIR23 Take-aways
engineering

Conference Recap: ECIR23 Take-aways

We’re just back from ECIR23, the leading European conference around Information Retrieval systems, which ran its 45th edition in ...

Paul-Louis Nech

Senior ML Engineer

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

ManoMano's "make or buy" decision grid
customers

Pierre Fournier

Chief Product Officer @ ManoMano

API Documentation 2.0: From Browsing to Search
product

Peter Villani

Sr. Tech & Business Writer

Indexing Markdown content with Algolia
engineering

Michael King
Soma Osvay

Michael King &

Soma Osvay