Wiki trên GitHub là một anti-pattern: Vì sao tài liệu nên nằm cạnh mã nguồn?

Câu hỏi "nên dùng wiki hay thư mục docs trên GitHub?" cứ khoảng sáu tháng lại nổi lên một lần trong các cộng đồng lập trình. Và theo quy tắc "ba lần lặp lại" của Shawn Wang, có lẽ đã đến lúc cần viết hẳn ra một bài cho rõ ràng. Bài viết của Michael Heap trên blog cá nhân đã gây chú ý trên Hacker News với 20 điểm và 13 bình luận, cho thấy đây vẫn là chủ đề gây tranh cãi.

Điều thú vị là phiên bản đầu tiên của bài viết này mở đầu bằng câu "Bạn có thể dùng wiki hoặc thư mục docs cho dự án GitHub của mình, cả hai đều là lựa chọn hợp lý". Nhưng càng viết, tác giả càng nhận ra rằng chỉ có một lý do duy nhất để dùng wiki, trong khi có rất nhiều lý do để không dùng. Nhiều đến mức ông coi việc dùng wiki trên GitHub là một anti-pattern.

Lợi ích của wiki: Chỉ có một, và không hơn

Hãy bắt đầu bằng những điểm được cho là lợi thế của wiki:

• Bạn có thể truy cập nội dung wiki chỉ với một cú nhấp chuột từ bất kỳ đâu trong kho mã nguồn.

Và... hết.

Thực sự thì lợi ích duy nhất mà tác giả tìm được là wiki luôn ở đó. Nó hiện diện sẵn trong giao diện repository, không cần cấu hình, không cần thiết lập. Nhưng đó cũng là toàn bộ giá trị của nó.

Những lý do để tránh xa wiki

Danh sách các nhược điểm dài hơn hẳn, và đáng chú ý là chúng đều liên quan đến những vấn đề cốt lõi trong quy trình phát triển phần mềm chuyên nghiệp:

• Tài liệu không được đánh phiên bản cùng mã nguồn. Khi dùng thư mục /docs, tài liệu được version hóa song song với code. Nếu cần xem phiên bản cũ, bạn dễ dàng tìm lại. Với wiki thì không có cơ chế này.

• Tài liệu không có sẵn cục bộ khi clone repository. Khi ai đó clone dự án về máy, họ không có tài liệu trong tay. Về mặt kỹ thuật, bạn có thể clone riêng wiki, nhưng đây là một tính năng ẩn mà gần như không ai biết đến.

• Chỉnh sửa tài liệu không được đối xử như code. Với thư mục /docs, mọi thay đổi tài liệu đều trải qua quy trình pull request với đầy đủ bước review ngang hàng. Điều này giúp phát hiện lỗi, đảm bảo chất lượng và lưu lại lịch sử thảo luận.

• Không thể dùng GitHub Actions để kiểm tra chất lượng tài liệu. Bạn không thể chạy các công cụ như Vale để lint văn bản, kiểm tra chính tả hay quy tắc trình bày.

• Không tận dụng được công cụ quen thuộc. Khi tài liệu nằm trong repository, lập trình viên có thể làm việc với VS Code, bật kiểm tra chính tả, dùng các extension yêu thích — tất cả những gì họ đã quen.

• Khả năng tùy biến thương hiệu gần như bằng không. Mọi wiki trên GitHub đều trông giống hệt nhau, không có cơ hội xây dựng nhận diện riêng cho dự án.

• Wiki không hỗ trợ tải ảnh lên. Điều này đồng nghĩa với việc bạn vẫn phải lưu ảnh ở một nơi khác, làm mất đi tính nhất quán của tài liệu.

Tóm lại, wiki chỉ có một điểm cộng duy nhất, trong khi danh sách điểm trừ kéo dài và chạm đến cả quy trình review, phiên bản hóa lẫn trải nghiệm cộng tác.

Vậy nên làm gì thay thế?

Nếu đã bị thuyết phục rằng nên giữ tài liệu cạnh mã nguồn, câu hỏi tiếp theo là làm sao để người khác dễ dàng xem chúng. Tác giả gợi ý quy trình sau:

• Đặt tài liệu trong thư mục /docs của repository. Không dùng nhánh gh-pages, vì điều đó ngăn cản việc đánh phiên bản tài liệu song song với code.

• Thiết lập build GitHub Pages để xuất bản tài liệu.

• Nếu mới bắt đầu, hãy dùng theme just-the-docs và để GitHub tự build và publish tài liệu.

• Nếu muốn tự xây dựng workflow riêng (chẳng hạn với Hugo), có thể dùng GitHub Action để publish tài liệu.

• Tạo một trang wiki duy nhất dẫn người đọc đến tài liệu đã được host chính thức.

Khi nào thì cần tách riêng repository?

Theo tác giả, dùng thư mục /docs là lựa chọn có tỷ lệ công sức trên lợi ích cao nhất khi đang xây dựng sản phẩm mới. Nhưng đến một lúc nào đó, tài liệu sẽ vượt quá khuôn khổ một thư mục duy nhất.

Lúc đó, bạn sẽ cần một repository riêng với quy trình build riêng, hướng dẫn review pull request riêng và nhiều thứ khác nữa. Điểm hay là khi ấy, mọi người đã quen với việc làm việc với tài liệu trong repository, nên việc chuyển từ /docs sang repo riêng sẽ diễn ra liền mạch với những người đóng góp.

Góc nhìn cho lập trình viên Việt Nam

Với các nhóm phát triển phần mềm tại Việt Nam — đặc biệt là các startup và đội outsource làm việc với khách hàng nước ngoài — bài học này khá thiết thực. Tài liệu dự án thường bị xem nhẹ, và wiki dễ trở thành "nghĩa địa tài liệu" với nội dung lỗi thời, không ai kiểm soát.

Việc đưa tài liệu vào /docs và bắt buộc review qua pull request giúp giải quyết đúng vấn đề mà nhiều đội Việt Nam gặp phải: tài liệu không ai cập nhật. Khi tài liệu nằm chung nhánh với code, mỗi lần merge feature là một cơ hội để cập nhật tài liệu tương ứng — và quy trình đó trở thành phản xạ tự nhiên thay vì một việc làm thêm phiền phức.