Screenshot yang Diperbarui Otomatis

• Alur ini secara otomatis menangkap screenshot dari aplikasi web yang sedang berjalan dan memperbaruinya bersamaan dengan build dokumentasi bantuan, sehingga gambar di dokumen mudah dijaga tetap mutakhir bahkan setelah UI berubah
• Komentar SCREENSHOT di dalam Markdown memuat instruksi seperti path target, cara pengambilan, dan CSS selector, lalu dibaca saat proses build untuk diisikan menjadi gambar yang sebenarnya
• Rake task menjalankan Chrome headless melalui Capybara dan Cuprite, lalu mengelompokkan pekerjaan per tim agar bisa login sekali dan menangkap beberapa URL sekaligus
• Pengambilan mendukung tiga mode: element, full_page, dan viewport, dengan opsi seperti click, wait, crop, torn, dan hide untuk mengendalikan UI yang sedang terbuka maupun elemen yang tidak diperlukan
• Dengan sekali rails manual:build, pembuatan screenshot dan build halaman bantuan berjalan bersama, sehingga kode dan dokumentasi lebih mudah diselaraskan dalam PR atau commit yang sama dan friksi dari tangkapan serta crop manual berkurang drastis

---

Pendekatan screenshot yang diperbarui otomatis

• Pusat bantuan Jelly disusun agar secara otomatis menangkap screenshot dari aplikasi web yang sedang berjalan, lalu memperbaruinya lagi saat build dijalankan ulang
• Dokumen ditulis dalam Markdown, lalu diproses menjadi HTML dengan Redcarpet berdasarkan artikel Self-updating screenshots, kemudian dirender sebagai ERB view di aplikasi Rails
• Di dalam Markdown terdapat komentar SCREENSHOT, yang memuat instruksi seperti path target, metode pengambilan, dan CSS selector
  • <!-- SCREENSHOT: acme-tools/inbox | element | selector=#inbox-brand-new-section -->
  • Tepat di bawahnya, tag gambar dipakai sebagai lokasi untuk menempatkan hasilnya
• Jika warna UI, posisi tombol, atau teks berubah sedikit saja, screenshot dokumentasi lama akan cepat usang; alur ini mengurangi beban pembaruan manual tersebut

Pipeline pengambilan dan dampaknya pada pemeliharaan

• Secara internal, Rake task menjalankan Chrome headless melalui Capybara dan Cuprite untuk memindai komentar SCREENSHOT di semua file Markdown
• Pekerjaan screenshot diproses dengan pengelompokan per tim, sehingga untuk tim yang sama cukup login satu kali sebelum menelusuri beberapa URL
• Ada tiga mode pengambilan yang didukung
  • element: menangkap elemen DOM tertentu dengan CSS selector
  • full_page: menangkap seluruh halaman, dan jika perlu bisa dipotong berdasarkan tinggi
  • viewport: menangkap hanya area yang sedang terlihat di jendela browser
• Opsi detail seperti click, wait, dan crop memungkinkan layar setelah klik tombol atau setelah animasi selesai juga ditangkap secara otomatis
  • <!-- SCREENSHOT: nectar-studio/manage/rules | full_page | click=".rule-create-button" wait=200 crop=0,800 -->
  • Ini akan menekan tombol untuk membuka formulir, menunggu 200ms, lalu memotong area tertentu sebelum menangkapnya
• Ada juga opsi tambahan torn dan hide
  • torn menerapkan efek tepi kertas sobek menggunakan CSS clip-path
  • hide untuk sementara menyembunyikan elemen seperti dev toolbar atau cookie banner yang seharusnya tidak muncul di layar
• Seluruh pipeline dijalankan dengan satu perintah, rails manual:build, yang menangani semua pengambilan screenshot sekaligus build halaman bantuan
• Sumber dokumen disusun di bawah public/manual/ menurut bagian seperti basics, setup, dan advanced
• Pada tahap build, file Markdown ini diubah menjadi ERB view di bawah app/views/help/, sekaligus membuat breadcrumb dan navigasi bagian
• Karena pengembangan fitur dan pembaruan bantuan bisa dikelola bersama dalam codebase yang sama, sinkronisasi kode dan dokumentasi lebih mudah dijaga dalam PR atau commit yang sama
• Penanganan kasus khusus seperti elemen yang perlu di-scroll, popover yang harus dibuka lewat klik, atau crop untuk menghindari bagian yang tidak perlu memang membutuhkan lebih banyak waktu saat implementasi, tetapi setelah dibangun pusat bantuan jadi jauh lebih sering diperbarui
• Dengan alur cukup mengubah UI, menjalankan build ulang, lalu melakukan commit pada hasilnya, screenshot bisa selalu dijaga tetap mutakhir, sehingga friksi dari tangkapan dan crop manual hampir hilang

[GN⁺]

Komentar Hacker News

• Saya juga menambahkan .#screenshots derivation yang mirip, dan meski biaya setup awalnya besar, setelah itu hampir tidak perlu maintenance
  Sekalian menghasilkan screenshot secara terprogram, buat saja dua versi aplikasi untuk light/dark theme, lalu tukar sesuai prefers-color-scheme: dark
  Hal seperti ini juga bekerja baik di GitHub README: https://github.com/CyberShadow/CyDo#readme
  • Sangat setuju dengan pendekatan ini
    Untuk aplikasi mobile, saya membuat Nix menjalankan emulator Android sekali pakai untuk menghasilkan screenshot terbaru, tanpa perlu pra-konfigurasi dan tanpa meninggalkan data setelah dijalankan
    Dalam kasus saya, setup-nya sendiri juga tidak terlalu sulit; justru lebih sulit memikirkan idenya, dan kode Nix-nya saya buat sekaligus dengan LLM favorit saya
    Memperbarui screenshot secara manual memang bukan pekerjaan paling berat di dunia, tapi alur upload-apk + take-screenshot + transfer-back-to-PC + edit selalu terasa agak merepotkan, jadi pada akhirnya hampir tidak pernah saya lakukan
• Di mobile, scroll horizontal untuk contoh kode benar-benar diperlukan
  Saya masih bisa menebak dari konteks, tapi tetap terasa tidak nyaman
• Ini sangat berguna untuk proyek mobile
  App store mewajibkan screenshot, dan karena harus membuat gambar sebanyak jumlah ukuran layar dikalikan jumlah lokalisasi, prosesnya cepat menjadi merepotkan
  Dulu saya menulis skrip sendiri untuk ini, dan sekarang alat Fastlane seperti https://fastlane.tools/ sangat membantu
  Saya juga memakai Fastlane untuk game puzzle logika saya, Nonoverse, dan Anda bisa melihat contoh screenshot di halaman App Store-nya: https://apps.apple.com/us/app/nonoverse-nonogram-puzzles/id6...
  Saya juga sudah mengotomatisasi perekaman video App Preview, termasuk beberapa adegan, dan kalau ada yang tertarik rasanya ini cukup layak ditulis sebagai posting terpisah
  • Ini langsung terdengar sangat menarik, tapi saya belum begitu paham apakah ini layanan berbayar atau aplikasi OS yang berjalan secara lokal
• Keren juga
  Game kasual kecil yang saya buat dengan vibe coding selalu dimulai dari kondisi di mana aplikasinya bisa dijalankan headless lewat CLI, dengan rendering tekstur offscreen, perintah screenshot, sampai pengukuran performa
  Menambahkan ini juga hampir tidak memakan waktu, dan memberi agen jalur untuk mengotomatisasi UI serta memeriksa titik-titik penting
  Karena itu, membuat agen memperbarui screenshot juga jadi sangat mudah
  Memang belum serapi bentuk yang benar-benar menyatu ke dalam proses build, tapi sekarang saya jadi ingin menambahkan bagian itu juga
  • Saya juga melakukan hal yang sama
    Saya juga punya argumen CLI untuk offscreen screenshot path serta world pos/camera view vector, dan menjalankan benchmark skrip dengan format input berbasis teks
    Format ini terdiri dari beberapa baris segmen bernama, panjang n game tick untuk tiap segmen, serta input kontrol untuk masing-masing segmen
    Saya sangat sering memakainya saat A/B testing visual dan performa sambil mengerjakan kode game
  • Penasaran apakah Anda bisa membagikan beberapa tautan ke game kasual itu
    Saya juga sangat tertarik dengan seberapa mudah vibe coding membuat pengembangan game
    Pada era Adobe Flash, ekosistem game indie benar-benar sangat hidup, dan setelah itu hampir tidak ada yang menyentuh tingkat kemudahan pengembangan seperti itu
    vibe coding tampaknya seperti alat pertama yang benar-benar melampaui level tersebut
  • Pernyataan hampir tidak memakan waktu untuk menambahkan ini tergantung kasusnya
    Saya penasaran Anda memakai engine apa
• Benar-benar keren
  Saya terutama suka bahwa deklarasi screenshot bisa ditaruh inline di dalam dokumen Markdown
  Untuk aplikasi desktop saya, saya sudah membuat solusi yang menghasilkan screenshot dalam berbagai bahasa dan mode light/dark, menghilangkan noise, bahkan menambahkan frame jendela Windows/macOS
  Saya merangkumnya di sini: https://maxschmitt.me/posts/cakedesk-website-redesign#screen...
  Saat ini masih berupa skrip terpisah jadi cukup merepotkan untuk dirawat, tapi saya perlu melihat kemungkinan memasukkannya sebagai bagian dari markdown/mdx
  Ini memberi saya inspirasi yang bagus
• Saya memang sering sekali membutuhkan hal seperti ini
  Sampai-sampai rasanya bisa dipakai sebagai meme seperti karya terbaik X yang tidak akan disadari siapa pun
• Ini bagus
  https://github.com/zombocom/rundoc yang saya buat juga punya fitur serupa
  Tujuan utamanya adalah membuat tutorial, jadi output dari perintah yang dijalankan juga dimasukkan kembali ke dalam dokumen
• Rasanya pendekatan rendering real-time juga mungkin di sini
  Misalnya dengan menaruh live preview dari alat itu di dalam sebuah persegi panjang
  Jika alatnya ringan, ini mungkin optimal juga secara visual, dan pengaturan rendering seperti setelan aksesibilitas browser atau addon pengguna juga bisa tercermin apa adanya
  • Atau cukup lakukan static build untuk HTML
    Dokumentasi iommi memang benar-benar melakukan itu: https://kodare.net/2025/01/14/iframes-not-screenshots.html
  • Tapi saya rasa ini juga bisa menjadi isu keamanan
• Saya pernah berpikir untuk ikut melakukan pembuatan screenshot saat menjalankan tes e2e
  Jika docs/ untuk dokumentasi juga diletakkan di repositori yang sama, lalu setiap kali perlu screenshot baru saat memperbarui dokumentasi kita menambahkan tes baru, sepertinya ini akan cocok sekali
• Bagus
  Saya juga sempat mulai membuat hal yang persis seperti ini beberapa tahun lalu, tapi akhirnya saya mengabstraksikannya ke arah yang lebih umum seperti https://picshift.io/
  Meski begitu, saya tetap sangat menyukai use case screenshot ini, dan nama asli proyek ini juga dulu ScreenSync
  • Bagus, dibuat dengan baik, dan menyenangkan melihat berbagai pendekatan seperti ini bisa hidup berdampingan