Người viết code nghỉ việc, dự án còn ai hiểu? 5 tài liệu cần có

Hình dung 1 công ty bán lẻ thuê đội ngoài làm hệ thống đặt hàng (tình huống giả định để minh họa, không phải khách hàng của Click Star). Sau 2 năm, kỹ sư chính nghỉ việc. Người mới mở kho mã và không biết chạy nó thế nào, vì sao chọn cơ sở dữ liệu này, hay phải làm gì khi hệ thống ngưng lúc nửa đêm.

Bài này nói về bộ tài liệu tối thiểu giúp dự án phần mềm sống sót qua chuyện đó: README, tài liệu kiến trúc, ADR, runbook và hồ sơ bàn giao. Nguồn gồm Diátaxis, bài của Michael Nygard, hướng dẫn của AWS, Google và GitHub, đối chiếu đến ngày 24/10/2026.

Bài trả lời 3 câu hỏi: nên viết tài liệu nào, ai giữ cho nó đúng, và 30 ngày đầu làm gì.

Điểm chính

• Mất người viết code là mất tri thức, không chỉ mất sức làm. Nghiên cứu năm 2016 trên 133 dự án GitHub nổi tiếng ước tính 65% dự án có "truck factor" không quá 2.
• Bộ tối thiểu theo khung của Click Star gồm 5 thứ: README (chạy thế nào), kiến trúc 1 trang, ADR (vì sao chọn vậy), runbook (xử lý sự cố) và hồ sơ bàn giao.
• ADR chỉ ghi quyết định quan trọng, ngắn gọn. Khi đổi ý, hãy viết ADR mới thay vì sửa ADR cũ.
• Diátaxis chia tài liệu thành 4 kiểu: hướng dẫn học, hướng dẫn làm, tham chiếu và giải thích. Trộn chúng vào 1 trang là lỗi quen thuộc.
• Tài liệu nên nằm cạnh mã, đổi cùng mã, có chủ và ngày xem lại. Tài liệu cũ gây hại vì làm người đọc hiểu sai.
• Đừng ghi mật khẩu hay khóa vào tài liệu. Hãy nhờ 1 người chưa từng làm dự án chạy thử theo tài liệu.

Người viết code rời đi thì dự án mất gì

Dự án mất 2 thứ: cách làm và lý do. Cách làm là chạy, triển khai, sửa lỗi. Lý do là vì sao hệ thống được dựng như hiện nay.

Theo bài "Documenting Architecture Decisions" của Michael Nygard (15/11/2011), người mới không biết lý do chỉ có 2 lựa chọn: chấp nhận quyết định một cách mù quáng, hoặc đổi nó một cách mù quáng. Nếu chấp nhận quá nhiều thứ mình không hiểu, Nygard viết, đội sẽ sợ đổi bất cứ thứ gì.

Về bằng chứng, nhóm của Guilherme Avelino đăng bài ngày 22/4/2016 trên arXiv (kho bản thảo khoa học); bài được nhận tại hội nghị ICPC 2016. Họ định nghĩa "truck factor" là số người tối thiểu phải rời đi trước khi dự án tê liệt. Với 133 dự án phổ biến trên GitHub, 65% có truck factor không quá 2.

Giới hạn: đó là dự án mã nguồn mở nổi tiếng, giá trị do thuật toán ước tính, và chỉ 53% câu trả lời hợp lệ của nhà phát triển ủng hộ hoặc ủng hộ một phần. Chưa có số đo tương đương cho Việt Nam.

Tài liệu dự án phần mềm: bộ tối thiểu gồm những gì

Hướng dẫn Documentation Best Practices của Google viết rằng tập nhỏ tài liệu mới và chính xác tốt hơn cả đống tài liệu hư hỏng.

Dưới đây là khung tham khảo của Click Star, không lấy từ nguồn ngoài. Mỗi tài liệu trả lời 1 câu hỏi của người kế nhiệm.

• README: dự án làm gì và chạy trên máy mới thế nào.
• Kiến trúc 1 trang: hệ thống gồm những khối nào, dữ liệu đi đâu, nối với dịch vụ ngoài nào.
• ADR: vì sao chọn công cụ hay cách làm này mà không chọn cách khác.
• Runbook: khi có sự cố thì kiểm tra gì, làm gì, theo thứ tự nào.
• Hồ sơ bàn giao: hệ thống nào, tài khoản nào, ai giữ quyền, liên hệ ai. Chỉ ghi nơi giữ khóa, không ghi giá trị khóa.

README: người mới có chạy được dự án không

README là tệp giới thiệu nằm trong thư mục dự án. Theo GitHub Docs, README thường nêu dự án làm gì, vì sao hữu ích, bắt đầu thế nào, hỏi ở đâu và ai bảo trì.

GitHub khuyên README chỉ chứa thông tin cần để bắt đầu, còn tài liệu dài hơn nên để ở wiki (trang tài liệu chung của đội). Hướng dẫn README của Google thêm đầu mối liên hệ và trạng thái (ví dụ không còn khuyến nghị dùng).

Phép thử của Click Star: nhờ 1 người chưa từng làm dự án chạy theo README trên máy sạch. Chỗ họ vướng chính là chỗ README còn thiếu.

ADR: ghi lại vì sao đã chọn như vậy

ADR (Architecture Decision Record, tức bản ghi quyết định kiến trúc) là 1 tệp ngắn ghi 1 quyết định quan trọng và lý do. Theo trang adr.github.io, tập hợp các ADR của dự án tạo thành sổ quyết định.

Nygard đề xuất mỗi ADR có 5 phần: tiêu đề, bối cảnh, quyết định, trạng thái, hệ quả. Mỗi bản dài 1 đến 2 trang và lưu cùng kho mã.

Quyết định nào đáng có ADR? Nygard và AWS cùng nêu: quyết định ảnh hưởng cấu trúc, yêu cầu phi chức năng (như bảo mật), mức gắn kết giữa các thành phần, giao diện kết nối và kỹ thuật xây dựng (thư viện, công cụ). Microsoft Learn (trang ghi "Last updated on 2026-04-13") thêm: lựa chọn khó đảo ngược, và nên ghi cả phương án đã loại.

Theo AWS Prescriptive Guidance, ADR ở trạng thái "Proposed" (đề xuất) được cả đội xem xét, rồi chấp nhận, hoặc từ chối kèm lý do. AWS nêu rõ ADR đã chấp nhận thì không sửa. Khi có hiểu biết mới, đội đề xuất ADR mới và ADR cũ chuyển sang "Superseded" (đã bị thay thế). Nygard cũng giữ bản cũ để người sau biết trước đây đã quyết định gì.

Runbook: bước làm khi hệ thống gặp sự cố

Runbook là tài liệu mô tả từng bước để đạt 1 kết quả cụ thể. Theo AWS Well-Architected (OPS07-BP03), runbook đơn giản nhất là 1 danh sách kiểm. AWS yêu cầu nêu kết quả mong muốn, công cụ và quyền cần có, cách xử lý lỗi, cách báo lên cấp trên và người sở hữu.

AWS tách runbook với playbook. Theo AWS (OPS07-BP04), playbook là hướng dẫn điều tra sự cố để tìm nguyên nhân gốc, còn runbook là bước xử lý nguyên nhân đó. Google SRE (đội kỹ sư vận hành độ tin cậy hệ thống) dùng 1 từ là playbook cho cả điều tra lẫn xử lý.

AWS khuyên nhờ 1 thành viên khác chạy thử runbook trước khi coi là xong. Mức chi tiết còn tranh luận: theo Google SRE Workbook (chương On-Call, tức trực sự cố), một số kỹ sư Google muốn mục chung chung để ít phải sửa, số khác muốn từng bước. Nếu playbook chỉ là danh sách lệnh giống nhau mỗi lần, sách khuyên tự động hóa.

Click Star đã có bài riêng về giám sát website và về sao lưu, khôi phục. Một runbook tối thiểu (khung tham khảo của Click Star) gồm: triệu chứng, cách xác nhận, các bước xử lý theo thứ tự, khi nào báo người khác, cách kiểm tra đã khắc phục.

Diátaxis: vì sao tài liệu hay khó đọc

Theo trang giới thiệu của Diátaxis (diataxis.fr), có 4 kiểu tài liệu cho 4 nhu cầu khác nhau, mỗi kiểu có cách viết riêng.

• Hướng dẫn học (tutorial): bài học dẫn tay người mới, họ làm và rút ra kỹ năng.
• Hướng dẫn làm (how-to guide): giải 1 bài toán thực tế cho người đã có nghề.
• Tham chiếu (reference): mô tả trung lập, đầy đủ về sản phẩm, như API hay hàm.
• Giải thích (explanation): bối cảnh và lý do, trả lời "vì sao".

Theo la bàn của Diátaxis, hướng dẫn học và giải thích phục vụ việc học; hướng dẫn làm và tham chiếu phục vụ công việc đang làm. Diátaxis nói làm nhòe ranh giới giữa các kiểu là gốc của rất nhiều vấn đề tài liệu. Theo trang Reference của Diátaxis, tài liệu tham chiếu chỉ nên mô tả; muốn hướng dẫn hay giải thích thì đặt liên kết sang bài khác.

Diátaxis không nhắc ADR hay runbook trong các trang đã đọc. Cách gán là của Click Star: bước chạy lần đầu trong README gần hướng dẫn học; runbook là hướng dẫn làm; mô tả API là tham chiếu; ADR và kiến trúc là giải thích.

Ai giữ cho tài liệu không cũ

Tài liệu cũ gây hại vì nó trông đáng tin dù đã sai. Hướng dẫn của Google nói tài liệu chết làm người đọc hiểu sai, làm chậm việc và gây nản.

Sách Software Engineering at Google (chương Documentation) kể lại: tài liệu trên wiki không có chủ thì lỗi thời và trùng lặp.

Khi chuyển vào kho mã, có chủ và qua đánh giá như mã, chất lượng cải thiện rõ. Sách đề xuất đối xử với tài liệu như mã: có quy định, nằm trong kiểm soát phiên bản, có chủ, đổi cùng mã, theo dõi lỗi và kiểm tra định kỳ.

Hướng dẫn của Google yêu cầu sửa tài liệu trong cùng thay đổi với mã, và nếu tài liệu đã xuống cấp thì xóa trước những gì chắc chắn sai. Sách Software Engineering at Google còn kể Google ghi chủ sở hữu và "ngày xem lại" vào tài liệu, hệ thống nhắc khi quá lâu (ví dụ 3 tháng).

Đừng ghi bí mật vào tài liệu

README, wiki và tài liệu vận hành rất dễ bị dán nhầm mật khẩu hay khóa API cho tiện. Theo GitHub Docs, secret scanning quét toàn bộ lịch sử Git trên mọi nhánh, cùng mô tả và bình luận trong issue, pull request, discussion và wiki.

Kho công khai được quét miễn phí; kho riêng của tổ chức cần bật GitHub Secret Protection trên gói Team hoặc Enterprise Cloud. Khi lộ khóa, GitHub khuyên đổi khóa ngay.

Vì vậy tài liệu chỉ ghi khóa nằm ở đâu và ai cấp quyền, không ghi giá trị. Click Star đã có bài riêng về quản lý khóa API và bí mật.

Ý nghĩa với doanh nghiệp Việt Nam

Theo quan sát của Click Star (chưa có số đo), doanh nghiệp nhỏ thuê đội ngoài hoặc chỉ có 1 đến 2 người kỹ thuật trong nhà, nên tri thức tập trung ở rất ít người. Với dự án thuê ngoài, tài liệu nên là sản phẩm bàn giao có tiêu chí nghiệm thu, ví dụ người của bên mua chạy được dự án theo README trên máy sạch.

Bài của Click Star về làm phần mềm theo yêu cầu liệt kê mục bàn giao trong hợp đồng: kho mã có lịch sử, tài liệu kiến trúc, mô hình dữ liệu, mô tả API, hướng dẫn vận hành, quyền tài khoản hạ tầng. Quyền sở hữu mã là câu hỏi pháp lý, hãy hỏi luật sư.

Click Star làm phần mềm theo yêu cầu nên có lợi ích liên quan; các yêu cầu trên nên áp dụng cho mọi bên làm, kể cả Click Star.

Đánh giá của Click Star. Với dự án nhỏ, README và runbook cho sự cố hay gặp mang lại giá trị sớm nhất. ADR nên bắt đầu bằng vài quyết định gần đây, chưa cần dựng lại cả lịch sử. Click Star ưu tiên ít tài liệu nhưng đúng, và coi việc người lạ chạy được dự án là phép thử đáng tin hơn số trang.

Cách đo

Khung tham khảo của Click Star, chưa có chuẩn chung; hãy so đội với chính mình theo thời gian.

• Thời gian chạy lần đầu: từ lúc người chưa từng làm dự án nhận README đến khi dự án chạy trên máy họ.
• Quyết định có ADR: trong các quyết định lớn gần đây, bao nhiêu quyết định có ADR.
• Ngày xem lại: tài liệu nào có chủ, tài liệu nào quá hạn xem lại do đội đặt.
• Sau mỗi sự cố: có dùng runbook không, bước nào sai hoặc thiếu, đã sửa chưa.

Lộ trình 30 ngày

Khung tham khảo của Click Star, không lấy từ nguồn ngoài, nhằm cứu tri thức đang nằm trong đầu 1 hay 2 người trước khi họ rời đi.

• Tuần 1: liệt kê hệ thống, tài khoản và người giữ quyền; chạy dự án trên máy sạch và viết README nháp; hỏi người sắp rời đi.
• Tuần 2: hoàn thiện README theo phép thử người lạ; viết runbook cho 3 sự cố gần nhất; ghi nơi giữ khóa.
• Tuần 3: vẽ kiến trúc 1 trang; viết ADR cho các quyết định lớn gần nhất; lưu ADR trong docs/decisions.
• Tuần 4: nhờ người ngoài dự án chạy thử theo tài liệu; đặt chủ và ngày xem lại cho từng tài liệu; thêm dòng "đã cập nhật tài liệu" vào danh sách kiểm.

Những sai lầm thường gặp

1. Để tài liệu không có chủ và ngày xem lại, rồi để mã đổi mà tài liệu không đổi theo.
2. Sửa ADR cũ khi đổi ý, làm mất dấu vì sao ngày trước đã chọn khác.
3. Viết runbook mà chưa ai ngoài tác giả chạy thử.
4. Dán mật khẩu, khóa hay chuỗi kết nối vào README hoặc wiki.
5. Trộn hướng dẫn, giải thích và tham chiếu vào 1 trang.

Điều chưa biết

Click Star không có số đo độc lập về chi phí mất tri thức khi người giữ dự án rời đi, ở Việt Nam hay nơi khác. Nghiên cứu truck factor thực hiện năm 2016 trên dự án mã nguồn mở.

Chu kỳ xem lại, mức chi tiết của runbook và số ADR hợp lý chưa có chuẩn chung; Click Star không tìm thấy số đo về lợi ích của từng loại tài liệu.

Điều kiện bật secret scanning được đọc từ 1 trang GitHub Docs và có thể đổi theo gói.