Mở đầu — vì sao bài này quan trọng
Hãy tưởng tượng bạn vừa gia nhập một team backend ở một startup fintech tại TP.HCM. Ngày đầu tiên, bạn được giao đọc tài liệu về hệ thống thanh toán. Bạn mở Confluence lên và... chết đứng. Có một trang dài 4000 chữ, tiêu đề "Payment Service", trong đó trộn lẫn: cách cài đặt môi trường, giải thích triết lý thiết kế, một đoạn tutorial nửa vời, ba lệnh curl không rõ dùng khi nào, và một ghi chú "TODO: cập nhật sau" từ hai năm trước. Bạn đọc xong mà vẫn không biết phải làm gì tiếp theo.
Đây là vấn đề phổ biến nhất trong technical documentation: không phải thiếu tài liệu, mà là tài liệu trộn lẫn nhiều mục đích vào cùng một chỗ. Kết quả là không ai đọc được cho ra hồn — người mới thì lạc lối, người cũ thì bực vì không tìm được thông tin tra cứu nhanh.
Trong khóa học này, các bài trước đã nói về Written Communication nói chung (Bài 5), và các bài sau sẽ đi sâu vào RFC (Bài 10), ADR (Bài 11), Code Review (Bài 12). Bài 9 này tập trung vào một câu hỏi cốt lõi và mang tính nền tảng: làm sao viết một tài liệu kỹ thuật thực sự tốt, có cấu trúc, mà người khác đọc được và dùng được? Chúng ta sẽ học một framework kinh điển đã thay đổi cách hàng nghìn team viết docs: Diátaxis. Đây là kỹ năng nhân bội (multiplier) — vì một tài liệu tốt được đọc bởi hàng chục, hàng trăm người, tiết kiệm hàng trăm giờ trả lời câu hỏi lặp đi lặp lại.
Khái niệm cốt lõi
Diátaxis framework — bốn loại docs, đừng trộn
Daniele Procida, khi làm việc với dự án Django, đã đúc kết ra một nguyên lý đơn giản mà cực kỳ mạnh: có bốn loại tài liệu kỹ thuật khác nhau về bản chất, phục vụ bốn nhu cầu khác nhau của người đọc. Trộn chúng vào nhau là nguyên nhân số một khiến docs trở nên khó dùng.
Bốn loại đó được sắp xếp theo hai trục: người đọc đang học hay đang làm việc? Và họ cần hành động thực tế hay kiến thức lý thuyết?
| Loại | Mục đích | Khi người đọc | Ví dụ |
|---|---|---|---|
| Tutorial | Học qua thực hành | Mới, đang học | "Xây dựng app to-do đầu tiên với Laravel" |
| How-to guide | Giải quyết một vấn đề cụ thể | Đang làm việc, có mục tiêu | "Cách cấu hình gửi email qua SendGrid" |
| Reference | Tra cứu thông tin chính xác | Đang làm việc, cần tra | "API endpoints, danh sách tham số config" |
| Explanation | Hiểu bối cảnh, lý do | Muốn hiểu sâu | "Vì sao chúng ta chọn kiến trúc event-driven" |
Tutorial — cầm tay chỉ việc. Đây là bài học dành cho người hoàn toàn mới. Mục tiêu không phải là dạy họ hiểu hệ thống, mà là cho họ một trải nghiệm thành công đầu tiên. Tutorial phải đảm bảo chạy được từ đầu đến cuối, không được để người học vấp. Bạn nói "gõ lệnh này", họ gõ, và nó phải hoạt động. Tutorial không giải thích dài dòng "tại sao", vì người mới chưa đủ nền tảng để hiểu; giải thích lúc này chỉ gây rối. Ví dụ: "Bắt đầu với hệ thống của chúng ta trong 15 phút."
How-to guide — công thức nấu ăn. Người đọc how-to đã biết cơ bản, họ có một mục tiêu rõ ràng và cần các bước để đạt được. Khác với tutorial, how-to giả định người đọc có năng lực và chỉ cần chỉ dẫn cho tình huống cụ thể của họ. Ví dụ: "Cách rollback một migration bị lỗi trên production." How-to tập trung vào một vấn đề, không lan man.
Reference — từ điển. Reference là thông tin khô khan, chính xác, đầy đủ, có cấu trúc nhất quán. Danh sách tất cả API endpoints, tất cả tham số cấu hình, tất cả mã lỗi. Người đọc không đọc reference từ đầu đến cuối — họ nhảy vào tra một thứ cụ thể rồi thoát ra. Reference phải đúng tuyệt đối và đầy đủ, nhưng không cần giải thích hay dẫn dắt.
Explanation — bài luận. Explanation trả lời câu hỏi "tại sao" và "trong bối cảnh nào". Nó giúp người đọc hiểu sâu, thấy được bức tranh lớn, các trade-off, lịch sử quyết định. Ví dụ: "Vì sao chúng ta dùng event sourcing cho module thanh toán và những đánh đổi đi kèm." Explanation có thể đọc lúc rảnh, không gắn với một tác vụ cấp bách nào.
Vì sao tách bạch lại quan trọng đến vậy
Điểm mấu chốt: mỗi loại tài liệu phục vụ một trạng thái tâm lý khác nhau của người đọc. Khi tôi đang cần rollback migration lúc 2 giờ sáng vì production down (trạng thái how-to), điều cuối cùng tôi muốn đọc là ba đoạn giải thích triết lý về migration (explanation). Ngược lại, khi tôi đang thong thả tìm hiểu kiến trúc hệ thống, một danh sách 200 tham số config (reference) chẳng giúp tôi hiểu gì.
Khi bạn trộn bốn loại này, bạn buộc mọi người đọc phải lọc bỏ 75% nội dung không liên quan đến nhu cầu hiện tại của họ. Đó chính là lý do trang Confluence 4000 chữ ở đầu bài trở nên vô dụng.
Tình huống thực tế
Ví dụ 1 — Startup logistics ở Hà Nội "dọn dẹp" mớ docs hỗn độn
Một công ty logistics công nghệ tại Hà Nội (khoảng 40 kỹ sư) có một trang wiki nội bộ "Onboarding Guide" dài tới 6000 chữ cho service điều phối đơn hàng. Team than phiền rằng người mới mất trung bình 8 ngày mới bắt đầu commit được code đầu tiên, và mỗi tuần các senior mất khoảng 5-6 giờ trả lời những câu hỏi đã "có trong docs" nhưng không ai tìm ra.
Một kỹ sư đề xuất áp dụng Diátaxis. Họ tách trang khổng lồ đó thành bốn khu vực rõ ràng:
- Tutorial: "Setup máy và chạy một đơn hàng thử trong 30 phút" — một luồng duy nhất, đảm bảo chạy được.
- How-to: các bài ngắn như "Cách thêm một loại vận đơn mới", "Cách debug webhook từ đối tác giao hàng".
- Reference: bảng liệt kê tất cả trạng thái đơn hàng, mã lỗi API, biến môi trường.
- Explanation: "Vì sao hệ thống dùng state machine cho vòng đời đơn hàng."
Bài học: Sau một tháng, thời gian onboarding giảm còn khoảng 3 ngày, và câu hỏi lặp lại giảm rõ rệt vì người mới tự tìm được reference. Docs tốt không nhất thiết là docs dài hơn — thường là docs có cấu trúc hơn.
Ví dụ 2 — Tutorial "chết" vì không ai kiểm thử lại
Ở một công ty SaaS tại Singapore, đội developer relations viết một tutorial "Getting Started" rất công phu cho SDK của họ. Ban đầu nó tuyệt vời. Nhưng sáu tháng sau, một khách hàng lớn ở Việt Nam phản hồi rằng làm theo tutorial thì lỗi ngay bước 3: lệnh cài đặt trỏ tới một package version đã bị deprecate, và biến môi trường đã đổi tên.
Điều tệ hơn: có tới 40% người dùng thử SDK bỏ cuộc ngay bước cài đặt, nhưng team không hề biết vì không ai báo — họ chỉ lặng lẽ rời đi.
Diễn giải: Tutorial là loại tài liệu dễ hỏng nhất vì nó phụ thuộc vào việc mọi lệnh phải chạy đúng. Reference sai một tham số thì người đọc còn đoán được; tutorial sai một bước thì người mới hoàn toàn tắc.
Bài học: Team lập ra một CI job chạy toàn bộ tutorial mỗi tuần trong môi trường sạch. Nếu tutorial fail, build đỏ. Đây gọi là "docs as code" — coi tài liệu (nhất là tutorial) như một artifact cần được kiểm thử tự động, không phải văn bản viết một lần rồi bỏ đấy.
Ví dụ 3 — Nhầm explanation thành how-to
Một team platform ở một ngân hàng số Việt Nam viết tài liệu "Cách triển khai service lên Kubernetes cluster." Nhưng khi đọc kỹ, nửa đầu tài liệu lại là ba trang giải thích về triết lý container, sự khác biệt giữa Docker và containerd, lịch sử vì sao họ chọn Kubernetes thay vì Nomad. Một kỹ sư mới cần deploy gấp phải cuộn qua toàn bộ phần đó mới tới các lệnh thực tế.
Diễn giải: Nội dung giải thích tự nó có giá trị — nhưng nó là explanation, không phải how-to. Trộn vào nhau khiến người cần hành động bị chậm lại, còn người muốn hiểu sâu thì lại thấy phần giải thích bị cắt xén cho vừa khuôn khổ một how-to.
Bài học: Họ tách ra: một how-to gọn "Deploy service trong 5 bước" (chỉ có lệnh và điều kiện tiên quyết), và một explanation riêng "Kiến trúc triển khai của chúng tôi: các lựa chọn và trade-off." Người deploy gấp vào how-to; người mới muốn hiểu vào explanation. Cả hai đều hài lòng.
Hướng dẫn từng bước
Đây là quy trình thực tế để viết một tài liệu kỹ thuật tốt theo Diátaxis:
Bước 1 — Xác định người đọc đang ở trạng thái nào. Trước khi viết một chữ, hỏi: người đọc tài liệu này đang học hay đang làm? Họ cần hành động hay cần hiểu? Trả lời hai câu này sẽ xác định bạn đang viết loại nào trong bốn loại. Nếu bạn không trả lời được, đó là dấu hiệu bạn đang định trộn nhiều loại.
Bước 2 — Đặt một tiêu đề trung thực với loại tài liệu. Tiêu đề nên báo hiệu loại: "Hướng dẫn từng bước: ..." (tutorial), "Cách ..." (how-to), "Tham chiếu: ..." (reference), "Vì sao / Tổng quan về ..." (explanation). Tiêu đề trung thực giúp người đọc biết ngay có nên vào không.
Bước 3 — Viết đúng "văn phong" của loại đó.
- Tutorial: dùng "chúng ta", cầm tay chỉ việc, không giải thích thừa, đảm bảo mỗi bước tạo ra kết quả nhìn thấy được.
- How-to: đi thẳng vào giải pháp, giả định người đọc có năng lực, tập trung một vấn đề.
- Reference: khô khan, nhất quán, đầy đủ; dùng bảng và danh sách; không kể chuyện.
- Explanation: viết như bài luận, thảo luận trade-off, nêu bối cảnh và lịch sử.
Bước 5 — Kiểm thử bằng chính người đọc mục tiêu. Nhờ một người chưa từng làm việc này làm theo tài liệu, và bạn ngồi im quan sát, không nhắc. Mỗi lần họ khựng lại là một chỗ tài liệu cần sửa. Đây là bài kiểm tra tàn nhẫn nhưng chính xác nhất.
Bước 6 — Đặt cơ chế bảo trì. Ai chịu trách nhiệm cập nhật? Với tutorial quan trọng, hãy tự động hóa việc kiểm thử. Với reference, cân nhắc sinh tự động từ code (ví dụ OpenAPI spec sinh ra tài liệu API) để không bao giờ lệch với thực tế.
Lỗi thường gặp & mẹo
Lỗi 1 — Trộn bốn loại vào một trang. Đây là lỗi kinh điển đã nói ở đầu bài. Mẹo: khi viết mỗi đoạn, tự hỏi "đoạn này thuộc loại nào?". Nếu một trang chứa nhiều loại, hãy tách ra và liên kết chéo bằng link.
Lỗi 2 — Tutorial giải thích quá nhiều. Người mới bị "nghẹn" vì bạn dừng lại giải thích tại sao ở mỗi bước. Mẹo: trong tutorial, thay vì giải thích, hãy để một dòng "Muốn hiểu vì sao? Đọc [explanation này]." — đẩy phần "tại sao" sang đúng chỗ của nó.
Lỗi 3 — Reference kể chuyện. Reference nên tra cứu nhanh, nhưng nhiều người viết chèn văn xuôi dài dòng. Mẹo: ưu tiên bảng, danh sách, cấu trúc lặp lại nhất quán. Người đọc quét mắt (scan), không đọc từng chữ.
Lỗi 4 — Docs viết một lần rồi bỏ. Tài liệu lỗi thời còn tệ hơn không có tài liệu, vì nó khiến người đọc mất niềm tin và làm sai. Mẹo: đặt docs cạnh code trong cùng repo (docs as code), review docs trong pull request như review code, và ghi ngày cập nhật cuối.
Lỗi 5 — Viết cho chính mình thay vì người đọc. Bạn biết hệ thống nên bạn bỏ qua những bước "hiển nhiên" — nhưng chúng không hiển nhiên với người mới. Mẹo: luôn hình dung một người cụ thể (một junior mới vào tuần trước) và viết cho họ.
Mẹo vàng — bắt đầu từ câu hỏi có thật. Cách tốt nhất để biết cần viết docs gì: theo dõi những câu hỏi lặp lại trên Slack/Discord của team. Mỗi câu hỏi lặp lại nhiều lần là một tài liệu đang thiếu. Điều này biến việc viết docs từ "công việc mơ hồ" thành "giải quyết vấn đề có thật".
Bài tập thực hành
- Phân loại (10 phút): Chọn 5 tài liệu kỹ thuật bất kỳ trong công ty hoặc dự án của bạn (hoặc từ một open-source project bạn dùng). Gán mỗi tài liệu vào một trong bốn loại Diátaxis. Có tài liệu nào trộn từ hai loại trở lên không? Ghi lại.
- Tách bạch (30 phút): Chọn một tài liệu "trộn" mà bạn tìm được ở bài 1. Vẽ ra (chỉ cần gạch đầu dòng) cách bạn sẽ tách nó thành các tài liệu riêng theo bốn loại. Loại nào nên tách ra, loại nào giữ, link chéo ra sao?
- Viết một how-to (45 phút): Chọn một tác vụ bạn thường làm và hay được hỏi (ví dụ: "cách chạy test suite cục bộ", "cách reset môi trường dev"). Viết một how-to guide hoàn chỉnh: tiêu đề bắt đầu bằng "Cách...", nêu điều kiện tiên quyết, các bước rõ ràng, đi thẳng vào giải pháp. Giữ dưới 400 chữ.
- Kiểm thử tàn nhẫn (30 phút): Nhờ một đồng nghiệp chưa từng làm tác vụ đó làm theo how-to bạn vừa viết, trong khi bạn ngồi im quan sát và ghi lại mọi chỗ họ khựng lại. Sửa tài liệu dựa trên quan sát đó.
Tóm tắt
Technical documentation tốt không phải là viết nhiều hơn, mà là viết đúng loại vào đúng chỗ. Framework Diátaxis của Daniele Procida cho chúng ta bốn loại tài liệu, mỗi loại phục vụ một trạng thái khác nhau của người đọc:
- Tutorial — học qua thực hành, cầm tay chỉ việc, phải chạy được từ đầu đến cuối.
- How-to guide — giải quyết một vấn đề cụ thể, đi thẳng vào giải pháp.
- Reference — tra cứu chính xác, khô khan, đầy đủ, có cấu trúc.
- Explanation — hiểu bối cảnh và lý do, thảo luận trade-off.
Quy tắc thực hành: trước khi viết, xác định người đọc đang học hay làm, cần hành động hay hiểu. Đặt tiêu đề trung thực. Viết đúng văn phong của loại. Kiểm thử bằng chính người đọc mục tiêu. Và quan trọng nhất — coi docs như code: đặt cạnh nhau, review cùng nhau, cập nhật liên tục. Một tài liệu tốt là kỹ năng nhân bội: bạn viết một lần, hàng trăm người hưởng lợi.