Tự động hóa ảnh chụp màn hình trong tài liệu kỹ thuật: Một giải pháp thông minh

Nếu bạn từng duy trì một trung tâm hỗ trợ (help centre) hoặc trang tài liệu cho một ứng dụng web, bạn sẽ hiểu rõ nỗi khổ đặc thù của những tấm ảnh chụp màn hình (screenshot). Bạn viết một bài hướng dẫn rất hay, chụp cẩn thận màn hình tính năng cần tài liệu hóa, cắt ghép, thêm viền và đổ bóng, rồi tải lên. Nó trông tuyệt vời.

Nhưng sau đó, bạn thay đổi giao diện người dùng (UI) một chút — điều chỉnh màu sắc, di chuyển một nút bấm, hoặc cập nhật một đoạn văn bản — và đột nhiên, mọi ảnh chụp màn hình chứa yếu tố đó đều trở nên lạc hậu. Bạn biết chúng đã cũ. Người dùng có thể không để ý, nhưng bạn thì biết, và điều đó thật khó chịu.

Hoặc có thể chỉ riêng tôi cảm thấy vậy.

Dù thế nào, tôi quyết định khắc phục vấn đề này. Trung tâm trợ giúp trong Jelly có một hệ thống build (hệ thống xây dựng) trong đó các ảnh chụp màn hình được thu thập tự động từ ứng dụng đang chạy, và chúng tự cập nhật mỗi khi bạn rebuild.

Markdown với một chút biến tấu

Các bài viết trợ giúp được viết bằng Markdown, được xử lý thành HTML thông qua Redcarpet và sau đó hiển thị dưới dạng view ERB trong ứng dụng Rails. Cho đến nay, mọi thứ vẫn khá bình thường. Nhưng rải rác trong Markdown là các đoạn chú thích đặc biệt đóng vai trò chỉ dẫn cho hệ thống chụp ảnh.

Ví dụ, một dòng lệnh có thể yêu cầu: "đi đến trang inbox cho nhóm demo Acme Tools, tìm phần tử khớp với #inbox-brand-new-section, và chụp ảnh màn hình phần tử đó." Thẻ ảnh bên dưới dòng chú thích là nơi kết quả được hiển thị.

Cơ chế hoạt động

Về mặt kỹ thuật, đây là một tác vụ Rake khởi chạy trình duyệt Chrome headless thông qua Capybara và Cuprite. Nó quét mọi tệp Markdown để tìm các chú thích chụp ảnh, nhóm chúng theo nhóm người dùng (để chỉ cần đăng nhập một lần cho mỗi nhóm), điều hướng đến từng URL và thực hiện chụp ảnh.

Các chế độ chụp bao gồm:

• element: Chụp một phần tử DOM cụ thể bằng CSS selector.
• full_page: Chụp toàn bộ trang, tùy chọn cắt theo chiều cao.
• viewport: Chỉ chụp phần hiển thị trong cửa sổ trình duyệt.

Ngoài ra, còn có một số tùy chọn để xử lý các trường hợp khó khăn:

Hệ thống có thể điều hướng đến trang quy tắc, nhấp vào một nút để mở form, đợi 200 mili-giây để hiệu ứng hoạt hình hoàn tất, sau đó chụp ảnh toàn trang và cắt theo một vùng cụ thể. Tùy chọn click thực sự là điểm sáng của hệ thống này — rất nhiều tính năng ẩn sau một nút bấm hoặc popover, và khả năng chụp tự động các trạng thái đó thực sự tuyệt vời.

Còn có tùy chọn torn — áp dụng hiệu ứng mép giấy rách thông qua clip-path của CSS — và hide, giúp ẩn tạm thời các phần tử bạn không muốn xuất hiện trong ảnh (thanh công cụ dev, banner cookie, v.v.).

Phần thỏa mãn nhất

Toàn bộ quy trình pipeline chỉ chạy với một lệnh duy nhất:

rails manual:build

Lệnh này sẽ chụp mọi ảnh chụp màn hình và sau đó xây dựng tất cả các trang trợ giúp. Khi tôi thay đổi giao diện, tôi chạy lệnh đó và mọi ảnh chụp màn hình đều được cập nhật để khớp với giao diện mới. Không cần cắt ghép thủ công, không còn cảnh "à, tôi quên cập nhật cái này", và không còn những ảnh chụp màn hình dần dần trở nên lỗi thời khiến trung tâm trợ giúp trông bị bỏ rơi.

Các tệp markdown nằm trong public/manual/, được tổ chức theo phần — cơ bản, cài đặt, nâng cao — và bước build sẽ xử lý chúng thành các view ERB trong app/views/help/, hoàn chỉnh với breadcrumbs và điều hướng phần, tất cả đều được tạo từ các tệp markdown nguồn.

Điều này cũng giúp việc cập nhật trung tâm trợ giúp trở nên dễ dàng ngay khi tôi đang làm việc trên tính năng; mã nguồn và tài liệu sống chung với nhau và có thể được giữ đồng bộ trong cùng một Pull Request hoặc thậm chí là cùng một commit.

Một trong những việc "tại sao mình không làm sớm hơn"

Tôi đã trì hoãn việc xây dựng hệ thống này một thời gian dài vì nó dường như là quá nhiều công việc cho một tính năng "có thì tốt". Thú thật, nó tốn khá nhiều công sức. Việc xử lý các trường hợp ngoại lệ — các phần tử cần cuộn vào vùng nhìn thấy, các popover cần nhấp vào, các ảnh cần cắt để tránh hiển thị nội dung không liên quan — mất nhiều thời gian hơn trường hợp tiêu chuẩn.

Nhưng giờ đây, khi nó đã hiện hữu, tôi cập nhật trung tâm trợ giúp thường xuyên hơn nhiều so với trước đây, vì ma sát (friction) gần như đã biến mất. Thay đổi giao diện, chạy build, commit kết quả. Các ảnh chụp màn hình luôn mới nhất, và tôi không bao giờ phải mở trình duyệt và lúng túng với công cụ chụp màn hình của macOS nữa.