Co de Ha rm on ics

undusting the shelves


Technical Writing

Build a solution 

Start with a solution. Show the UI. Describe the components. And ask yourself – How did I get here? What have I done?!

(David Byrne)

What is a search experience?

An Algolia search experience is what an end user sees on the screen. Analyzing the end user experience helps you understand what we want to build, but it doesn’t help you understand the work that goes into building it.

Behind every search experience is another kind of experience: the Developer eXperience (DX) and the Business User eXperience (BuX). By providing great DX and BuX, Algolia ensures sure that its customers have it easy when developing a search experience. 

This document is about building a search experience. We organize it in the following way: we trace the main steps that all customers must follow to build a search solution.

Web Development

In the real world, there is no standard workflow for developing a website. Some companies will build the UI before plugging Algolia into its finished website. Others will start with their product data – seeing how to search and make sure that results are good, before building the search UI around that. Still others will do these in parallel. 

What matters is that all the necessary steps are done at some point in time.

There are 4 steps to build a solution: Continue reading “Build a solution “

The iWalk Framework


In this documentation, we trace the multiple layers of the iWalk code, to demonstrate how data from the Crawl database gets to the iSee and iKnow web applications. The other direction – such as saving data entered by the Crawl user – is not discussed, though it follows the same layered process in reverse.

There are at least seven layers between the data in the Crawl database and the information that appears in iSee and iKnow. Seven is the lucky number, but there are in fact many ways to enumerate the quantity of layers. We can say there are actually ten or fifteen layers because within each layer there are a number of sub-layers of equal importance and significantly different from the others so as to warrant separate distinction. Or we can say there are really only two layers: the Data / Business layer and the Presentation Layer. But all this is too abstract. What follows is a discussion of the seven major interlocking points along the data cascade.

Sometimes the layers build upon the previous layer – combining fields, adding new data, and reformatting information; other times, the layers are redundant, with nothing really changing in the exchange, the only purpose being that of wrapping functionality or decoupling iWalk from the Crawl database. In all cases, however, the layers are set up to be followed in a very precise, linear fashion with the momentous task of getting data from Crawl (Part 1) into the front end (Part 2).

The first five layers – Part 1 – require a good understanding of Crawl’s data and its functional concepts. The final two layers – Part 2 – require a good understanding of iWalk functionality and web development.

Each layer plays a small but significant role in the overall process. Be aware that each layer accomplishes its task using a different way of thinking, a different vocabulary, a different technology, a different set of data, and a different way of representing that data.

This complexity requires patience, concentration, creativity and adaptability, along with an ease in a number of distinct skills – both functional and technical. And time – there is an estimated two-year learning curve. So, be patient with the process. At times, this document might let slip some criticisms of the iWalk Framework, or frustrations with its code. These are personal to the writer and are not intended to be merely critical: they are added constructively to inform the reader that the learning process is difficult for everybody.

Continue reading “The iWalk Framework”

Exploring Technical Documentation Space

Awe. Like I am part of something insanely large. Touching infinity.

We travel in space. We are in space, and we and everything in it are moving.

To see this, you need to get out of the city and into the dark country. Lay back on the ground and face the sky.

It takes about 30 minutes for your eyes to adapt.

And then feel the movement.

Continue reading “Exploring Technical Documentation Space”

Create a website or blog at

Up ↑