Mở đầu — vì sao bài này quan trọng
Hãy tưởng tượng bạn vừa nhận vai trò tech lead cho một team 8 người. Trong tuần đầu tiên, bạn nhận ra một sự thật đáng sợ: có một service thanh toán chạy production, xử lý hàng tỷ đồng mỗi tháng, nhưng người duy nhất hiểu cách nó hoạt động đã nghỉ việc cách đây 6 tháng. Không có tài liệu. Chỉ có code, một vài comment rời rạc, và một câu nói truyền miệng "đừng động vào cái đó, nó tự chạy được".
Đây không phải câu chuyện hiếm. Đây là hệ quả trực tiếp của việc một tổ chức không có documentation culture — văn hóa viết và duy trì tài liệu. Và điều quan trọng nhất bạn cần hiểu ngay từ đầu: documentation culture không phải thứ bạn "thêm vào sau khi rảnh". Nó phải được xây từ Ngày 1, bởi vì một khi team đã quen với việc không viết gì, việc đảo ngược thói quen đó khó gấp nhiều lần so với việc xây nó ngay từ đầu.
Với tư cách tech lead, tài liệu không phải "việc phụ". Nó là một trong những đòn bẩy mạnh nhất để bạn nhân bản chính mình — để kiến thức không nằm mắc kẹt trong đầu vài người, để onboarding nhanh hơn, để quyết định không bị bàn đi bàn lại, và để team có thể scale mà không sụp đổ. Bài này sẽ giúp bạn hiểu vì sao documentation thường yếu, và làm thế nào để xây một văn hóa tài liệu bền vững ngay từ đầu.
Khái niệm cốt lõi
Vì sao documentation culture thường yếu?
Trước khi sửa một vấn đề, bạn phải hiểu tại sao nó tồn tại. Có ba nguyên nhân gốc rễ khiến tài liệu ở hầu hết các tổ chức đều yếu:
Thứ nhất, doc không có ROI ngay lập tức. Khi bạn viết code, bạn thấy kết quả ngay — feature chạy, test pass, khách hàng dùng được. Khi bạn viết tài liệu, phần thưởng đến trong tương lai và cho người khác: một đồng nghiệp 3 tháng sau đỡ mất nửa ngày mò mẫm. Bộ não con người rất kém trong việc đánh đổi công sức hiện tại lấy lợi ích tương lai mơ hồ. Vì thế doc luôn thua trong cuộc cạnh tranh ưu tiên.
Thứ hai, engineer thích code hơn viết. Đây là sự thật cần thừa nhận thẳng thắn. Nhiều kỹ sư chọn nghề này một phần vì họ thích làm việc với máy tính hơn với ngôn ngữ. Viết một đoạn văn giải thích rõ ràng đòi hỏi kỹ năng khác hẳn viết code, và nhiều người thấy nó vừa khó vừa chán. Khi không có cấu trúc hỗ trợ, họ sẽ né tránh.
Thứ ba, doc nhanh chóng lỗi thời (stale). Đây là lý do nguy hiểm nhất. Code thay đổi mỗi ngày, nhưng tài liệu thì không tự cập nhật. Một tài liệu sai còn tệ hơn không có tài liệu — vì nó khiến người đọc tin vào thông tin đã lỗi thời, đưa ra quyết định sai, rồi mất niềm tin vào toàn bộ hệ thống tài liệu. Chỉ cần vài lần bị "lừa" bởi doc cũ, cả team sẽ ngừng đọc và ngừng viết.
Nhưng chi phí của việc thiếu doc là gì?
Ghi chú gốc của bài này bỏ lửng ở chữ "re-". Hãy hoàn thành nó, vì đây chính là trái tim của lập luận: chi phí của thiếu doc = re-discovery (khám phá lại). Mỗi khi ai đó cần hiểu một hệ thống mà không có tài liệu, họ phải:
- Re-discover: đọc lại toàn bộ code để hiểu logic vốn đã có người hiểu trước đó.
- Re-explain: người biết phải giải thích lại bằng miệng, lặp đi lặp lại cho từng người mới.
- Re-debate: những quyết định đã từng được cân nhắc kỹ bị mang ra tranh luận lại vì không ai nhớ lý do ban đầu.
- Re-implement: tệ nhất là làm lại từ đầu vì không ai dám động vào phần "hộp đen".
Không phải mọi tài liệu đều bằng nhau
Một hiểu lầm phổ biến là "viết nhiều doc = tốt". Sai. Có nhiều loại tài liệu, và bạn cần biết loại nào đáng đầu tư:
- Tài liệu bền (durable): kiến trúc hệ thống, lý do đằng sau quyết định, quy trình vận hành (runbook), khái niệm domain. Những thứ này thay đổi chậm và có giá trị lâu dài — đây là nơi đầu tư.
- Tài liệu dễ hỏng (brittle): chi tiết implementation cụ thể, tên biến, các bước bấm nút. Những thứ này thay đổi liên tục và nên để code tự nói (self-documenting code), hoặc tự sinh ra từ code.
Tình huống thực tế
Ví dụ 1: Startup fintech ở TP.HCM và cái giá của "hộp đen"
Một startup fintech tại TP.HCM (gọi là công ty A) tăng trưởng nhanh từ 12 lên 40 kỹ sư trong 18 tháng. Trong giai đoạn đầu, họ chạy theo tốc độ — "ship trước, viết sau". Kết quả là service tính lãi suất khoản vay, phần lõi của nghiệp vụ, chỉ có duy nhất một senior engineer tên Tuấn hiểu trọn vẹn.
Khi Tuấn xin nghỉ 3 tuần về quê cưới vợ, một bug tính sai lãi phát sinh trong production. Team mất 2 ngày chỉ để hiểu logic — đọc code, dò từng dòng, gọi điện làm phiền Tuấn giữa đám cưới. Con số thiệt hại: khoảng 200 khách hàng bị tính sai lãi, một khoản bồi thường và mất uy tín, cộng với 2 ngày công của 4 engineer.
Sau sự cố, CTO đưa ra một quy định đơn giản: mỗi service "critical" phải có một trang runbook và một trang "domain logic" giải thích công thức nghiệp vụ và lý do. Bài học rút ra: tài liệu không phải để cho bạn, nó là bảo hiểm cho tổ chức khi bạn vắng mặt. Và điểm mấu chốt — họ chỉ nhận ra giá trị này sau khi trả giá đắt, thay vì xây từ Ngày 1.
Ví dụ 2: GitLab và triết lý "handbook-first"
GitLab là ví dụ kinh điển về documentation culture xây từ gốc. Là công ty remote hoàn toàn với hơn 2000 nhân viên trải khắp thế giới, họ áp dụng nguyên tắc "if it's not in the handbook, it doesn't exist" (nếu nó không có trong sổ tay, coi như nó không tồn tại). Handbook của họ public, dài hàng nghìn trang, và mọi quy trình — từ cách deploy đến cách nghỉ phép — đều được viết ra.
Điều đáng học không phải là độ dài, mà là cơ chế: khi có bất kỳ câu hỏi nào, câu trả lời mặc định là "hãy viết nó vào handbook rồi gửi link". Việc trả lời câu hỏi trở thành hành động tạo tài liệu, thay vì giải thích miệng một lần rồi mất. Điều này biến documentation từ "việc phụ tốn thời gian" thành "cách làm việc mặc định". Bài học rút ra: văn hóa tài liệu mạnh khi việc viết được nhúng vào luồng công việc hằng ngày, chứ không phải một hoạt động tách rời.
Ví dụ 3: Team platform ở một công ty e-commerce Đông Nam Á
Một công ty thương mại điện tử lớn ở Đông Nam Á (giả định là công ty B, quy mô vài trăm engineer) từng có tình trạng "doc nghĩa địa" — một Confluence khổng lồ với hàng nghìn trang, phần lớn đã lỗi thời. Không ai tin tài liệu nào còn đúng, nên không ai đọc, và vòng luẩn quẩn tiếp diễn.
Tech lead của team platform áp dụng một giải pháp thông minh: gắn owner và review date vào mỗi tài liệu quan trọng. Mỗi quý, hệ thống tự động ping owner: "Tài liệu này còn đúng không? Xác nhận hoặc cập nhật hoặc archive." Trong 6 tháng, số trang giảm từ khoảng 3000 xuống còn 400 trang "sống", nhưng độ tin cậy tăng vọt. Team bắt đầu đọc lại, và quan trọng hơn, bắt đầu viết lại. Bài học rút ra: chống stale không phải bằng cách viết nhiều hơn, mà bằng cách coi tài liệu như code — có owner, có review, có vòng đời rõ ràng, và mạnh dạn xóa cái đã chết.
Hướng dẫn từng bước
Đây là lộ trình cụ thể để xây documentation culture, đặc biệt khi bạn đang bắt đầu một team hoặc dự án mới.
Bước 1 — Định nghĩa "documentation tối thiểu" cho mỗi loại việc. Đừng bắt team viết mọi thứ. Hãy quy định rõ: mỗi service phải có README (chạy thế nào, deploy thế nào), mỗi quyết định lớn phải có một ghi chú "tại sao", mỗi quy trình vận hành phải có runbook. Danh sách này càng ngắn càng dễ tuân thủ.
Bước 2 — Chọn một nơi duy nhất (single source of truth). Kiến thức phân tán khắp Slack, email, Google Docs, Confluence là kẻ thù của tài liệu. Chọn một nền tảng, và ra quy tắc: câu trả lời quan trọng phải "hạ cánh" ở đó. Với nhiều team, để doc nằm ngay trong repo (dạng Markdown, "docs-as-code") là lựa chọn tốt vì nó được review cùng code.
Bước 3 — Nhúng việc viết vào luồng công việc. Thêm một mục "Documentation" vào Definition of Done. Một pull request không được merge nếu nó thay đổi hành vi nhưng không cập nhật README hay doc liên quan. Khi viết trở thành một phần của "làm xong", nó ngừng là việc tùy hứng.
Bước 4 — Biến câu hỏi thành tài liệu. Đây là mẹo mạnh nhất. Mỗi lần ai đó hỏi bạn một câu trong Slack, thay vì trả lời trực tiếp, hãy viết câu trả lời vào doc rồi gửi link. Lần đầu tốn thêm 5 phút, nhưng lần thứ hai, thứ ba, bạn chỉ cần gửi lại link. Bạn đang xây tài liệu bằng chính công việc bạn vẫn phải làm.
Bước 5 — Gán owner và vòng đời cho tài liệu. Mỗi doc quan trọng cần một người chịu trách nhiệm và một ngày review. Tài liệu không có chủ sẽ chết. Định kỳ (mỗi quý), rà soát: cái nào còn đúng thì xác nhận, cái nào sai thì sửa, cái nào chết thì archive không thương tiếc.
Bước 6 — Làm gương từ vị trí tech lead. Đây là bước quan trọng nhất về mặt văn hóa. Nếu bạn — người dẫn dắt — không viết, không ai sẽ viết. Hãy viết công khai các quyết định của bạn, khen ngợi công khai người viết tài liệu tốt, và tham chiếu doc trong các cuộc họp ("theo runbook thì..."). Văn hóa được định hình bởi hành vi bạn thưởng và hành vi bạn làm gương, chứ không phải bởi khẩu hiệu.
Lỗi thường gặp & mẹo
Lỗi 1 — Viết quá nhiều, quá chi tiết. Nhiều người mới nghĩ documentation culture nghĩa là viết tài liệu dài về mọi thứ. Kết quả là tài liệu quá dài không ai đọc, và quá chi tiết nên lỗi thời chỉ sau một tuần. Mẹo: viết ngắn, tập trung vào "tại sao" và bức tranh tổng thể; để chi tiết cho code.
Lỗi 2 — Coi doc là dự án một lần rồi bỏ. Nhiều team tổ chức một "documentation sprint" hoành tráng, viết được một đống, rồi không bao giờ đụng lại. Sáu tháng sau tất cả đều lỗi thời. Mẹo: documentation là dòng chảy liên tục, không phải sự kiện. Viết một chút mỗi ngày tốt hơn viết nhiều một lần.
Lỗi 3 — Không xóa tài liệu chết. Vì tâm lý "biết đâu có ích", team giữ lại mọi trang cũ. Nhưng tài liệu sai làm ô nhiễm cả kho, khiến người ta mất niềm tin. Mẹo: mạnh dạn archive. Một kho tài liệu nhỏ nhưng đáng tin giá trị hơn nhiều một kho lớn đầy rác.
Lỗi 4 — Phạt thay vì thưởng. Ép buộc bằng cách trách móc người không viết chỉ tạo ra tài liệu đối phó, viết cho có. Mẹo: khen ngợi công khai, đưa "chất lượng tài liệu" vào tiêu chí đánh giá thăng tiến, và khiến việc viết dễ dàng nhất có thể (template sẵn, công cụ tốt).
Mẹo bổ sung — Dùng template. Con người sợ trang giấy trắng. Cung cấp sẵn các mẫu (template) cho README, runbook, ghi chú quyết định giúp giảm ma sát khổng lồ. Người viết chỉ cần điền vào chỗ trống thay vì tự nghĩ cấu trúc.
Mẹo — Đặt tài liệu gần nơi cần dùng. Doc về deploy nên nằm cạnh code deploy. Doc về on-call nên xuất hiện trong kênh incident. Tài liệu ở xa nơi dùng thì bị bỏ quên.
Bài tập thực hành
Bài 1 — Audit tài liệu hiện tại. Chọn một service quan trọng trong team bạn. Trả lời: nếu người hiểu rõ nhất về nó nghỉ ngày mai, team mất bao lâu để một người mới vận hành được? Viết ra ba mảnh kiến thức đang chỉ nằm trong đầu ai đó và chưa được ghi lại ở đâu.
Bài 2 — Viết một runbook tối thiểu. Chọn một tình huống vận hành thực tế (ví dụ: "service X bị chậm phải làm gì"). Viết một runbook ngắn dưới 1 trang gồm: dấu hiệu nhận biết, các bước kiểm tra theo thứ tự, cách khắc phục, và ai cần liên hệ khi bí. Nhờ một đồng nghiệp thử làm theo mà không hỏi bạn, xem có làm được không.
Bài 3 — Thử nghiệm "câu hỏi thành tài liệu" trong 1 tuần. Trong 5 ngày làm việc tới, mỗi khi ai đó hỏi bạn một câu về hệ thống, hãy viết câu trả lời vào doc rồi gửi link. Cuối tuần, đếm xem bạn tạo được bao nhiêu trang, và có câu nào bạn đã phải gửi lại link lần thứ hai không.
Bài 4 — Thiết kế "Documentation tối thiểu" cho team. Viết ra danh sách ngắn (tối đa 5 mục) những tài liệu bắt buộc phải có cho mỗi loại công việc trong team bạn. Sau đó thêm một mục "Documentation" vào Definition of Done và thảo luận với team.
Tóm tắt
Documentation culture yếu ở hầu hết tổ chức vì ba lý do: doc không có ROI ngay, engineer thích code hơn viết, và doc nhanh chóng lỗi thời. Nhưng chi phí thật của việc thiếu doc là re-discovery — team liên tục phải khám phá lại, giải thích lại, tranh luận lại và làm lại những thứ vốn đã có người hiểu. Chi phí này ẩn nhưng khổng lồ.
Điểm cốt lõi cần nhớ:
- Xây từ Ngày 1, vì đảo ngược thói quen "không viết" khó hơn nhiều lần so với xây thói quen viết ngay từ đầu.
- Viết về "tại sao", để code nói "cái gì" và "như thế nào". Ưu tiên tài liệu bền, bỏ qua tài liệu dễ hỏng.
- Nhúng việc viết vào luồng công việc: đưa vào Definition of Done, biến câu hỏi thành tài liệu, dùng single source of truth.
- Chống stale bằng cách coi doc như code: có owner, có review date, và mạnh dạn xóa tài liệu chết. Một kho nhỏ đáng tin hơn một kho lớn đầy rác.
- Tech lead phải làm gương: viết công khai, thưởng cho người viết tốt, tham chiếu doc trong công việc. Văn hóa được định hình bởi hành vi bạn làm gương, không phải khẩu hiệu.