Inspiration
Just like any other software-based company, we at Actindo want to provide documentation on our product as best as we can. As such we have documentation on most of our modules available on our website. However, as we are increasingly shifting our focus away from developing customer-specific solutions and plugins that only a few of our customers use, we need to open up our systems such that third parties can create and maintain those functionalities instead. As part of that we decided to move the documentation to a public GitHub repository to allow anyone else to contribute. In the process, we took this opportunity to drastically improve the user experience for anyone using the documentation with a reworked UI including a central search functionality.
What it does
Using the composable design of the Actindo platform we have integrated the Algolia service into the documentation release workflow. Within the workflow the markup files extracted from GitHub are converted into html files for display on the website as well as for upload to the Algolia API. In the frontend we have implemented a central search that calls the Algolia API to deliver precise and relevant search results quickly and seamlessly.
How we built it
As we are hosting the documentation on github we are able to use github webhooks to call our API whenever a change to the documentation files is accepted. We then automatically extract the markdown files from github and use the couscous generator to convert the files into html files such that they can be displayed in any webbrowser. The files are saved and additionally prepared for upload to the Algolia API by removing some redundant information and adding a proper title as well as tags for more precise results. The contents of the files as well as the additional metadata are then uploaded to our Algolia index.
Challenges we ran into
When we initially tried to use the central search, our results weren’t as precise as we would have liked. Given how heavily interconnected the articles within the documentation were, the actually searched for content didn’t stand out as much compared to other articles that frequently pointed to it. To reduce this effect, we decided to cut out the primary cause of this – link collection sections, that would point to relevant related articles – such that these would not be pushed to the Algolia API. Additionally, we took this opportunity to also prevent content like the common html boilerplate from being included as this section is the same for any file (and would also lead to unexpected behavior if someone were to search for text contained within that boilerplate). Additionally we reached the conclusion that our search results were not granular enough as the results could only point the user to an article rather than a specific article section. We solved this by splitting up the article into its different sections and only pushing those instead of the entire article. A user could then reach the same file via the search but would be pointed to the exact section they selected among the search results.
Accomplishments that we're proud of
As part of this project, we were able to seamlessly integrate multiple third-party software components to deliver the best experience possible to any user of the documentation section of our website. Especially given just how central the search functionality is to any good documentation we are proud of just how quickly we are able to deliver the most relevant results to any search query. Furthermore the entire process of publishing new or updated documentation to our website is entirely automatic meaning we can devote our time to developing new functionality for the Actindo Core1 platform instead.
What we learned
Developing software that is compliant with the MACH principles allows for seamless and effortless integration with any number of other third-party systems.
What's next
At the time of writing this the new documentation is actually not yet available online – getting it in the hands of our users is thus our highest priority. Beyond that we need to port over the existing documentation to GitHub so it remains available to our customers. Furthermore, given the wide variety of modules and extensions available for the Actindo platform we are still working on the documentation for quite a multitude of our plugins.
Log in or sign up for Devpost to join the conversation.