Dans notre article précédent, nous avons discuté des étapes qui ont permis de définir ce que notre nouvelle documentation plate-forme pourrait être, ainsi que les objectifs techniques et les non-objectifs. Continuons la conversation avec les conceptions techniques qui sont entrées dans le nouveau système.
Go + React vs Next.js
Nous connaissons les problèmes, nous avons l’approbation, nous avons notre philosophie. Construisons un service !
La première approche que nous avons envisagée était la création de la nouvelle plate-forme en Go. Go alimente Snowsight, l’interface Web moderne de Snowflake. C’est performant, efficace, et nous avons des outils et une expertise avec la langue ici. Tous les bons facteurs.
Cependant, nous savions que la documentation aurait un certain niveau d’interactivité. Les barres latérales qui s’effondrent, la navigation escamotable, les onglets pour afficher plusieurs langues dans les exemples, étaient tous assez standard dans les systèmes de documentation que nous avons observés dans notre étude de marché. Nous savions également que nous voulions intégrer des fonctionnalités plus avancées telles que des exemples et des résultats interactifs, des diagrammes et même des systèmes de rétroaction.
Si nous devions utiliser Go pour construire la plate-forme, l’interaction avec le code à ce stade deviendrait insensée. Aller modèles serait responsable du rendu de la majeure partie du DOM, tandis que certaines divs (vides) seraient récupérées et détenues par ce qui serait probablement React côté client. Cela crée une expérience de codage désordonnée et risque de manquer du contenu dynamique aux moteurs de recherche.
Go est sorti. Y a-t-il un autre moyen ?
Une autre technologie largement utilisée chez Snowflake est React, l’interface utilisateur de Snowflake étant entièrement construite sur React. Mais React est une bibliothèque côté client. Ou est-ce?
De nombreux projets ont vu le jour pour faciliter le rendu de React côté serveur, en fournissant des réponses HTML entièrement formées lors du chargement initial, puis en optimisant les demandes ultérieures de mises à jour partielles sur les systèmes prenant en charge Javascript. L’une de ces options est Suivant.js.
Next.js a vraiment coché de nombreuses cases pour nous. Nous pouvons tirer parti des connaissances approfondies de Snowflake sur React tout en bénéficiant de la fourniture de contenu rendu côté serveur. En regardant notre liste restreinte de sites de documentation que nous avons appréciés, nous avons remarqué qu’une majorité d’entre eux ont également construit leurs systèmes de documentation sur Next.js.
Un autre avantage de Next.js est la façon dont il gère les transitions de page. Plutôt que de supprimer l’intégralité du DOM (ou de devoir coder manuellement la récupération et le changement d’interface utilisateur comme dans une application à une seule page), Next.js demande les données pour la page suivante, puis affiche le résultat. La récupération de données est extrêmement petite et généralement limitée à une seule requête (à l’exception des images que la page suivante pourrait nécessiter).
Lorsque les transitions de page prennent quelques fractions de seconde, les utilisateurs trouvent plus facile de se déplacer et d’explorer librement, ce qui est exactement ce que nous voulions que nos utilisateurs fassent.
Après quelques tests, une analyse comparative et une preuve de concept de base, nous nous sommes sentis confiants pour aller de l’avant avec Next.js.
TailwindCSS
La prochaine décision que nous avons dû prendre concernait notre approche CSS. Vent arrière a fait des vagues dans l’espace CSS, et nous n’avons jamais trouvé aucune des solutions CSS-in-React particulièrement bonnes, produisant généralement du code et des styles difficiles à raisonner qui deviennent généralement inflexibles avec le temps. Tailwind était quelque chose que nous avions exploré auparavant, et ce projet était une excellente occasion de l’essayer en production.
Gréer notre installation Next.js avec Tailwind CSS était assez simple, et avec un PoC rapide et en prenant un peu de temps pour apprendre comment Tailwind voulait fonctionner, nous étions plutôt convaincus. Nous avons fini par encoder notre directives de la marque dans le fichier de configuration de Tailwind pour une réutilisation facile – et des accessoires à l’équipe de la marque Snowflake pour nommer les couleurs ! Je suis éternellement reconnaissant que nous n’ayons pas eu à le faire. Nommer est difficile.
Nous avons découvert deux choses avec Tailwind. Premièrement, le passage au style Tailwind de CSS est généralement accueilli, au départ, avec scepticisme en voyant le modèle d’utilisation. La réaction initiale la plus fréquente semble être : “Pourquoi ne pas simplement utiliser des styles alors ?” Cependant, une fois qu’un développeur s’est installé et l’a essayé, nous avons constaté que les attitudes changent rapidement et de façon permanente.
Deuxièmement, Tailwind a également une excellente documentation ! Nous avons ajouté la documentation de Tailwind à notre liste d’inspirations car son contenu facile à rechercher et complet a joué un rôle déterminant dans notre adoption réussie de la bibliothèque. L’adoption de Tailwind aurait probablement échoué sans une documentation aussi complète et bien structurée. Nous sommes de grands fans !
Le système de construction est l’endroit où nous nous sommes principalement intégrés à Sphinx.
Pour exploiter à la fois Next.js et Sphinx, le système de génération commence par déclencher Sphinx pour générer la documentation. Cependant, nous avons appliqué une personnalisation — un modèle vierge. Sphinx utilise normalement un modèle qui inclut des éléments tels qu’un en-tête, un pied de page et une navigation. Cependant, nous voulions seulement que Sphinx compile le reStructuredText en HTML et laisse le reste du “chrome” à Next.js. Nourrir Sphinx avec un modèle vierge est assez simple :
{% block document %}
{% block body %}{% endblock %}
{% endblock %}
Les actifs compilés sont ensuite mis à la disposition de Next.js et utilisés pour afficher le contenu d’une page donnée. Toutes les directives Sphinx personnalisées et les rôles de texte ont été conservés, et après un peu de réimplémentation pour certaines classes CSS, nous avons eu la parité.
L’utilisation de Sphinx avait des avantages, mais elle comportait également ses propres inconvénients. L’un des plus gros problèmes avec lesquels nous nous débattons encore est le temps de compilation. Pendant le développement, il est souhaitable que les rédacteurs voient les modifications qu’ils apportent en temps quasi réel, ce qui est très similaire à la façon dont Next.js présentera rapidement les modifications lors de l’enregistrement lors de la création de Typescript. Cependant, Sphinx ne peut pas recevoir un seul point d’entrée de fichier, lorsqu’il compile, il doit tout ingérer.
Le cache de construction de Sphinx rend cela plus rapide, mais avec ~ 1800 pages, ce n’est pas inférieur à la seconde. Sphinx passe beaucoup de temps à essayer de compiler la table des matières et la navigation – toutes choses dont nous ne profitons pas dans le nouveau système, il semble donc y avoir des efforts inutiles.
À l’avenir, nous aimerions explorer la suppression de Sphinx et l’appel direct de docutils, dans l’espoir de pouvoir cibler des pages individuelles pour la compilation plutôt que l’ensemble du système. Nous utilisons certaines directives Sphinx personnalisées qui devraient être remplacées/réimplémentées, mais en raison de la réduction si importante du rôle de Sphinx, cela pourrait avoir un sens ultérieurement.
L’autre changement notable lié au système de construction est que nous en avons créé un ! Comme mentionné précédemment, le « système de construction » précédent était « inconfortablement manuel », en ce sens qu’il n’y en avait tout simplement pas. Les builds se déroulaient auparavant directement sur les machines de l’écrivain. Les ingénieurs reconnaîtront immédiatement le risque que cela présentait, mais cela représentait également un inconvénient pour nos écrivains. Compiler l’intégralité du site sur leurs machines locales (sans cache, ce qui était la pratique) a pris environ 45 minutes. Pendant ces 45 minutes, l’écrivain n’a eu qu’à patienter. Ils ne pouvaient pas itérer sur le code, et comme la construction prenait autant de ressources que leur ordinateur portable pouvait en fournir, il était souvent préférable de s’éloigner de la machine tout au long du processus de construction.
Le déplacement du processus de construction vers Jenkins a fourni un énorme avantage, non seulement pour s’aligner sur les meilleures pratiques d’ingénierie de Snowflake, mais aussi pour libérer du temps de rédaction. De plus, Jenkins avait accès à des nœuds avec beaucoup plus de CPU et de mémoire que les ordinateurs portables de notre écrivain, et ces machines ne seraient pas non plus soumises à la limitation du CPU comme le sont si souvent les CPU des ordinateurs portables. Les builds sont beaucoup plus rapides aujourd’hui, reproductibles et ne bloquent plus nos rédacteurs – un énorme gain de productivité !
Finalement, le moment est venu de déployer notre nouveau système auprès des clients. Nous avions un nouveau système en place que nous devions surveiller et nous assurer qu’il ne tomberait pas à la réception du trafic. Nous avions fait nos propres tests de charge, mais rien ne se compare au trafic réel.
Nous ne voulions pas proposer le nouveau site à tout le monde à la fois. Nous devions procéder à un déploiement progressif.
Pour minimiser les changements, nous avons continué à utiliser CloudFront devant le service. Mais le « service » n’était auparavant qu’un compartiment S3, qui n’offrait pas beaucoup d’opportunités pour rediriger le trafic de manière sélective. Heureusement, CloudFront offre Lambda@Edge. Lambda@Edge nous permet d’exécuter une fonction lambda à différentes phases du cycle de vie des requêtes CloudFront, ce qui nous permet de capturer les requêtes et d’attribuer le service d’origine que CloudFront doit utiliser pour une requête donnée.
Nous avons créé un algorithme de base pour attribuer et diriger le trafic vers la nouvelle ou l’ancienne expérience. Le jour du lancement, nous avons commencé par acheminer 20 % de notre trafic vers le nouveau service. En surveillant nos tableaux de bord, l’utilisation du processeur et de la mémoire était bien dans les limites acceptables. Après 2 heures, nous avons augmenté cela à 50%, puis à 100% encore 2 heures plus tard. Tout compte fait, nous avons migré tout le trafic vers le nouveau service en seulement 4 heures, sans interruption !
Impact
L’impact ressenti a été à la fois positif et immédiat. En plus de la grande migration technique que nous avons effectuée, la conception a été mise à jour, l’architecture de l’information a été réinventée, la recherche a été implémentée au fur et à mesure de la frappe et même une page d’accueil appropriée a été ajoutée (là où il s’agissait en grande partie d’une table des matières). Le sentiment trouvé dans des endroits comme LinkedIn et notre propre nouveau module de rétroaction ont mis en évidence une réception très positive du changement.
D’un point de vue analytique, les utilisateurs visitaient davantage de pages au cours de leurs sessions. Le contenu sous-jacent n’a pas changé, nous supposons donc que cela est dû au fait que les utilisateurs souhaitent explorer davantage le contenu. Certaines sections qui étaient auparavant dans la navigation mais cachées profondément dans la structure de navigation (comme nos notes de version), ont vu plus de 300 % de visiteurs augmenter.
La migration vers un système de construction automatisé a été une énorme victoire. Les écrivains ont pu rester plus concentrés sur l’écriture de contenu et moins impliqués dans la garde d’une sortie jusqu’à la production. En raison de la facilité avec laquelle les versions ont été rendues, nous sommes passés d’un processus de publication une fois par semaine à une publication deux fois par jour, avec des plans pour augmenter encore ce nombre et éliminer complètement l’implication humaine. Selon un compte, nous avons pris un effort de 10 à 12 heures pour une seule version jusqu’à 1 à 2 heures par semaine pour faciliter 14 versions. Cela a été une énorme victoire.
Du point de vue de la conception, il est clair que le nouveau système a été considérablement amélioré. Notre nouveau système de documentation reflète les directives modernes de la marque Snowflake et s’aligne mieux sur le langage visuel de notre produit. Le nouveau système prend en compte des préoccupations telles que la longueur de la ligne en ce qui concerne la lisibilité et offre une bien meilleure expérience de navigation dans son ensemble.
Et après
Nous avons beaucoup de travail devant nous ! Snowflake a généré beaucoup de contenu au fil des ans, et tout ne réside pas dans notre documentation et est donc difficile à trouver (et a souvent son propre langage visuel séparé). Créer un lieu d’accueil pour ce contenu au sein de la nouvelle plate-forme de documentation est l’une de nos premières priorités.
La deuxième priorité est d’améliorer notre présentation des tutoriel et contenu de référence. Ces types de contenu ont des exigences visuelles et d’interface utilisateur très différentes que notre système doit prendre en charge. Les didacticiels, par exemple, bénéficient d’une navigation ciblée de type “1-2-3” avec une interface utilisateur qui limite le nombre de distractions éloignant l’utilisateur de sa tâche. Pendant ce temps, le contenu de référence bénéficie de l’élévation des exemples et de l’ajout de contexte supplémentaire dans la navigation, comme le marquage des itinéraires comme GET, POST ou PUT, ou des fonctions comme Functions, Method ou Class (par exemple).
À partir de là, notre feuille de route devient un peu plus ambitieuse. Exemples interactifs/exécutables, authentification, préférences de l’utilisateur, contenu dynamique, en plus d’effectuer des recherches sur les utilisateurs pour comprendre où les utilisateurs ont du mal à trouver des réponses. En fin de compte, notre mission consiste à nous demander dans quelle mesure les utilisateurs peuvent apprendre à utiliser Snowflake, que ce soit pour un utilisateur novice ou expérimenté. Nous avons encore un long chemin à parcourir, mais j’espère que nos utilisateurs seront ravis chaque fois qu’ils revisiteront notre nouveau système documentaire!
to medium.com
Abonnez-vous à notre page Facebook: https://www.facebook.com/mycamer.net
Pour recevoir l’actualité sur vos téléphones à partir de l’application Telegram cliquez ici: https://t.me/+KMdLTc0qS6ZkMGI0
Nous ecrire par Whatsapp : Whatsapp +44 7476844931
Jeu de briques
Snake
Pacman
Bubble