Notre parcours vers la création d'un index consultable avec Algolia et NodeJS

J'ai fait équipe avec l'ingénieur Starschema Full Stack Soma Osvay pour écrire sur un projet qui me tient à cœur : la documentation pour les développeurs. Soma et moi espérons que vous apprécierez cet article où nous couvrons le cas d'utilisation et les défis et la mise en œuvre proposée par Soma.

Chez Starschema, nous avons beaucoup de projets que nous avons réalisés dans le cadre d'une consultation avec la documentation de démarquage . Lorsque nous prenons en charge ces solutions existantes ou que nous souhaitons développer un nouveau projet, nous souhaitons souvent parcourir toute la documentation. Nous n'avons actuellement pas de solution, ce qui nous coûte des heures de travail puisque nous devons faire ce travail manuellement.

Cas d'utilisation

Nous devons être en mesure de rechercher des projets liés à des sujets spécifiques pour vérifier les spécificités de la mise en œuvre, obtenir des idées à partir du code, et bien plus encore. L'équipe des ventes a également besoin d'une solution pour déterminer le type de projets que notre équipe a réalisés pour certains sujets et être en mesure de le communiquer rapidement aux clients potentiels.

Ce serait également formidable d'avoir quelque chose comme un Stack Overflow interne pour nos développeurs puisque nous effectuons beaucoup de travail technique approfondi dans Tableau. Les chefs de projet doivent également être en mesure de déterminer quels employés ont travaillé avec certaines technologies afin d'obtenir rapidement et facilement des réponses à leurs questions.

En bref, nous devons pouvoir rechercher nos propres projets en fonction des attributs suivants :

1. Technologies utilisées (langages de codage, bases de données, etc.)
2. Mots clés du projet (tags)
3. La documentation du projet elle-même, telle que les instructions d'installation, la documentation technique, etc.
4. Période de réalisation du projet

Tous ces attributs existent dans les fichiers de démarquage de la documentation interne - nous avons juste besoin d'un moyen de les rechercher.

Plan de mise en œuvre

Le plan consiste à utiliser une CLI NodeJS comme preuve de concept qui :

1. Grattez les principaux référentiels publics GitHub et récupérez le fichier README Markdown (qui représentera finalement nos projets internes)
2. Stocke les fichiers de documentation dans Algolia avec les informations de base du projet (titre, langage(s) de programmation, tags, etc.)

L'interface de ligne de commande contiendra des arguments avancés de journalisation et de ligne de commande pour faciliter l'utilisation. Nous voulons également l'héberger sur le Web afin que les gens puissent l'essayer.

Défi

Le plus grand défi à relever est la taille de l'enregistrement - Algolia n'autorise nos enregistrements qu'à 100 Ko au maximum. Cependant, la plupart des fichiers de documentation de démarquage sont beaucoup plus volumineux. La solution est que nous devons diviser les fichiers de démarquage en plusieurs parties dans l'index. Nous devons également nous assurer que lorsque nous recherchons quelque chose, un seul projet n'apparaît qu'une seule fois, même s'il est divisé en plusieurs enregistrements.

Heureusement, Algolia a une fonctionnalité distincte qui nous permet de dédupliquer ces résultats très facilement.

Implémentation de l'indexeur

Pour rendre l'utilisation de l'indexeur aussi simple que possible, j'ai choisi de créer une CLI comme mentionné ci-dessus. Après avoir fourni les arguments requis, l'outil initialisera automatiquement le référentiel, supprimera tous les enregistrements existants et configurera les paramètres de pertinence.

L'outil est alimenté par une API GitHub simple qui récupère le nombre demandé de référentiels supérieurs, extrait toutes leurs métadonnées et télécharge le fichier README. Il filtrera également les référentiels auxquels il manque un propriétaire ou un fichier README, nous donnant les meilleurs résultats. Enfin, il convertira également le contenu de démarquage en HTML pour un rendu plus facile dans le frontend.

Pour contrôler la taille de l'enregistrement, l'outil divisera automatiquement les fichiers README de plus de 50 000 caractères en enregistrements supplémentaires. De cette façon, les enregistrements ne deviendront pas trop volumineux, mais un enregistrement devrait toujours servir presque tous les référentiels. Il synchronisera ensuite ces informations avec Algolia 100 enregistrements à la fois afin que nous puissions respecter leurs recommandations de traitement par lots, comme décrit ici dans la documentation.

Implémentation frontale

Pour servir de point de départ, j'ai profité de la bibliothèque create-instantsearch-app publiée par Algolia et lancé un passe-partout InstantSearch.js. À partir de là, j'ai pu ajouter des widgets supplémentaires fournis par InstantSearch.js tels que la pagination et le sélecteur de taille de page qui fonctionnaient très bien.

Comme nous avons également collecté les métadonnées du référentiel avec le démarquage, nous devions également personnaliser le composant hits pour inclure ces informations supplémentaires. Souvent, les métadonnées sont aussi importantes que la description de la bibliothèque afin que les développeurs puissent voir en un coup d'œil s'il s'agit d'une bibliothèque populaire, qui l'a publiée, les balises et bien plus encore. J'ai également ajouté des facettes afin que les utilisateurs puissent filtrer par langage de programmation, balises ou combien de fois il a été forké.

La dernière pièce du puzzle consistait à ajouter le bouton "Ouvrir la documentation" vous permettant de lire rapidement et facilement le contenu de démarquage du référentiel dans une fenêtre contextuelle sans quitter l'application. Si l'enregistrement sur lequel nous cliquons comporte plusieurs lignes, il chargera automatiquement les enregistrements supplémentaires et les concaténera dans l'affichage - génial !

Conclusion

Ce projet était un test amusant et m'a vraiment montré à quel point Algolia est flexible pour différents cas d'utilisation comme le nôtre. Les widgets prêts à l'emploi m'ont fait gagner beaucoup de temps lors du prototypage et avoir des résultats pertinents dès les premières frappes est super impressionnant. Je pense aussi que ce serait super intéressant si nous pouvions exploiter la puissance d'Algolia Recommend si nous pouvions générer suffisamment d'événements à partir d'utilisateurs cliquant sur des projets en interne.

Vous pouvez voir une démonstration en direct du projet de test GitHub ici , avec un bouton qui vous configurera avec les informations d'identification de démonstration par défaut pour afficher notre index. Intéressé par le code d'indexation backend ? Vous pouvez le trouver ici sur GitHub !

Également publié ici.