Arrivée à la gare : L'évolution de notre plateforme de documentation sur les API

Il y a trois ans, notre plateforme de documentation voyait le jour. Nous étions loin de nous douter de l'impact que certaines des décisions que nous avions prises à l'époque allaient avoir aujourd'hui. Par exemple, nous avons choisi de construire une application web open-source utilisant Ruby on Rails au lieu de générateurs de sites statiques pour les fichiers markdown, par exemple Jekyll, Middleman, etc.

L'histoire jusqu'à présent

Un framework web, tel que Rails, était le choix idéal parce qu'il ne présume pas de ce qui sera construit avec lui, ce qui vous donne la flexibilité de dire oui à tout.

Il y a trois ans, nous ne savions pas quelle serait la portée de notre projet en tant qu'entreprise d'API en pleine évolution. Il est difficile d'imaginer à quel point notre plateforme de documentation s'est développée, et il est encore plus difficile d'imaginer ce qu'elle pourrait devenir à l'avenir.

Aujourd'hui, l'outillage autour de la plateforme s'est considérablement développé. De la vérification automatique de l'orthographe à l'internationalisation, en passant par la vérification de la validité et du style des spécifications de l'API, la liste ne cesse de s'allonger.

Depuis sa création, la plateforme a alimenté Développeur API Vonage. Vonage API Developer a commencé sa vie en tant que Nexmo Developer, et au cours des années qui ont suivi sa création, il est devenu une partie de Vonage, le principal fournisseur de communications unifiées dans le nuage à l'échelle mondiale. En conséquence, les exigences et les attentes à l'égard de la plateforme se sont accrues de manière exponentielle.

L'histoire de l'évolution de la plate-forme ne s'est pas arrêtée là.

L'histoire continue...

Il y a six mois, une autre équipe produit de l'entreprise nous a contactés parce que l'outil qu'elle utilisait pour son site de documentation était arrivé en fin de vie. Elle était enthousiaste à l'idée de passer à une simple copie de la plateforme Vonage API Developer, mais malheureusement, elle n'était pas prête à être utilisée. Non seulement le code de la plateforme et la documentation de Vonage API Developer vivaient dans le même référentiel, mais certaines pages et fonctionnalités n'étaient pas conçues pour prendre en charge d'autres modalités de contenu propres à cette ligne de produits.

La complexité croissante des besoins en outils imposés à une seule application Rails monolithique, associée à un intérêt accru pour l'adoption de la plateforme par diverses lignes de produits de Vonage, nous a conduits à rechercher une meilleure alternative.

C'est grâce à cette recherche que nous sommes arrivés à la gare.

Qu'est-ce qu'une station ?

Au cours des derniers mois, nous avons séparé la prose du code de la plateforme. Nous l'avons remaniée pour en faire une plateforme agnostique en termes de contenu, capable de prendre en charge une pléthore de formes de contenu et de médias et d'autonomiser d'autres équipes dans l'ensemble de l'entreprise.

Station est un outil de plateforme. En définissant quelques fichiers de configuration et en indiquant le chemin d'accès à votre contenu, un site web peut être créé en une seule commande depuis le terminal.

Il est conçu pour fournir les services suivants dès sa sortie de l'emballage :

• Une solution pour créer rapidement des sites web à contenu textuel

• La possibilité pour chacun, quelle que soit son expertise en matière de programmation, de contribuer au contenu d'une manière simplifiée.

• Hautement personnalisable pour répondre aux besoins de chaque site grâce à un ensemble de fichiers de configuration

À la base, Station est une application Ruby on Rails (et Webpack) hautement personnalisée regroupée dans un Ruby Gem - un logiciel réutilisable dans le langage de programmation Ruby. Pour le développeur Rails expérimenté, cette application sera familière. Pour une personne ne connaissant pas Rails, il ne sera pas nécessaire d'apprendre les nuances du framework pour exécuter ou contribuer au contenu d'un site propulsé par Station.

Que fait la station ?

L'installation de Station prend en charge dès le départ la plupart des éléments que l'on peut attendre d'un site de contenu : rendu de contenu riche en médias, fichiers de spécification OpenAPI, tutoriels étape par étape, pages web créées sur mesure, cas d'utilisation, possibilité de fournir un retour d'information, recherche de contenu, et la liste est encore longue.

Non seulement le contenu, mais aussi la plupart des parties du site peuvent être personnalisés à l'aide de fichiers de configuration. L'extrait suivant correspond au fichier de configuration de l'en-tête et du pied de page du site.

C'est ainsi qu'ils sont rendus sur la page.

Quelle est la prochaine étape ?

Bien que nous soyons heureux d'avoir construit une plateforme robuste qui prend en charge n'importe quel site de contenu et qui alimente actuellement le site de documentation de deux de nos équipes, elle n'est pas encore entièrement disponible pour tout le monde.

Bien qu'elle soit open-source, la gem est publiée en utilisant le registre de paquets de Github, et les versions ne sont pas encore disponibles pour le public. Cependant, nous prévoyons de publier bientôt une version publique v1.0, qui sera disponible pour tout le monde via Rubygems.

Dans les prochains articles, nous parlerons de certains des outils mentionnés ci-dessus, que nous avons construits pour maintenir notre documentation et les spécifications de l'API ouverte au plus haut niveau.