Cuốn sách được "over-engineer" đến mức nào? Viết sách bằng Git, CI và 5.500 bài kiểm tra tự động

Hầu hết tác giả bắt đầu viết sách bằng Word hoặc Google Docs, nhưng Ben Balter — một kỹ sư phần mềm kỳ cựu — đã chọn cách "không giống ai": viết toàn bộ cuốn sách trên Git, Markdown và một CI pipeline hoàn chỉnh. Cuốn sách "Open and Async" của ông không chỉ là một tác phẩm văn chương, mà còn là một "dự án phần mềm" với hàng nghìn bài kiểm tra tự động, nhiều định dạng xuất bản và một quy trình build nghiêm ngặt.

Trong bài viết dài trên blog cá nhân, Balter chia sẻ chi tiết về cách ông "over-engineer" (thiết kế quá mức) cuốn sách của mình — và lý do ông cho rằng đây là cách viết sách hiệu quả nhất mà ông từng trải qua.

Tại sao lại viết sách như viết code?

Balter, người từng làm việc tại GitHub và có nhiều năm kinh nghiệm phát triển web, cho rằng các công cụ viết sách chuyên dụng đều "kém hơn" những công cụ ông dùng hàng ngày với tư cách là một developer. Ông giải thích:

"Tôi đã làm website hàng chục năm, nên bước nhảy rất ngắn: những công cụ xây website cũng có thể xây sách, không cần phép màu nào để biến một file Word thành một cuốn sách hoàn chỉnh."

Theo ông, một cuốn sách thực chất là một website trong chiếc áo khoác — sách điện tử chỉ là HTML và CSS, dù là phiên bản đã bị lược bỏ khá nhiều. Ông cũng so sánh Kindle với một trình duyệt WebKit cổ, giống như một "trang web ngoại tuyến nhỏ".

Nội dung như code: Markdown và Git

Toàn bộ nội dung sách được viết dưới dạng Markdown và lưu trữ trong một Git repository. Mỗi chương là một file Markdown riêng, còn một file index.yml xác định thứ tự các chương. Điều này giúp việc sắp xếp lại chương hoặc thêm chương mới trở nên dễ dàng.

Đặc biệt, Balter đã viết phần lớn cuốn sách trên iPad — sử dụng Codespaces trong trình duyệt, bàn phím Bluetooth — thường vào buổi tối hoặc cuối tuần khi xa bàn làm việc. Git repository giúp mọi thứ đồng bộ ở bất kỳ đâu ông mở nó.

Kiểm thử nội dung như kiểm thử code

Điểm "cực đoan" nhất trong cách làm của Balter nằm ở hệ thống kiểm tra tự động. Ông chia làm hai lớp: kiểm tra theo thời gian thực và kiểm tra khi push lên CI.

Lint theo thời gian thực

Khi viết, ông chạy 6 công cụ lint ngay trong VS Code:

• Markdownlint — kiểm tra cú pháp Markdown và định dạng
• Harper — kiểm tra ngữ pháp và lựa chọn từ, chạy hoàn toàn trên thiết bị
• LanguageTool — ngữ pháp, dấu câu và phong cách
• Vale — quy tắc phong cách "nhà" và các từ bị cấm
• Alex — phát hiện ngôn từ thiếu tế nhị hoặc phân biệt
• Write-good — phát hiện văn phong yếu: câu bị động, từ ruồi, sáo ngữ

Tất cả cùng lúc gạch chân lỗi sai trong thời gian thực, giống như cách ESLint hoặc Prettier gạch chân lỗi code.

Custom validators

Ngoài các linter mã nguồn mở, Balter tự viết một bộ test suite riêng với ~30 validator tùy chỉnh. Một trong những validator nổi bật nhất: kiểm tra thì của động từ khi nói về GitHub — vì ông không còn làm việc tại đó nữa, nên bất kỳ câu nào nói rằng ông đang làm việc tại GitHub sẽ khiến build thất bại.

Validator này ra đời sau khi ông từng mắc lỗi — ông nhận ra một nguyên tắc quan trọng:

"Một lỗi bị bắt một lần trở thành một quy tắc quét mọi chương và làm hỏng build nếu nó quay lại. Đừng vỗ về từng chương như thú cưng, hãy điều hành cả đàn bằng chính sách."

Một số validator khác bao gồm: kiểm tra không viết hoa "open source", không dùng các mở đầu kiểu AI ("Hãy tưởng tượng...", "Hãy xem xét..."), không có ba câu liên tiếp mở đầu bằng cùng một từ, kiểm tra cân bằng giữa callout dành cho quản lý và nhân viên, và kiểm tra mọi liên kết chéo trong sách đều hoạt động.

Chống trùng lặp: từ copy-paste đến trùng ý tưởng

Balter xây dựng ba lớp phát hiện trùng lặp, mỗi lớp bắt được những gì lớp trước bỏ sót:

1. jscpd — phát hiện khối văn bản trùng lặp chính xác giữa các chương
2. n-gram — mã hóa từng chương và phát hiện cụm từ xuất hiện ở nhiều chương
3. Ngữ nghĩa (LLM) — phát hiện cùng một ý được diễn đạt bằng từ khác nhau

Phát hiện thú vị nhất: sau khi các lớp cơ học hoạt động sạch, lớp ngữ nghĩa phát hiện ra ông đã lặp lại cùng một luận điểm — "chuyển thói quen văn phòng lên mạng không giống với làm việc remote-first" — trong 5 chương riêng biệt, cùng với 166 lần tự lặp nhỏ hơn trải khắp 51 chương.

"Tôi đã tự diễn đạt lại giỏi đến mức không có công cụ nào rẻ hơn LLM có thể bắt được."

Audit nội dung bằng LLM

Bên cạnh kiểm tra kỹ thuật, Balter còn dùng 20 "lens" LLM đơn mục đích để đánh giá chất lượng văn chương. Mỗi lens hỏi một câu hỏi hẹp để mô hình không thể trả lời chung chung kiểu "trông ổn đấy".

Đáng chú ý nhất là lens Claims, giúp ông phát hiện một câu khẳng định sai: ông viết rằng buổi họp toàn công ty của GitHub "dành khoảng một nửa thời gian cho Q&A trực tiếp" — con số thực tế chỉ là một phần ba. Không một linter nào có thể phát hiện điều này vì đó là câu văn rõ ràng, tự tin nhưng không đúng sự thật.

Xuất bản: vẫn là "click-op" — nhưng thông minh hơn

Sau tất cả tự động hóa, khâu xuất bản thực tế vẫn yêu cầu thao tác thủ công: đăng nhập vào KDP của Amazon, IngramSpark, Draft2Digital và tải file lên từng nền tảng. Balter gọi đây là "tải file lên như năm 2009".

Tuy nhiên, ông chọn trở thành nhà xuất bản của chính mình — thành lập LLC và mua ISBN riêng — để tránh bị phụ thuộc vào nền tảng. Metadata (mô tả, danh mục, từ khóa) cũng được quản lý trong repo, giúp có thể diff và version hóa.

Kết quả: con số biết nói

Chỉ số	Số lượng
Số từ	~100.000 từ, ~70 chương
Số trang in	576 trang (6"×9")
Định dạng xuất bản	5 (EPUB, Kindle, PDF, PDF/X-1a, HTML)
Số bài kiểm tra	~70 files, 2.204 test cases, ~5.500 checks
Số CI jobs mỗi lần push	14, chạy song song
Số quy tắc phong cách	~300 quy tắc, 500+ từ bị cấm
Số commit	5.000+

Bảng điều khiển viết sách

Kết luận: "over-engineer" có đáng không?

Balter thừa nhận: "Tôi không khuyên bạn viết 5.500 bài kiểm tra cho cuốn tiểu thuyết của mình. Với hầu hết sách, phần lớn điều này là phi cân xứng — và đó chính là vấn đề."

Nhưng với ông, đây là một trải nghiệm đáng giá:

"Tôi làm vậy vì chi phí biên của một bài kiểm tra thêm, một định dạng thêm, một validator thêm chỉ là vài phút và một chút tò mò — và vì làm theo cách của developer, tôi có thể viết từ iPad xa bàn làm việc và tin rằng main luôn có thể xuất bản được."

Công cụ này cũng vượt ra ngoài cuốn sách: ông áp dụng nó cho blog của mình và phát hiện một bài viết từ năm 2011 có lỗi chính tả — "its clear" thay vì "it's clear" — mà hàng nghìn người đã đọc mà không ai nhận ra. Ông kết luận: "Bạn không tự phát hiện ra. Bạn phải đi tìm."

Balter đang có kế hoạch phát hành toàn bộ công cụ này dưới dạng mã nguồn mở để những người khác không phải xây dựng lại từ đầu.

Đồ thị CI build của cuốn sách

Bài viết được tổng hợp và lược dịch từ bài đăng gốc của Ben Balter trên blog cá nhân.