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

 (interblah.net)
11 points par GN⁺ 2026-04-27 | 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 en même temps que le build de la documentation d’aide, afin que les images de la doc 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 remplit avec 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 contrôler aussi bien les UI ouvertes que les é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 la friction liée aux captures et recadrages manuels

La méthode des captures d’écran auto-actualisées

  • Le centre d’aide de Jelly (un service de boîte de réception e-mail partagée pour les équipes) en production est conçu pour capturer automatiquement des captures d’écran depuis l’application web en cours d’exécution et les mettre à jour à chaque nouveau build
  • La documentation est écrite en Markdown et, d’après l’article Self-updating screenshots, elle est transformée en HTML avec Redcarpet, puis rendue via des vues ERB dans une application Rails
  • Le Markdown contient des commentaires SCREENSHOT, qui embarquent ensemble des instructions comme le chemin cible, le mode de capture et un sélecteur CSS
    • <!-- SCREENSHOT: acme-tools/inbox | element | selector=#inbox-brand-new-section -->
    • La balise image placée 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 texte change légèrement, les captures d’écran existantes dans la documentation deviennent vite obsolètes ; ce flux réduit cette charge de mise à jour manuelle

Le pipeline de capture et ses effets sur la maintenance

  • En interne, une tâche Rake lance Chrome en mode headless via Capybara et Cuprite pour scanner les commentaires SCREENSHOT de tous les fichiers Markdown
  • Les tâches de capture d’écran sont regroupées par équipe et, pour une même équipe, le système est conçu pour ne se connecter qu’une seule fois 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 et peut, si nécessaire, la recadrer selon la hauteur
    • 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 capturer automatiquement aussi bien l’état qui apparaît après un clic sur un bouton que l’écran après une animation
    • <!-- SCREENSHOT: nectar-studio/manage/rules | full_page | click=".rule-create-button" wait=200 crop=0,800 -->
    • Le système clique sur le bouton pour ouvrir le formulaire, attend 200 ms, puis capture après recadrage sur une zone donnée
  • Il existe aussi des options supplémentaires, torn et hide
    • torn applique un effet de bord de papier déchiré à l’aide du CSS clip-path
    • hide masque temporairement les é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/ par sections telles que basics, setup et advanced
  • À l’étape de build, ces fichiers Markdown sont convertis en vues ERB sous app/views/help/, avec génération des breadcrumbs et de la navigation de section
  • Comme le développement des fonctionnalités et la mise à jour de l’aide peuvent être gérés dans la même base de code, il devient plus facile de maintenir la synchronisation entre le code et la documentation dans la même PR ou le même commit
  • Les cas particuliers comme les éléments nécessitant un scroll, les popovers qui s’ouvrent au clic, ou les recadrages destinés à éviter des parties inutiles ont demandé plus de temps à implémenter, mais une fois le système en place, le centre d’aide a pu être 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 la friction des captures et recadrages manuels

À lire aussi

1 commentaires

 
GN⁺ 2026-04-27
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