Tại sao mình quyết định "vứt bỏ" file README.md truyền thống để chuyển sang Vitepress: Trải nghiệm làm Doc Đa Ngôn Ngữ chuẩn Enterprise

Chào anh em, chắc hẳn ai trong chúng ta khi làm dự án cũng từng tự hứa với bản thân: "Mình sẽ viết file README thật sạch sẽ, khoa học để ai vào cũng đọc được."

Thế nhưng đời không như là mơ. Khi dự án của bạn bắt đầu lớn lên, ôm thêm hàng tá cấu hình từ Multi-stage Docker, PM2 Cluster, hàng đợi BullMQ cho đến cơ chế Centralized Env... file README ban đầu bỗng biến thành một "bãi rác" cấu hình dài hàng nghìn dòng.

Đỉnh điểm là khi mình quyết định đưa con tool open-source của mình ra thị trường quốc tế, hỗ trợ cùng lúc 3 thứ tiếng: Tiếng Anh, Tiếng Việt và Tiếng Trung (English, Vietnamese, Chinese). Việc ngồi duy trì thủ công 3 file readme rải rác chính là một cơn ác mộng thực sự về mặt vận hành (DevOps) và trải nghiệm nhà phát triển (DX).

Vì vậy, mình đã quyết định đập đi xây lại, vứt bỏ tư duy viết readme thủ công cũ kỹ để chuyển dịch toàn bộ sang kiến trúc tài liệu cô lập bằng Vitepress.

Nỗi đau của việc bảo trì README thủ công khi làm Đa ngôn ngữ

Nếu anh em cố đấm ăn xôi quản lý tài liệu đa ngôn ngữ bằng các file README truyền thống, anh em sẽ dính ngay 3 cái bẫy:

1. Lệch thông tin (Desynchronization): Chỉ cần một hôm đẹp trời anh em cập nhật thêm 1 biến env mới ở file Tiếng Anh, nhưng quên không sửa ở file Tiếng Việt hay Tiếng Trung, coi như user ở các region đó sẽ bị lỗi cấu hình ngay lập tức khi chạy.
2. Giao diện rối loạn: Việc nhồi nhét quá nhiều hướng dẫn sử dụng hạ tầng phức tạp vào một trang duy nhất khiến người đọc bị ngợp. Họ phải "bơi" trong đống text để tìm cái họ cần.
3. Tăng dung lượng package (Bloatware): Nhồi nhét tài liệu, hình ảnh hướng dẫn vào root dự án sẽ vô tình làm phình to dung lượng gói cài đặt khi kéo về qua CLI.

Giải pháp: Cách ly tài liệu bằng Vitepress Static Engine

Để giải quyết triệt để bài toán này, mình đã bóc tách toàn bộ phần tài liệu ra khỏi core của dự án và chuyển sang dùng Vitepress. Lý do mình chọn Vitepress thay vì các công cụ khác rất đơn giản:

• Tốc độ siêu tốc (0ms): Chạy trên nền Vite, compile toàn bộ Markdown thành các file HTML tĩnh, bấm một cái là load ngay lập tức.
• Hỗ trợ i18n cực mạnh: Vitepress có sẵn tính năng cấu hình đa ngôn ngữ gốc. Nó tự động tạo ra nút chuyển đổi ngôn ngữ (Language Switcher) cực kỳ mượt mà trên thanh điều hướng mà mình không cần viết thêm một dòng logic định tuyến nào.
• Cô lập hoàn toàn: Folder docs nằm biệt lập, không can thiệp hay dính dáng gì đến logic code chạy bên dưới của hệ thống.

Hiện thực hóa thực chiến: Giữ vững mốc 1.4MB

Toàn bộ kiến trúc tài liệu tĩnh đa ngôn ngữ này đã được mình hiện thực hóa thành công trong dự án open-source Nodejs Quickstart Generator

Dù ôm trọn các giải pháp kiến trúc Enterprise nặng đô, nhưng nhờ việc cô lập trang doc qua Vitepress và tối ưu regex parser cho hệ thống config, tổng dung lượng package sinh ra vẫn giữ vững ở con số 1.4MB siêu nhẹ, sạch bóng vulnerability.

Trang tài liệu mới của dự án giờ đây sở hữu giao diện chuyên nghiệp, có thanh tìm kiếm thông minh, hỗ trợ chuyển đổi mượt mà giữa 3 ngôn ngữ (🇺🇸 Tiếng Anh làm mặc định, 🇻🇳 Tiếng Việt cho anh em nước nhà, và 🇨🇳 Tiếng Trung để tiếp cận cộng đồng GitHub tỷ dân).

Nếu anh em đang đau đầu với những file README thủ công rắc rối, hãy thử chuyển hướng sang mô hình tài liệu tĩnh cô lập này để nâng tầm dự án của mình nhé!

Nguồn: Why We Ditched the Traditional README.md for Vitepress: Scaling Multi-Language Enterprise Docs Without Code Bloat