Documentation Culture – Tại sao thời đại AI lại cần viết doc hơn bao giờ hết

Xin chào, mình là Khoa. Hôm nay trên Fx Studio, chúng ta sẽ cùng bàn về một chủ đề nghe có vẻ “cũ” nhưng lại đang nóng trở lại theo cách ít ai ngờ — Documentation Culture, tức văn hóa viết tài liệu trong team phát triển phần mềm.

Đây là phần tiếp theo trong mạch bài về văn hóa developer. Nếu bạn đã đọc bài Reading Culture – Văn hóa đọc trong thời đại AI, thì bài này có thể xem như mặt còn lại của cùng một đồng xu. Một bên là chuyện đọc. Còn bên này là chuyện viết ra cái để người khác đọc.

Đôi lời tản mạn

Bạn đã bao giờ mở lại một file code mình viết hai năm trước chưa? Không một dòng comment, không README, không một manh mối nào về việc tại sao đoạn logic kỳ lạ kia lại tồn tại. Bạn ngồi đọc, cau mày, rồi tự hỏi: “Ai viết cái này vậy?” — để rồi nhận ra đó chính là mình.

Mình từng ở đúng tình huống đó nhiều lần. Và mỗi lần như vậy, mình lại thấm một điều: code kể cho bạn nghe nó đang làm gì, nhưng hiếm khi kể tại sao nó được viết như thế.

Gần đây, câu chuyện còn có thêm một lớp mới. Khi các AI coding assistant như Copilot, Cursor hay Claude Code trở nên phổ biến, mình nghe không ít người nói: “Thời buổi này cần gì viết doc, hỏi AI là xong.” Nghe cũng có lý — nhưng mình thấy nó thiếu thiếu điều gì đó.

Bài viết này là góc nhìn cá nhân của mình về Documentation Culture: doc thật ra là gì, tại sao nhiều team viết doc mà không ai đọc, và tại sao — khá bất ngờ — thời đại AI lại khiến việc viết doc quan trọng hơn chứ không phải ít đi. Đây không phải một bài giảng kiểu “hãy chăm viết tài liệu”. Mà là vài điều mình đúc kết được sau nhiều năm làm việc trong các team thực tế.

Documentation là gì? – Đừng nhầm với “viết cho có”

Trước khi đi xa hơn, mình muốn làm rõ một hiểu lầm phổ biến: documentation không phải là việc giải thích code làm gì.

Nếu một dòng comment chỉ lặp lại đúng những gì code đã nói, nó là comment thừa. Code tốt tự nó đã nói được phần what — biến này tên gì, hàm này trả về cái gì, vòng lặp chạy bao nhiêu lần. Bạn không cần một dòng chú thích // tăng i lên 1 cho dòng i++.

Giá trị thật của documentation nằm ở phần mà code không nói được: phần why.

Code cho bạn biết hệ thống làm gì. Documentation cho bạn biết tại sao nó được làm như thế — và tại sao những cách khác đã bị loại bỏ.

Tại sao team chọn kiến trúc này thay vì kiến trúc kia? Cái workaround xấu xí ở dòng 200 vì đâu mà cần thiết — hóa ra nó vá một bug của thư viện bên thứ ba? Còn API kia, tại sao lại nhận tham số theo thứ tự lạ đời như vậy? Đây là những thứ không nằm trong code, chỉ nằm trong đầu người viết. Và khi người đó rời team, kiến thức ấy biến mất theo.

Documentation cũng không chỉ có một dạng. Trong thực tế, nó gồm nhiều loại với mục đích khác nhau:

Trong số này, ADR (Architecture Decision Record) là khái niệm mình muốn nhấn mạnh — vì nó đúng tinh thần “ghi lại cái why” nhất. Mình sẽ nói kỹ hơn ở phần sau.

Tại sao Documentation Culture quan trọng?

Có nhiều lý do, nhưng dưới đây là bốn điểm mình thấy tác động trực tiếp nhất đến team.

1. Giảm “bus factor”

Có một khái niệm hơi đen tối nhưng rất thật trong ngành: bus factor — số người trong team mà nếu họ “bị xe buýt tông” (nói vui là rời đi đột ngột), dự án sẽ đứng hình. Nếu bus factor của bạn bằng 1, nghĩa là toàn bộ hiểu biết về một phần hệ thống chỉ nằm trong đầu đúng một người.

Documentation là cách rẻ nhất để nâng con số đó lên. Khi cái why được ghi ra, kiến thức không còn bị khóa trong một bộ não duy nhất. Người mới có thể đọc và hiểu, thay vì phải đi “khai quật” qua từng commit cũ.

2. Onboarding nhanh hơn

Hãy nhớ lại lần gần nhất bạn join một dự án mới. Bạn cần bao lâu để hiểu được codebase? Một tuần? Một tháng?

Tài liệu tốt rút ngắn quãng thời gian đó. Thay vì hỏi đi hỏi lại đồng nghiệp (và làm gián đoạn công việc của họ), member mới có thể tự đọc README, lướt qua các ADR để hiểu được vì sao hệ thống có hình dạng hiện tại. Như tài liệu của Microsoft Azure về ADR nhận xét, người mới có thể đọc qua các quyết định để nắm được hành trình kiến trúc và hiện trạng của hệ thống.

3. Là “bộ nhớ dài hạn” của team

Trí nhớ con người có hạn. Quyết định bạn đưa ra hôm nay, sáu tháng sau bạn sẽ quên gần hết lý do. Tài liệu của Microsoft Azure về ADR diễn đạt điều này khá hay: một quyết định được đưa ra nhưng không bao giờ ghi lại thì gần như chắc chắn sẽ bị lãng quên, dẫn đến những cuộc tranh luận lặp lại hoặc thay đổi sau này vô tình đi ngược lại ý định ban đầu.

Documentation đóng vai trò bộ nhớ ngoài cho cả team. Nó giữ lại bối cảnh mà não người để rơi rớt theo thời gian.

4. Giảm gián đoạn

Mỗi câu hỏi “ê, chỗ này hoạt động sao vậy?” là một lần ai đó bị kéo ra khỏi luồng tập trung. Khi câu trả lời đã nằm sẵn trong tài liệu, số lần gián đoạn giảm đi. Người hỏi tự tìm được, người bị hỏi được yên tĩnh làm việc. Cả hai cùng lợi.

Những vấn đề thường gặp

Lý thuyết thì đẹp. Nhưng trên thực tế, văn hóa tài liệu ở nhiều team đang gặp vấn đề. Dưới đây là những tình huống mình hay gặp nhất.

Tài liệu lỗi thời – kẻ thù đáng ngại hơn cả không có tài liệu

Mình xem đây là vấn đề đáng lưu ý nhất. Một tài liệu sai còn rủi ro hơn không có tài liệu nào — vì nó khiến người đọc tin vào thông tin đã cũ.

Khi không có doc, ít nhất bạn biết mình phải đi đọc code hoặc hỏi người khác. Nhưng khi có một trang doc trông gọn gàng, đầy đủ, bạn sẽ tin nó. Để rồi làm theo và dính một quyết định đã bị thay đổi từ đời nào.

Tài liệu cũ không tự phát tín hiệu báo rằng nó đã cũ. Nó vẫn nằm đó, vẫn trông đáng tin — và đó mới là phần khó.

“Viết cho có” để qua review

Nhiều team đặt ra luật “PR phải có doc mới được merge”. Nghe thì tốt. Nhưng khi viết doc trở thành thủ tục bắt buộc thay vì nhu cầu thật, kết quả là những đoạn mô tả qua loa, viết cho đủ ô, chẳng ai đọc lại.

Doc kiểu này không tạo ra giá trị. Nó chỉ tạo ra cảm giác an toàn giả, và tốn công của cả người viết lẫn người review.

Tài liệu sống ở nơi không ai tìm thấy

Bạn viết một tài liệu công phu. Vấn đề là: nó nằm trong một Google Doc cá nhân, link chia sẻ trong một tin nhắn Slack từ ba tháng trước, giờ đã trôi mất. Về mặt lý thuyết tài liệu tồn tại. Nhưng trên thực tế, nó vô hình.

Tài liệu chỉ có giá trị khi người cần nó tìm được nó — đúng lúc cần.

Over-documentation

Ở thái cực ngược lại, có những team viết quá nhiều. Mỗi hàm getter/setter đều có một đoạn mô tả dài dòng. Mỗi thay đổi nhỏ đều kéo theo ba trang tài liệu. Kết quả là không ai theo kịp, và đống tài liệu khổng lồ đó nhanh chóng lỗi thời.

Cuốn Software Engineering at Google có một quan sát đáng suy ngẫm về điểm này: tài liệu lớn gần như không bao giờ được cập nhật; chỉ những tài liệu nhỏ, dạng module, mới có cơ hội được giữ cho đúng. Viết nhiều không bằng viết đúng chỗ.

Documentation trong thời đại AI

Phần này mình thấy thú vị nhất — và cũng là lý do mình muốn viết lại bài này vào thời điểm hiện tại.

Lập luận “có AI rồi, cần gì viết doc” nghe hợp lý trên bề mặt. Nhưng khi nhìn kỹ vào cách các công cụ AI thật sự hoạt động, bạn sẽ thấy điều ngược lại: AI khiến documentation quan trọng hơn, theo ba hướng.

AI tiêu thụ documentation để làm việc

Một AI coding assistant tốt đến đâu cũng chỉ tốt bằng phần context bạn đưa cho nó. Trong bài My LLM coding workflow going into 2026, Addy Osmani đúc kết một câu mình thấy rất đúng: LLM chỉ tốt ngang với context bạn cung cấp — hãy cho nó thấy code, tài liệu và ràng buộc liên quan.

Khi codebase của bạn có tài liệu rõ ràng, AI hiểu được bối cảnh: naming convention, kiến trúc, các ràng buộc kỹ thuật. Nó sinh ra code phù hợp với hệ thống. Khi codebase không có gì ngoài code trần, AI phải đoán — và nó đoán dựa trên những gì phổ biến trên internet, chưa chắc đúng với dự án của bạn.

Đây cũng là lý do gần đây xuất hiện các quy ước như file CLAUDE.md, llms.txt hay skill.md — về bản chất, chúng là tài liệu viết riêng cho AI đọc. Documentation không biến mất; nó chỉ có thêm một loại độc giả mới.

Trước đây bạn viết doc cho đồng nghiệp. Giờ bạn viết doc cho cả đồng nghiệp lẫn con AI đang ngồi gõ code cùng bạn.

Mức độ phụ thuộc này lớn đến đâu? Theo số liệu nội bộ mà Mintlify — một nền tảng documentation — công bố trong bài The value of llms.txt: hype or real, gần một nửa lượng truy cập vào các trang tài liệu của họ hiện đến từ các AI agent như Cursor, Claude Code, ChatGPT và Perplexity. Con số này từ một nhà cung cấp nên bạn hãy đọc với chút dè chừng, nhưng xu hướng thì khó phủ nhận: tài liệu ngày nay phục vụ máy đọc không kém gì người đọc.

Tài liệu kém khiến AI sinh code sai

Mặt trái cũng đúng. Khi tài liệu thiếu hoặc sai, AI không chỉ “không giúp được” — nó còn có thể chủ động dẫn bạn đi sai.

Bài viết How to write LLM-friendly documentation của Fern chỉ ra một điểm đáng chú ý: tài liệu API thiếu sót sẽ tạo ra code tích hợp sai khi developer dựa vào AI. AI đọc tài liệu của bạn, thấy nó mô tả một endpoint đã đổi, rồi tự tin sinh ra đoạn code gọi sai. Code chạy được, trông mạch lạc — nhưng sai.

Nói cách khác, trong thế giới có AI, tài liệu lỗi thời được nhân bản tác hại. Trước đây một doc sai chỉ làm lạc lối những ai vô tình đọc nó. Giờ nó còn làm lạc lối cả cái máy đang sinh ra hàng trăm dòng code mỗi phút.

AI hỗ trợ viết doc – nhưng không thay được phần “why”

Tin tốt là AI cũng giúp được chiều ngược lại. Nó có thể đọc code và sinh ra bản nháp tài liệu, tóm tắt một PR lớn, hay đề xuất phần mô tả cho một hàm. Đây là việc AI làm khá tốt — vì phần what vốn nằm sẵn trong code, AI chỉ cần diễn đạt lại.

Nhưng phần why thì khác. AI không biết tại sao team bạn chọn hàng đợi thay vì gọi đồng bộ. Nó không biết cái workaround kia ra đời sau một đêm trực sự cố production. Những quyết định ấy là tri thức của con người, sinh ra từ bối cảnh mà AI không có mặt.

AI viết được phần what rất nhanh. Còn phần why — thứ giá trị nhất của documentation — vẫn cần con người. AI tốt nhất khi đóng vai người viết bản nháp đầu tiên; con người là người chốt bản cuối.

Vì vậy, trong thời đại AI, kỹ năng viết tài liệu không mất giá. Nó chuyển trọng tâm: từ “mô tả code làm gì” sang “ghi lại lý do và bối cảnh” — đúng phần mà máy chưa làm thay được.

Xây dựng Documentation Culture lành mạnh

Nói xong vấn đề, giờ đến phần thực hành. Đây là những nguyên tắc mình đúc kết được. Không phải cái nào cũng hợp với mọi team, nhưng ít nhất chúng cho bạn một điểm xuất phát.

Nguyên tắc 1: Viết “why”, đừng viết “what”

Nguyên tắc gốc của cả bài nằm ở đây. Trước khi viết một dòng tài liệu, hãy tự hỏi: cái này code đã tự nói được chưa? Nếu rồi, đừng lặp lại. Hãy dành sức cho phần code không nói được — lý do, đánh đổi, bối cảnh.

Một comment tốt không phải là // lặp qua danh sách user. Mà là // duyệt ngược vì danh sách đã sort tăng dần, ta cần phần tử mới nhất trước.

Nguyên tắc 2: Để tài liệu sống gần code

Tài liệu càng xa code thì càng nhanh lỗi thời. Một trang wiki tách rời sẽ bị quên; một file Markdown nằm ngay trong repo, ngay cạnh code nó mô tả, có cơ hội được cập nhật cùng lúc với code.

Đây chính là tinh thần docs-as-code: tài liệu viết bằng Markdown, đặt trong version control, review qua pull request, đi qua CI giống hệt code. Software Engineering at Google khuyến nghị thẳng rằng tài liệu thường gắn chặt với code đến mức nên được đối xử như code. Nhiều team lớn như Google, Microsoft, GitHub đã áp dụng cách này từ lâu.

Quy tắc đơn giản: nếu sửa code mà không sửa doc trong cùng một PR, doc đó sẽ chết. Hãy để chúng đi cùng nhau.

Nguyên tắc 3: Dùng ADR cho các quyết định lớn

ADR (Architecture Decision Record) là một tài liệu ngắn, ghi lại một quyết định kiến trúc: bối cảnh lúc đó, các lựa chọn đã cân nhắc, lý do chọn cái này và bỏ cái kia. Khái niệm này do Michael Nygard giới thiệu trong bài Documenting Architecture Decisions năm 2011, và sau đó được Thoughtworks đưa vào nhóm “Adopt” trên technology radar.

Điểm hay của ADR là nó nắm đúng phần why. Sáu tháng sau, khi ai đó hỏi “tại sao hồi đó mình làm thế này?”, câu trả lời đã nằm sẵn trong docs/adr/. Không tranh luận lại, không đào lại Slack cũ.

Một lưu ý quan trọng mình rút ra: ADR là point-in-time document — nó ghi lại một quyết định tại một thời điểm, và nên giữ nguyên như vậy. Khi bối cảnh đổi, bạn không sửa ADR cũ, mà viết một ADR mới “thay thế” (superseded) nó. Cách này tránh được cái bẫy mà một phân tích trên Java Code Geeks gọi là “category error”: bắt một tài liệu chụp-tại-một-thời-điểm phải đóng vai một tài liệu sống. ADR không phải để mô tả hiện trạng — nó là một dòng trong lịch sử.

Nguyên tắc 4: Coi doc là một phần của Definition of Done

Nếu doc là việc làm sau cùng “nếu còn thời gian”, nó sẽ không bao giờ được làm. Cách bền vững hơn là đưa nó vào Definition of Done của task: một tính năng chỉ được coi là xong khi code chạy, test pass, và tài liệu liên quan đã cập nhật.

Software Engineering at Google có một nhận xét mình thấy đúng: càng coi tài liệu là “một trong những” việc cần làm của phát triển phần mềm, developer càng bớt khó chịu với chi phí ban đầu của việc viết.

Nguyên tắc 5: Review doc như review code

Nếu team bạn đã có văn hóa code review tốt (mình có viết riêng một bài về Code Review Culture), hãy mở rộng nó sang tài liệu. Khi review một PR, đừng chỉ nhìn code — nhìn cả phần doc đi kèm. Nó có rõ không? Có đúng không? Có thừa không?

Tài liệu được review cũng giống code được review: chất lượng tăng, và cả team cùng giữ chung một chuẩn.

Tạm kết

Documentation Culture, cũng như mọi văn hóa khác trong team, không phải thứ bật lên bằng một cái công tắc. Nó là một thói quen được bồi đắp dần — và như mọi thói quen, nó cần sự đồng thuận của cả team chứ không phải mệnh lệnh từ một người.

Điều mình muốn bạn mang về sau bài này là một góc nhìn: thời đại AI không khai tử việc viết tài liệu, mà làm nó đổi vai. Phần what — mô tả code làm gì — đúng là AI lo được. Nhưng phần why — lý do, bối cảnh, những đánh đổi đằng sau mỗi quyết định — vẫn là tri thức của con người, và giờ còn là thứ “thức ăn” mà AI cần để làm việc tử tế. Cũng đừng quên mặt còn lại: doc lỗi thời trong thế giới có AI đáng ngại hơn trước, vì nó dẫn sai cả người lẫn máy. Viết ít mà đúng, để gần code, và cập nhật cùng code — vẫn hơn viết nhiều rồi bỏ mặc.

Nếu bạn hỏi mình bắt đầu từ đâu, câu trả lời khá đơn giản: lần tới khi viết một đoạn code có quyết định không hiển nhiên, hãy thêm một dòng giải thích tại sao. Chỉ một dòng. Không cần cả trang wiki. Người đọc nó sáu tháng sau — rất có thể là chính bạn — sẽ thầm cảm ơn.

Đây là quan điểm cá nhân dựa trên trải nghiệm thực tế, chắc chắn không phải chân lý tuyệt đối. Mỗi team, mỗi dự án đều có ngữ cảnh riêng, và mình rất muốn nghe câu chuyện của bạn qua phần bình luận.

Cảm ơn bạn đã đọc bài viết. Hẹn gặp lại ở các bài sau trên Fx Studio.

Tài liệu tham khảo

Documentation & docs-as-code

• Software Engineering at Google – Chapter 10: Documentation
• What Is Documentation as Code and Why Do You Need It?
• What is Docs as Code? Guide to Modern Technical Documentation – Kong

Architecture Decision Records (ADR)

• Michael Nygard – Documenting Architecture Decisions
• Lightweight Architecture Decision Records – Thoughtworks Technology Radar
• Maintain an Architecture Decision Record – Microsoft Azure Well-Architected Framework
• The Reason Most ADRs Get Written and Never Read – Java Code Geeks

Documentation trong thời đại AI

• Addy Osmani – My LLM Coding Workflow Going into 2026
• Fern – How to Write LLM-Friendly Documentation
• Mintlify – The Value of llms.txt: Hype or Real
• Mintlify – Best AI Documentation Tools in 2026

Bài liên quan trên Fx Studio

• Reading Culture – Văn hóa đọc trong thời đại AI
• Code Review Culture – Xây dựng văn hóa review code lành mạnh trong team

Written by Võ Trần Anh Khoa