Outil de documentation gratuit pour les équipes d'ingénierie à distance

Trupeer AI est l'outil de documentation pas-à-pas pour les équipes d'ingénierie à distance qui ne peuvent pas se pencher pour demander à la personne à côté d'elles. Un ingénieur senior enregistre l'explication une fois (comment fonctionne réellement le pipeline de déploiement, pourquoi ce service gère les tentatives de cette manière, ce que fait la partie complexe de la base de code et pourquoi elle est complexe), et Trupeer AI génère à la fois une vidéo et un document d'ingénierie écrit lors de la même tâche. D'autres ingénieurs, travaillant dans des fuseaux horaires différents et des bureaux différents, regardent et lisent de manière asynchrone. Les équipes d'ingénierie distribuées ne souffrent pas tant de l'absence de fichiers README que de l'absence de l'explication derrière le README, qui est la partie qu'un ingénieur senior met un après-midi à écrire et pour laquelle personne n'a jamais de temps disponible.

• Un ingénieur senior enregistre le guide pas à pas. La vidéo et le document d'ingénierie écrit arrivent ensemble.

• Conçu pour le flux de travail asynchrone et multi-fuseaux horaires dans lequel vivent déjà les équipes d'ingénierie distribuées.

• Traduisez la documentation dans plus de 65 langues pour les équipes d'ingénierie réparties aux États-Unis, en Inde, en Europe et en LATAM.

• S'intègre aux côtés du wiki existant de l'équipe, du dépôt de code et des documents d'API. Ne remplace aucun d'entre eux.

• Mettez à jour en réenregistrant l'étape modifiée. L'explication de l'architecture ne devient pas obsolète.

Ce que Trupeer AI produit pour les équipes d'ingénierie

Un ingénieur senior ouvre un enregistrement d'écran. Il explique pas à pas le déploiement du service de production, le débogage de l'environnement de staging ou le choix de conception de la file d'attente de messages fait par l'équipe en 2024. Trupeer AI s'occupe de la post-production. Les tics de langage disparaissent. Des effets de zoom mettent en valeur la commande du terminal, la zone de l'IDE ou le tableau de bord que l'ingénieur suivant doit examiner. Un projet de vidéo et un projet de document d'ingénierie écrit apparaissent au même endroit, avec des captures d'écran et des étapes numérotées intégrées.

Les sorties sont livrées au format vidéo MP4 et document PDF ou Word. Le document est ce que l'on lit dans un wiki ou ce que l'on colle dans Notion ou Confluence. Les vidéos sont ce que l'on regarde dans le centre d'aide, intégré dans un ticket Linear, ou partagé via un lien de Page partagée. Les deux proviennent du même enregistrement sans second passage. Le kit de marque applique des diapositives d'introduction et de fin spécifiques à l'équipe d'ingénierie, et le glossaire personnalisé gère les noms de services internes, les noms de composants d'infrastructure et les acronymes que l'IA n'orthographierait pas correctement autrement.

Comment fonctionne l'outil de documentation d'ingénierie en trois étapes

Trois étapes couvrent l'ensemble du flux : enregistrer ce que l'ingénieur senior a déjà en tête, laisser l'IA générer les deux formats, et distribuer via un lien que le reste de l'équipe peut trouver quel que soit le fuseau horaire.

Étape 1 : Enregistrer l'explication

Démarrez un enregistrement d'écran dans le navigateur, dans l'IDE de l'équipe d'ingénierie ou sur le terminal. L'ingénieur senior explique le travail de la même manière qu'il le ferait lors d'un entretien en tête-à-tête avec une nouvelle recrue. Cinq à dix minutes d'enregistrement suffisent généralement pour expliquer une architecture ou pour un guide de déploiement. L'IA travaille sur ce qui est enregistré, de sorte que l'ingénieur senior n'a pas besoin d'écrire un projet ou de préparer des diapositives.

Étape 2 : L'IA génère la vidéo et le document d'ingénierie écrit

Les tics de langage et les moments du type « laissez-moi trouver ce fichier » sont supprimés. Des effets de zoom mettent en valeur les parties de l'écran qui comptent (le chemin du fichier, la sortie du terminal, le diff dans la revue de PR). Un projet de vidéo et un projet de document d'ingénierie écrit apparaissent ensemble dans l'éditeur. Le glossaire personnalisé identifie les noms de services internes et les acronymes de composants avant qu'ils ne soient mal transcrits.

Étape 3 : Personnaliser, traduire, partager

Appliquez le kit de marque pour que les documents internes à l'ingénierie soient cohérents dans toute la bibliothèque de l'équipe. Traduisez dans les langues dans lesquelles l'équipe travaille réellement : l'espagnol pour le bureau de Mexico, l'hindi pour l'équipe de Bangalore, le portugais pour São Paulo. Distribuez via un lien de Page partagée qui se trouve dans le wiki, dans le document d'intégration de l'équipe, ou collé directement dans les fils Slack où les ingénieurs peuvent le trouver sans interrompre leur flux de travail.

Qui utilise cet outil de documentation d'ingénierie

La personne qui ouvre cet outil est généralement un ingénieur principal, un responsable de l'ingénierie ou un directeur technique au sein d'une organisation d'ingénierie hybride ou axée sur le télétravail, comptant des collaborateurs répartis sur au moins deux fuseaux horaires. Ils l'ouvrent lorsqu'une nouvelle recrue arrive et que le README ne suffit pas, lorsque l'équipe prend une décision architecturale non évidente dont il vaut la peine d'enregistrer le raisonnement, ou lorsque le guide d'astreinte a besoin de réellement expliquer quoi faire à 3 heures du matin au lieu de simplement lister des commandes. Certaines équipes l'utilisent systématiquement pour chaque décision de conception majeure ; d'autres n'y ont recours que lorsqu'un manque d'explication se fait sentir.

Le même flux de travail se retrouve dans différents rôles. Les responsables DevOps et SRE enregistrent les rétrospectives d'incidents et les guides d'infrastructure qui sont partagés avec l'ensemble de l'organisation d'ingénierie. Les responsables de l'ingénierie enregistrent des guides d'intégration pour les nouvelles recrues afin que les mêmes questions ne soient pas posées en messages privés chaque semaine. Les directeurs techniques enregistrent les décisions d'architecture afin que les futurs ingénieurs sachent pourquoi un système est conçu ainsi. Les directeurs de l'ingénierie enregistrent les déploiements inter-équipes (une nouvelle plateforme interne, une migration de service, un changement de processus de déploiement) qui nécessiteraient autrement une réunion générale de 50 personnes à laquelle personne ne souhaite assister.

Types de contenu d'ingénierie gérés par cet outil

Les types de contenu qui reviennent le plus souvent : les guides d'architecture et de conception (pourquoi ce système est ainsi), les guides de déploiement et d'infrastructure (comment livrer en production, comment faire un retour arrière), les guides d'intégration (la présentation de la base de code, la configuration du développement local, le parcours de la première PR), les rétrospectives d'incidents et post-mortems (ce qui s'est passé, ce que nous avons appris, ce que nous modifions), et les explications de revues de code (le pourquoi derrière une PR non évidente). Trupeer AI gère chacun d'eux avec le même flux allant de l'enregistrement au document. Le format s'adapte : un guide d'exploitation requiert des étapes numérotées avec des captures d'écran, une explication d'architecture nécessite la vidéo avec le résumé écrit, un parcours d'intégration demande les deux.

Pour la documentation d'ingénierie plus largement, Trupeer AI comble la couche d'explications que les outils de wiki textuels laissent vide. La documentation en ingénierie logicielle se divise généralement en trois couches : les documents de référence générés par le code (Sphinx, javadoc, OpenAPI), le contenu du wiki d'équipe (Confluence, Notion, Slab), et les guides enregistrés par des humains. La plupart des équipes d'ingénierie disposent de la première couche car elle est automatique, et de la deuxième car quelqu'un a été payé pour l'écrire. La troisième couche (la documentation système en ingénierie logicielle, la documentation de projet d'ingénierie, la documentation interne en ingénierie logicielle) est celle qui est toujours en retard. Trupeer AI rend la production de cette troisième couche assez rapide pour qu'un ingénieur senior puisse le faire un vendredi après-midi entre deux réunions.

Où se situe Trupeer par rapport aux wikis, aux outils de documentation de code et aux générateurs de documentation d'API

Trupeer AI ne remplace pas le wiki de l'équipe. Confluence, Notion, Slab, GitBook et le wiki d'équipe interne continuent de faire ce qu'ils font. Trupeer AI produit le contenu d'explication enregistré qui est intégré dans ces wikis sous forme de Page partagée, aux côtés des articles écrits que l'équipe rédige déjà.

Trupeer AI ne remplace pas non plus les générateurs de documentation d'API. Swagger, Stoplight, Redoc, Postman et toute référence OpenAPI générée automatiquement continuent de gérer les documents de référence au niveau des points de terminaison. Trupeer AI se situe à une couche différente : l'explication humaine de la façon dont l'API a été conçue, de la manière de l'intégrer concrètement, et des pièges que la documentation de référence ne met pas en évidence. Une bibliothèque de documentation d'équipe d'ingénierie a généralement besoin des deux, la référence générée automatiquement et l'explication enregistrée par un humain. Trupeer AI ne gère que la seconde ; la première reste là où elle se trouve. La même logique s’applique aux outils au niveau du code comme Doxygen, javadoc et les systèmes de commentaires intégrés, que Trupeer AI complète plutôt que de concurrencer. Pour la gestion de la documentation d'ingénierie et la documentation technique plus largement, cela signifie que l'équipe ajoute une couche d'explications sans supprimer ce qu'elle possède déjà.

Mises à jour et traduction pour les équipes d'ingénierie réparties dans le monde entier

La documentation d'ingénierie vieillit plus vite que ce à quoi les équipes non techniques s'attendent, car les systèmes sous-jacents changent chaque semaine. Une modification du pipeline de déploiement rend obsolète le guide d'utilisation du trimestre dernier, une refonte d'architecture rend le document de conception trompeur, un service renommé rend le guide d'intégration déroutant. La plupart des équipes gèrent cela en laissant silencieusement les documents dériver et en répondant aux questions sur Slack chaque fois que quelqu'un tombe sur le document désormais obsolète. Trupeer AI gère les mises à jour en réenregistrant uniquement le segment modifié. L'IA ne traite à nouveau que cette partie, la vidéo et le document d'ingénierie écrit sont tous deux mis à jour sur place, et le prochain ingénieur qui consultera le wiki verra la version actuelle.

Pour les équipes d'ingénierie réparties dans le monde entier, la traduction réduit les frictions dont personne ne parle lors des réunions quotidiennes. La même explication d'architecture parvient à l'équipe de Bangalore en hindi, à l'équipe de Berlin en allemand et à l'équipe de São Paulo en portugais, à partir du même enregistrement source, au cours de la même semaine. La traduction s'applique à la fois à la voix off de la vidéo et au document d'ingénierie écrit, le kit de marque, le glossaire et le texte à l'écran étant conservés. Associer ce flux de documentation d'équipe d'ingénierie au générateur de SOP de Trupeer AI couvre à la fois les guides destinés à l'ingénierie et les procédures opérationnelles standard interfonctionnelles que les équipes d'ingénierie transmettent à d'autres parties de l'organisation.