Automatisch aktualisierte Screenshots in Dokumente einfügen

 (interblah.net)
11 Punkte von GN⁺ 14 일 전 | 1 Kommentare | Auf WhatsApp teilen
  • Einen Ablauf aufbauen, der Screenshots automatisch erfasst aus einer laufenden Web-Anwendung und sie zusammen mit dem Build der Hilfedokumentation aktualisiert, damit die Bilder in der Dokumentation auch nach UI-Änderungen auf dem neuesten Stand bleiben
  • SCREENSHOT-Kommentare in Markdown enthalten Anweisungen wie Zielpfad, Aufnahmemethode und CSS-Selector; diese werden im Build-Prozess gelesen und mit echten Bildern befüllt
  • Eine Rake-Task startet über Capybara und Cuprite ein headless Chrome, bündelt Aufgaben teamweise, meldet sich einmal an und durchläuft dann mehrere URLs für die Aufnahmen
  • Die Aufnahme unterstützt drei Modi: element, full_page und viewport; mit Optionen wie click, wait, crop, torn und hide lassen sich auch geöffnete UI-Zustände oder unnötige Elemente steuern
  • Mit nur einem rails manual:build laufen Screenshot-Erzeugung und Build der Hilfeseiten gemeinsam, wodurch sich Code und Dokumentation im selben PR oder Commit leichter synchron halten lassen und der Aufwand durch manuelle Aufnahmen und manuelles Zuschneiden stark sinkt

Ansatz mit automatisch aktualisierten Screenshots

  • Das Help Center von Jelly (ein Shared-Inbox-Dienst für Teams) ist so aufgebaut, dass Screenshots automatisch aus der laufenden Web-Anwendung erfasst und beim erneuten Build gleich mit aktualisiert werden
  • Die Dokumentation wird in Markdown geschrieben und, entsprechend dem Artikel Self-updating screenshots, mit Redcarpet zu HTML verarbeitet und anschließend als ERB-View einer Rails-App gerendert
  • Im Markdown stehen SCREENSHOT-Kommentare, die Anweisungen wie Zielpfad, Aufnahmemethode und CSS-Selector enthalten
    • <!-- SCREENSHOT: acme-tools/inbox | element | selector=#inbox-brand-new-section -->
    • Das Bild-Tag direkt darunter dient als Platzhalter für das Ergebnis
  • Schon kleine Änderungen an UI-Farben, Button-Positionen oder Texten lassen bestehende Screenshots in der Dokumentation schnell veralten; dieser Ablauf reduziert den Aufwand solcher manuellen Aktualisierungen

Capture-Pipeline und Wartungsvorteile

  • Intern startet eine Rake-Task über Capybara und Cuprite ein headless Chrome und scannt die SCREENSHOT-Kommentare in allen Markdown-Dateien
  • Screenshot-Aufgaben werden teamweise gebündelt, sodass innerhalb desselben Teams nur einmal eingeloggt werden muss, bevor mehrere URLs durchlaufen werden
  • Es gibt drei unterstützte Aufnahmemodi
    • element: Erfasst ein bestimmtes DOM-Element per CSS-Selector
    • full_page: Erfasst die gesamte Seite und kann bei Bedarf anhand der Höhe zugeschnitten werden
    • viewport: Erfasst nur den aktuell im Browserfenster sichtbaren Bereich
  • Mit Detailoptionen wie click, wait und crop lassen sich auch Zustände nach einem Button-Klick oder nach einer Animation automatisch festhalten
    • <!-- SCREENSHOT: nectar-studio/manage/rules | full_page | click=".rule-create-button" wait=200 crop=0,800 -->
    • Dabei wird nach dem Klick auf den Button das Formular geöffnet, 200 ms gewartet und anschließend ein bestimmter Bereich zugeschnitten und aufgenommen
  • Zusätzlich gibt es die Optionen torn und hide
    • torn verwendet CSS clip-path, um einen Effekt wie eine eingerissene Papierkante anzuwenden
    • hide blendet Elemente wie die Dev-Toolbar oder ein Cookie-Banner vorübergehend aus, wenn sie nicht im Bild erscheinen sollen
  • Die gesamte Pipeline wird mit einem einzigen Befehl rails manual:build ausgeführt und übernimmt alle Screenshot-Aufnahmen sowie den Build der Hilfeseiten gemeinsam
  • Die Dokumentationsquellen sind unter public/manual/ nach Abschnitten wie basics, setup und advanced organisiert
  • Im Build-Schritt werden diese Markdown-Dateien in ERB-Views unter app/views/help/ umgewandelt; außerdem werden Breadcrumbs und die Abschnittsnavigation erzeugt
  • Weil Feature-Entwicklung und Aktualisierung der Hilfe innerhalb derselben Codebasis stattfinden, lässt sich die Synchronisierung von Code und Dokumentation leichter im selben PR oder im selben Commit halten
  • Sonderfälle wie scrollbare Elemente, Popovers, die erst per Klick geöffnet werden müssen, oder crop, um unnötige Teile auszuschneiden, haben in der Umsetzung mehr Zeit gekostet; nach dem Aufbau wurde das Help Center dafür deutlich häufiger aktualisiert
  • Wenn man die UI ändert, den Build erneut ausführt und das Ergebnis committet, bleiben die Screenshots allein durch diesen Ablauf immer aktuell; der Aufwand für manuelle Aufnahmen und manuelles Zuschneiden verschwindet damit fast vollständig

Verwandte Beiträge

1 Kommentare

 
GN⁺ 14 일 전
Hacker-News-Kommentare
  • Ich habe mir ganz ähnlich eine .#screenshots derivation hinzugefügt, und die anfänglichen Einrichtungskosten sind zwar hoch, danach fällt aber fast keine Wartung mehr an
    Wenn man Screenshots ohnehin programmatisch erzeugt, kann man auch gleich beide Versionen der App für light/dark theme erstellen und sie passend zu prefers-color-scheme: dark austauschen
    So etwas funktioniert auch gut in GitHub-READMEs: https://github.com/CyberShadow/CyDo#readme
    • Dem stimme ich voll zu
      Bei mobilen Apps habe ich mit Nix einen einmaligen Android-Emulator gestartet, der aktuelle Screenshots erzeugt, und dabei ist weder Vorkonfiguration nötig noch bleiben nach dem Lauf Daten zurück
      In meinem Fall war selbst die Einrichtung nicht besonders schwer; schwieriger war es, auf die Idee zu kommen, und den Nix-Code habe ich mit meinem bevorzugten LLM in einem Durchgang erzeugt
      Screenshots manuell zu aktualisieren ist zwar nicht die härteste Arbeit der Welt, aber der Ablauf upload-apk + take-screenshot + transfer-back-to-PC + edit ist immer so subtil lästig, dass ich es am Ende fast nie mache
  • Auf Mobilgeräten ist horizontales Scrollen bei Codebeispielen unbedingt nötig
    Man konnte es aus dem Kontext ungefähr erraten, aber es war trotzdem unbequem
  • Das ist für mobile Projekte wirklich nützlich
    In App Stores sind Screenshots Pflicht, aber man muss Bilder in der Anzahl der Bildschirmgrößen und Lokalisierungen erstellen, wodurch es schnell lästig wird
    Früher habe ich dafür selbst Skripte geschrieben, und heute helfen Fastlane-Tools wie https://fastlane.tools/ enorm
    Ich nutze Fastlane auch für mein Logik-Puzzle-Spiel Nonoverse, und auf der App-Store-Seite kann man Beispiel-Screenshots sehen: https://apps.apple.com/us/app/nonoverse-nonogram-puzzles/id6...
    Auch das Aufzeichnen von App-Preview-Videos habe ich inklusive mehrerer Szenen automatisiert, und wenn Interesse besteht, wäre das durchaus ein Thema für einen eigenen Beitrag
    • Das weckt sofort mein Interesse, aber ich kann nicht ganz einschätzen, ob das ein kostenpflichtiger Service ist oder eine lokal laufende OS-App
  • Ziemlich cool
    Die kleinen Casual Games, die ich mit vibe coding baue, starten immer in einem Zustand, in dem die App per CLI headless laufen kann und Offscreen-Textur-Rendering, Screenshot-Befehle und Performance-Messung unterstützt
    Das einzubauen kostet fast keine Zeit, und es schafft zugleich einen Weg, über den ein Agent die UI automatisieren und wichtige Punkte überprüfen kann
    Dadurch wird es auch sehr einfach, den Agenten Screenshots aktualisieren zu lassen
    Es ist nicht ganz so sauber wie eine Form, die vollständig in den Build-Prozess integriert ist, aber ich habe vor, das jetzt ebenfalls noch hinzuzufügen
    • Ich mache exakt dasselbe
      Es gibt auch CLI-Argumente für offscreen screenshot path sowie world pos/camera view vector, und ich lasse skriptbasierte Benchmarks in einem textbasierten Eingabeformat laufen
      Dieses Format besteht aus mehreren Zeilen benannter Segmente, der Spiellänge von n Ticks pro Segment und den Steuerungseingaben für jedes Segment
      Ich nutze das sehr häufig, wenn ich beim Arbeiten am Spielcode Visuals und Performance A/B-teste
    • Ich würde gern ein paar Links zu solchen Casual Games sehen
      Mich interessiert auch sehr, wie stark vibe coding die Spieleentwicklung vereinfacht
      Zu Adobe-Flash-Zeiten war das Indie-Game-Ökosystem wirklich lebendig, und seitdem hat kaum etwas wieder ein ähnliches Maß an Entwicklungsleichtigkeit erreicht
      vibe coding wirkt wie das erste Werkzeug, das dieses Niveau sogar übertrifft
    • Die Aussage Das einzubauen kostet fast keine Zeit hängt vom Einzelfall ab
      Ich frage mich, welche Engine du verwendest
  • Wirklich cool
    Besonders gefällt mir, dass man Screenshot-Deklarationen direkt inline in Markdown-Dokumente setzen kann
    Für meine Desktop-App habe ich eine Lösung gebaut, die Screenshots in mehreren Sprachen und für Light/Dark-Modi erzeugt, Rauschen entfernt und sogar Fensterrahmen von Windows/macOS hinzufügt
    Ich habe das hier dokumentiert: https://maxschmitt.me/posts/cakedesk-website-redesign#screen...
    Im Moment ist es noch ein separates Skript, dessen Wartung ziemlich lästig ist, daher sollte ich mir anschauen, es als Teil von Markdown/MDX zu integrieren
    Gute Inspiration
  • So etwas habe ich wirklich oft gebraucht
    Das könnte man fast als Meme im Stil von die beste Arbeit an X, die niemand bemerkt verwenden
  • Das ist gut
    In meinem https://github.com/zombocom/rundoc gibt es eine ähnliche Funktion
    Der Hauptzweck ist dort die Erzeugung von Tutorials, deshalb werden auch die Ausgaben ausgeführter Befehle wieder ins Dokument eingefügt
  • Ich frage mich, ob hier auch ein Ansatz mit Echtzeit-Rendering möglich wäre
    Also etwa so, dass eine Live-Vorschau des Tools in ein Rechteck eingebettet wird
    Wenn das Tool leichtgewichtig ist, könnte das auch visuell optimal sein, und Rendering-Einstellungen wie Accessibility-Optionen des Browsers oder Benutzer-Add-ons würden ebenfalls direkt übernommen
  • Ich habe schon einmal darüber nachgedacht, beim Ausführen von e2e-Tests auch gleich Screenshots zu erzeugen
    Wenn man docs/ im selben Repository hält und bei Dokumentations-Updates, die neue Screenshots benötigen, jeweils neue Tests ergänzt, könnte das gut zusammenpassen
  • Gefällt mir
    Ich habe vor ein paar Jahren angefangen, genau das zu bauen, habe es am Ende aber zu etwas Allgemeinerem abstrahiert, ähnlich wie https://picshift.io/
    Trotzdem mag ich den Screenshot-Use-Case immer noch sehr, und der ursprüngliche Name dieses Projekts war auch ScreenSync
    • Gut, sauber gemacht, und schön zu sehen, dass solche verschiedenen Ansätze nebeneinander existieren können