Automatisch aktualisierte Screenshots in Dokumente einfügen

 (interblah.net)
11 Punkte von GN⁺ 2 일 전 | 1 Kommentare | Auf WhatsApp teilen
  • Einen Ablauf einrichten, der in einer laufenden Webanwendung automatisch Screenshots aufnimmt und sie zusammen mit dem Build der Hilfedokumentation aktualisiert, damit die Dokumentationsbilder auch nach UI-Änderungen auf dem neuesten Stand bleiben
  • SCREENSHOT-Kommentare in Markdown enthalten Anweisungen wie Zielpfad, Aufnahmemethode und CSS-Selector und werden im Build-Prozess ausgelesen, um sie mit echten Bildern zu füllen
  • Eine Rake-Task startet über Capybara und Cuprite ein headless Chrome; die Arbeit wird pro Team gebündelt, sodass nach einmaligem Login mehrere URLs nacheinander erfasst werden können
  • 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 zusammen, sodass sich Code und Dokumentation im selben PR oder Commit leicht aufeinander abstimmen lassen und die Reibung durch manuelle Aufnahmen und manuelles Zuschneiden stark sinkt

Ansatz für automatisch aktualisierte Screenshots

  • Das Hilfecenter von Jelly (ein Shared-Mail-Inbox-Dienst für Teams) ist so aufgebaut, dass es in der laufenden Webanwendung automatisch Screenshots aufnimmt und diese beim erneuten Build mit aktualisiert
  • Die Dokumentation wird in Markdown geschrieben und gemäß dem Artikel Self-updating screenshots mit Redcarpet zu HTML verarbeitet und anschließend über ERB-Views der Rails-App gerendert
  • In Markdown werden SCREENSHOT-Kommentare eingefügt, die Anweisungen wie Zielpfad, Aufnahmemethode und CSS-Selector enthalten
    • <!-- SCREENSHOT: acme-tools/inbox | element | selector=#inbox-brand-new-section -->
    • Das direkt darunter stehende Bild-Tag dient als Platz, an dem das Ergebnis eingefügt wird
  • Schon kleine Änderungen an UI-Farben, Button-Positionen oder Texten lassen bestehende Dokumentations-Screenshots schnell veralten; dieser Ablauf verringert den Aufwand für solche manuellen Aktualisierungen

Capture-Pipeline und Wartungseffekte

  • Intern startet eine Rake-Task über Capybara und Cuprite ein headless Chrome und scannt die SCREENSHOT-Kommentare in allen Markdown-Dateien
  • Die Screenshot-Arbeiten werden pro Team gebündelt verarbeitet; innerhalb desselben Teams wird nur einmal eingeloggt, bevor mehrere URLs nacheinander aufgerufen werden
  • Es gibt drei unterstützte Aufnahmemodi
    • element: Nimmt ein bestimmtes DOM-Element anhand eines CSS-Selectors auf
    • full_page: Nimmt die gesamte Seite auf und kann bei Bedarf anhand der Höhe zugeschnitten werden
    • viewport: Nimmt nur den aktuell sichtbaren Bereich des Browserfensters auf
  • Mit Detailoptionen wie click, wait und crop lassen sich auch Zustände nach einem Button-Klick oder nach einer Animation automatisch erfassen
    • <!-- 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 aufgenommen
  • Zusätzliche Optionen sind torn und hide
    • torn verwendet CSS clip-path, um einen Effekt mit einer eingerissenen Papierkante zu erzeugen
    • hide blendet Elemente wie die Dev-Toolbar oder Cookie-Banner vorübergehend aus, die nicht im Bild erscheinen sollen
  • Die gesamte Pipeline läuft mit nur einem einzigen Befehl: rails manual:build; dabei werden alle Screenshots aufgenommen und die Hilfeseiten gebaut
  • Die Quelldateien der Dokumentation 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; Breadcrumbs und Abschnittsnavigation werden ebenfalls erzeugt
  • Weil Funktionsentwicklung und Aktualisierung der Hilfe innerhalb derselben Codebasis zusammen behandelt werden können, lässt sich die Synchronisierung von Code und Dokumentation leicht im selben PR oder im selben Commit aufrechterhalten
  • Sonderfälle wie scrollbare Elemente, Popover, die erst per Klick geöffnet werden, oder Zuschneiden, um unnötige Bereiche zu vermeiden, erforderten in der Umsetzung mehr Zeit; nach dem Aufbau wurde das Hilfecenter jedoch deutlich häufiger aktualisiert
  • Wenn die UI geändert wird, der Build erneut läuft und das Ergebnis anschließend committet wird, bleiben die Screenshots allein durch diesen Ablauf stets aktuell; die Reibung durch manuelle Aufnahmen und manuelles Zuschneiden verschwindet nahezu vollständig

Verwandte Beiträge

1 Kommentare

 
GN⁺ 2 일 전
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