Insérer des captures d’écran qui se mettent à jour automatiquement dans la documentation

 (interblah.net)
11 points par GN⁺ 2 일 전 | 1 commentaires | Partager sur WhatsApp
  • Mettre en place un flux qui capture automatiquement des captures d’écran depuis une application web en cours d’exécution et les met à jour avec le build de la documentation d’aide, afin que les images restent à jour même après des changements d’UI
  • Des commentaires SCREENSHOT dans le Markdown contiennent des instructions comme le chemin cible, le mode de capture ou un sélecteur CSS, puis le processus de build les lit et les remplace par de vraies images
  • Une tâche Rake lance Chrome en mode headless via Capybara et Cuprite, regroupe le travail par équipe, se connecte une seule fois, puis parcourt plusieurs URL pour effectuer les captures
  • La capture prend en charge trois modes — element, full_page et viewport — avec des options comme click, wait, crop, torn et hide pour piloter aussi bien des UI ouvertes que des éléments inutiles
  • Avec un simple rails manual:build, la génération des captures d’écran et le build des pages d’aide s’exécutent ensemble, ce qui facilite l’alignement du code et de la documentation dans la même PR ou le même commit et réduit fortement les frictions liées aux captures et recadrages manuels

Une approche de captures d’écran auto-actualisées

  • Le centre d’aide de Jelly (un service de boîte mail partagée pour les équipes) est configuré pour capturer automatiquement des captures d’écran depuis l’application web en cours d’exécution et les remettre à jour à chaque nouveau build
  • La documentation est rédigée en Markdown et, sur la base de l’article Self-updating screenshots, elle est transformée en HTML avec Redcarpet, puis rendue dans des vues ERB de l’application Rails
  • Le Markdown contient des commentaires SCREENSHOT, qui embarquent des instructions comme le chemin cible, le mode de capture ou un sélecteur CSS
    • <!-- SCREENSHOT: acme-tools/inbox | element | selector=#inbox-brand-new-section -->
    • La balise image juste en dessous sert d’emplacement pour le résultat
  • Dès que la couleur de l’UI, la position d’un bouton ou le libellé change un peu, les captures d’écran de la documentation vieillissent rapidement ; ce flux réduit cette charge de mise à jour manuelle

Pipeline de capture et effets sur la maintenance

  • En interne, une tâche Rake lance Chrome en mode headless via Capybara et Cuprite pour analyser les commentaires SCREENSHOT de tous les fichiers Markdown
  • Les tâches de capture sont regroupées par équipe, avec une seule connexion par équipe avant de parcourir plusieurs URL
  • Trois modes de capture sont pris en charge
    • element : capture un élément DOM précis via un sélecteur CSS
    • full_page : capture la page entière, avec possibilité de la découper selon la hauteur si nécessaire
    • viewport : capture uniquement la zone actuellement visible dans la fenêtre du navigateur
  • Des options détaillées comme click, wait et crop permettent de récupérer automatiquement l’état affiché après un clic sur un bouton ou après la fin d’une animation
    • <!-- SCREENSHOT: nectar-studio/manage/rules | full_page | click=".rule-create-button" wait=200 crop=0,800 -->
    • Cela clique sur le bouton pour ouvrir le formulaire, attend 200 ms, puis recadre et capture une zone précise
  • Des options supplémentaires torn et hide sont également disponibles
    • torn applique un effet de bord de papier déchiré à l’aide de la propriété CSS clip-path
    • hide masque temporairement des éléments qui ne doivent pas apparaître à l’écran, comme une dev toolbar ou une bannière de cookies
  • L’ensemble du pipeline s’exécute avec une seule commande, rails manual:build, qui traite à la fois toutes les captures d’écran et le build des pages d’aide
  • Les sources de la documentation sont organisées sous public/manual/, dans des sections comme basics, setup et advanced
  • Lors du build, ces fichiers Markdown sont convertis en vues ERB sous app/views/help/, avec génération du breadcrumb et de la navigation de section
  • Comme le développement des fonctionnalités et la mise à jour de l’aide sont gérés dans la même base de code, il devient plus simple de garder le code et la documentation synchronisés dans la même PR ou le même commit
  • Les cas particuliers — comme les éléments nécessitant du scroll, les popovers qui ne s’ouvrent qu’après un clic, ou le crop pour éviter des zones inutiles — ont demandé davantage de temps d’implémentation, mais une fois en place, le centre d’aide est mis à jour beaucoup plus souvent
  • Il suffit de modifier l’UI, de relancer le build, puis de commit le résultat pour garder les captures d’écran toujours à jour, ce qui fait presque disparaître les frictions des captures et recadrages manuels

À lire aussi

1 commentaires

 
GN⁺ 2 일 전
Commentaires sur Hacker News
  • J’ai ajouté quelque chose de similaire avec une dérivation .#screenshots ; le coût de configuration initial est élevé, mais ensuite la maintenance est quasi nulle
    Puisqu’on génère les captures d’écran par programme, on peut produire en même temps les deux versions light/dark theme de l’app, puis les permuter selon prefers-color-scheme: dark
    Ce genre d’élément fonctionne aussi très bien dans un README GitHub : https://github.com/CyberShadow/CyDo#readme
    • Je suis tout à fait d’accord avec cette approche
      Sur mobile, j’ai utilisé Nix pour lancer un émulateur Android éphémère afin de générer les captures les plus récentes ; aucune préconfiguration n’est nécessaire et aucune donnée ne reste après exécution
      Dans mon cas, la configuration elle-même n’était pas si difficile ; le plus dur était plutôt d’avoir l’idée, et j’ai généré le code Nix d’un coup avec mon LLM préféré
      Mettre à jour les captures manuellement n’est pas la tâche la plus pénible du monde, mais le flux upload-apk + take-screenshot + transfer-back-to-PC + edit est toujours légèrement agaçant, donc au final je le fais presque jamais
  • Sur mobile, il faut absolument un défilement horizontal pour les exemples de code
    On pouvait plus ou moins deviner avec le contexte, mais c’était quand même gênant
  • C’est vraiment utile pour les projets mobiles
    Les app stores exigent des captures d’écran, mais comme il faut produire des images pour chaque taille d’écran et chaque localisation, ça devient vite pénible
    Avant, j’écrivais moi-même des scripts pour ça, et aujourd’hui des outils Fastlane comme https://fastlane.tools/ aident énormément
    J’utilise aussi Fastlane pour mon jeu de logique Nonoverse, et on peut voir des captures d’exemple sur sa page App Store : https://apps.apple.com/us/app/nonoverse-nonogram-puzzles/id6...
    J’ai aussi automatisé l’enregistrement des vidéos App Preview, y compris avec plusieurs scènes, et si ça intéresse des gens, ça pourrait mériter un article à part entière
    • Ça m’intéresse beaucoup, mais je ne vois pas bien si c’est un service payant ou une application OS qui tourne en local
  • C’est assez génial
    Pour les petits jeux casual que je fais en vibe coding, l’app commence toujours avec un CLI capable de tourner en mode headless, de faire du rendu sur texture hors écran, de prendre des captures et même de mesurer les performances
    Ça prend très peu de temps à intégrer, et ça crée aussi un point d’entrée pour qu’un agent puisse automatiser l’UI et inspecter les zones importantes
    Du coup, faire mettre à jour les captures par un agent devient aussi très simple
    Ce n’est pas aussi propre qu’une intégration complète dans le processus de build, mais je pense ajouter ça maintenant
    • Je fais exactement pareil
      J’ai aussi des arguments CLI pour le chemin de capture offscreen et le world pos/camera view vector, et je lance des benchmarks scriptés avec un format d’entrée textuel
      Ce format se compose de plusieurs lignes de segments nommés, avec pour chaque segment une durée de n ticks de jeu et les entrées de contrôle correspondantes
      Je m’en sers énormément pour faire des tests A/B sur le visuel et les performances pendant que je travaille sur le code du jeu
    • Je serais curieux de voir quelques liens vers ces jeux casual
      Moi aussi, je m’intéresse à quel point le vibe coding facilite le développement de jeux
      À l’époque d’Adobe Flash, l’écosystème du jeu indé était vraiment foisonnant, et depuis, peu de choses ont retrouvé ce niveau de facilité de développement
      Le vibe coding semble être le premier outil à dépasser vraiment ce niveau
    • Le ça prend très peu de temps à intégrer dépend quand même des cas
      Je me demande quel moteur tu utilises
  • Vraiment chouette
    J’aime particulièrement le fait qu’on puisse mettre des déclarations de captures d’écran inline dans un document Markdown
    Pour mon application desktop, j’ai mis en place une solution qui génère des captures dans plusieurs langues et en modes light/dark, supprime le bruit, et applique même des cadres de fenêtre Windows/macOS
    J’ai documenté ça ici : https://maxschmitt.me/posts/cakedesk-website-redesign#screen...
    Pour l’instant c’est encore un script séparé, donc assez pénible à maintenir ; je devrais regarder comment l’intégrer comme partie de markdown/mdx
    Très bonne source d’inspiration
  • J’ai eu besoin de quelque chose comme ça très souvent
    On pourrait presque en faire un mème du genre meilleur travail sur X que personne ne remarque
  • J’aime bien
    Il y a une fonctionnalité similaire dans https://github.com/zombocom/rundoc que j’ai créé
    L’objectif principal est la génération de tutoriels, donc il réinsère aussi dans le document la sortie des commandes exécutées
  • Je me demande si une approche en rendu temps réel ne serait pas possible ici aussi
    Par exemple, intégrer un aperçu live de l’outil dans un rectangle
    Si l’outil est léger, ça pourrait même être optimal visuellement, tout en reflétant aussi les réglages de rendu du navigateur, comme les paramètres d’accessibilité ou les extensions de l’utilisateur
  • En lançant des tests e2e, j’ai déjà pensé à générer aussi les captures d’écran en même temps
    Si la doc docs/ est dans le même dépôt, et qu’on ajoute un nouveau test lorsqu’une mise à jour de la documentation nécessite une nouvelle capture, ça semble assez bien s’imbriquer
  • Sympa
    J’ai commencé à construire exactement ça il y a quelques années, puis j’ai fini par l’abstraire vers quelque chose de plus générique, comme https://picshift.io/
    Cela dit, j’aime toujours beaucoup le cas d’usage des captures d’écran, et le nom d’origine de ce projet était ScreenSync
    • C’est bien, c’est bien fait, et je suis content de voir coexister ce genre d’approches variées