Mở đầu — vì sao bài này quan trọng
Hãy hình dung một buổi sáng thứ Hai điển hình ở một công ty công nghệ đang tăng trưởng nhanh tại TP.HCM. Một kỹ sư mới vào làm ngày thứ ba, cần deploy một service nhỏ lên staging. Anh ta mở Confluence của công ty ra và... lạc lối. Có một trang tên "Deployment Guide" nhưng lại giải thích triết lý CI/CD dài ba màn hình. Có một trang khác tên "How we think about infrastructure" nhưng bên trong lại là các lệnh kubectl rời rạc. Có một trang "API Reference" nhưng thực chất là câu chuyện về lần sự cố năm ngoái. Kết quả: anh ta bỏ cuộc, gõ Slack hỏi team lead, và cắt ngang công việc của một người đang bận.
Vấn đề ở đây không phải là công ty thiếu tài liệu. Ngược lại, họ viết rất nhiều. Vấn đề là tài liệu bị trộn lẫn mục đích. Một trang cố gắng vừa dạy, vừa hướng dẫn, vừa tra cứu, vừa giải thích — và cuối cùng không làm tốt việc nào cả.
Khi team còn 5 người, ai cũng biết mọi thứ, tài liệu gần như thừa. Nhưng khi bạn scale lên 30, 50, 100 kỹ sư — và đây chính là bối cảnh của cả khóa học này — thì tài liệu trở thành cơ sở hạ tầng cho việc truyền tải tri thức. Documentation kém không chỉ làm chậm onboarding; nó tạo ra tình trạng phụ thuộc vào vài "người biết tuốt", biến họ thành bottleneck, và làm tăng chi phí vận hành theo cấp số nhân khi tổ chức lớn lên.
Bài học này giới thiệu Diátaxis — một framework do Daniele Procida phát triển, phân loại mọi tài liệu kỹ thuật thành đúng bốn loại. Đây là công cụ đơn giản đến bất ngờ nhưng có sức mạnh cực lớn để xây dựng một văn hóa tài liệu (documentation culture) có kỷ luật và bền vững khi scale.
Khái niệm cốt lõi
Tại sao "viết tài liệu tốt" lại khó
Trước khi vào framework, cần hiểu gốc rễ vấn đề. Đa số tài liệu tệ không phải vì người viết dở, mà vì họ không xác định rõ họ đang phục vụ nhu cầu nào của người đọc. Người đọc tài liệu ở những thời điểm khác nhau có nhu cầu khác nhau hoàn toàn:
- Đôi khi họ đang học (chưa biết gì, cần được dẫn dắt).
- Đôi khi họ đang làm việc (đã biết mục tiêu, cần hoàn thành một nhiệm vụ cụ thể).
- Đôi khi họ cần thông tin chính xác (tra cứu một tham số, một endpoint).
- Đôi khi họ muốn hiểu sâu (nắm bức tranh lớn, lý do đằng sau thiết kế).
Hai trục của Diátaxis
Trục thứ nhất: người đọc đang học tập (study) hay đang làm việc (work)? Nghĩa là họ đang tiếp thu để phát triển kỹ năng, hay đang áp dụng để hoàn thành công việc trước mắt?
Trục thứ hai: nội dung thiên về thực hành (practical steps) hay về lý thuyết/tri thức (theoretical knowledge)? Nghĩa là tài liệu chỉ cho họ hành động, hay cung cấp sự hiểu biết?
Ghép hai trục lại, ta có một ma trận 2x2 với bốn góc phần tư, mỗi góc là một loại tài liệu riêng biệt:
| Học tập (study) | Làm việc (work) | |
|---|---|---|
| Thực hành | Tutorial (Hướng dẫn học) | How-to Guide (Hướng dẫn thao tác) |
| Lý thuyết | Explanation (Giải thích) | Reference (Tra cứu) |
Bốn loại tài liệu
1. Tutorial — Hướng dẫn học (thực hành + học tập). Đây là bài học có cầm tay chỉ việc dành cho người mới hoàn toàn. Mục tiêu không phải hoàn thành công việc thật, mà là giúp người học có trải nghiệm thành công đầu tiên và xây dựng sự tự tin. Tutorial giống như một thầy giáo dẫn học viên đi qua từng bước, đảm bảo họ đến đích. Ví dụ: "Xây dựng service đầu tiên của bạn trên nền tảng nội bộ trong 30 phút". Người viết tutorial phải chịu trách nhiệm cho từng bước — không được để người học tự suy luận.
2. How-to Guide — Hướng dẫn thao tác (thực hành + làm việc). Đây là công thức để giải quyết một vấn đề cụ thể trong thực tế, dành cho người đã có năng lực. Nó giả định người đọc biết mình muốn gì. Ví dụ: "Cách rollback một deployment trên production", "Cách cấu hình biến môi trường cho service". How-to tập trung vào kết quả, bỏ qua giải thích dài dòng. Đây là loại tài liệu bị nhầm với tutorial nhiều nhất.
3. Reference — Tài liệu tra cứu (lý thuyết + làm việc). Đây là mô tả kỹ thuật khô khan, chính xác, đầy đủ: danh sách API endpoint, tham số cấu hình, mã lỗi, cấu trúc database. Reference giống như từ điển — bạn không đọc từ đầu đến cuối, bạn tra cứu khi cần. Đặc tính quan trọng nhất là độ chính xác và tính nhất quán. Reference không dạy, không kể chuyện, không thuyết phục.
4. Explanation — Giải thích (lý thuyết + học tập). Đây là phần thảo luận, cung cấp bối cảnh và lý do: tại sao hệ thống được thiết kế thế này, những đánh đổi (trade-off) nào đã cân nhắc, background lịch sử. Explanation giúp người đọc hiểu sâu, kết nối các mảnh kiến thức. Ví dụ: "Vì sao chúng ta chọn kiến trúc event-driven cho hệ thống thanh toán". Explanation là loại có thể đọc lúc rảnh, tách khỏi công việc trước mắt.
Nguyên tắc vàng: không trộn lẫn
Điểm mấu chốt của Diátaxis không nằm ở việc biết bốn loại, mà ở kỷ luật giữ chúng tách biệt. Mỗi tài liệu chỉ nên phục vụ một góc phần tư. Khi bạn cố nhét giải thích vào giữa một how-to, bạn làm người đang vội bực mình. Khi bạn nhét các bước thao tác vào một explanation, bạn phá vỡ mạch tư duy. Diátaxis không phải là bảng phân loại để dán nhãn — nó là la bàn định hướng giúp bạn biết mỗi lúc đang viết loại gì và phải đứng ngoài các loại còn lại.
Tình huống thực tế
Ví dụ 1: Startup fintech ở Singapore và cơn ác mộng onboarding
Một startup fintech tại Singapore (gọi là PayFlow) tăng từ 12 lên 45 kỹ sư trong 10 tháng. Họ tự hào là "văn hóa viết tài liệu tốt" — wiki có hơn 400 trang. Nhưng thời gian để một kỹ sư backend mới commit dòng code có ý nghĩa đầu tiên trung bình là 11 ngày.
Khi VP Engineering ngồi xuống điều tra, cô phát hiện vấn đề kinh điển: trang "Getting Started with Payment Service" dài 4.000 từ, trộn lẫn cả bốn loại. Nó mở đầu bằng triết lý micro-services (explanation), giữa chừng liệt kê toàn bộ config schema (reference), rồi chuyển sang các lệnh setup (tutorial), rồi lại nhảy sang cách xử lý một edge case ở production (how-to). Người mới đọc 20 phút mà không setup được gì.
Nhóm đã tách trang này thành bốn phần theo Diátaxis: một tutorial 30 phút "Chạy Payment Service trên máy bạn"; một tập how-to ngắn cho các tác vụ thường gặp; một trang reference cho config; và một explanation riêng về kiến trúc. Sau ba tháng, thời gian đến commit đầu tiên giảm còn 4 ngày. Bài học: vấn đề không phải thiếu chữ, mà là chữ sai chỗ.
Ví dụ 2: Django — nơi Diátaxis ra đời
Daniele Procida chính là người từng làm việc với documentation của Django, một trong những framework có tài liệu được ngợi khen nhất thế giới mã nguồn mở. Nếu bạn vào trang docs của Django, bạn sẽ thấy bốn nhánh điều hướng rõ ràng: Tutorials, How-to guides, Reference, và Topics (explanation). Cấu trúc này không ngẫu nhiên — nó chính là hiện thân của Diátaxis.
Điều đáng học ở đây: sự tách biệt loại tài liệu được thể hiện ngay ở cấu trúc điều hướng (navigation), chứ không chỉ ở nội dung. Người đọc biết mình đang cần gì thì đi thẳng vào nhánh đó. Người mới học vào Tutorial. Người đang debug vào How-to. Người tra cú pháp vào Reference. Bài học: Diátaxis không chỉ định hình cách viết mà còn định hình kiến trúc thông tin của cả bộ tài liệu.
Ví dụ 3: Team platform ở một công ty e-commerce Việt Nam
Một team platform (nền tảng nội bộ) tại một sàn e-commerce lớn ở Hà Nội gặp tình huống: mỗi tuần họ nhận trung bình 25 câu hỏi lặp lại trên Slack từ các stream-aligned team, kiểu "làm sao tạo database mới", "endpoint auth là gì". Team platform chỉ có 6 người, và việc trả lời câu hỏi ngốn khoảng 8 giờ/tuần — gần một ngày công.
Họ áp dụng Diátaxis với một quy tắc đơn giản: mỗi câu hỏi Slack lặp lại lần thứ ba phải trở thành một how-to guide. Câu hỏi "làm sao" biến thành how-to; câu hỏi "cái gì / tham số nào" biến thành reference; câu hỏi "tại sao" biến thành explanation. Sau hai tháng, số câu hỏi lặp trên Slack giảm 60%, và quan trọng hơn, câu trả lời giờ nhất quán thay vì mỗi người trả lời một kiểu. Bài học: Diátaxis biến việc viết docs từ một dự án lớn đáng sợ thành thói quen nhỏ hằng ngày, gắn trực tiếp với nỗi đau thực tế.
Hướng dẫn từng bước
Đây là quy trình áp dụng Diátaxis cho team đang scale:
Bước 1 — Audit tài liệu hiện có bằng lăng kính bốn loại. Lấy 10–15 trang tài liệu được truy cập nhiều nhất. Với mỗi trang, hỏi: "Trang này phục vụ góc phần tư nào?" Bạn sẽ nhanh chóng phát hiện những trang "lai" — trộn nhiều loại. Đánh dấu chúng để tách.
Bước 2 — Thiết lập cấu trúc điều hướng bốn nhánh. Trong Notion/Confluence/wiki, tạo bốn khu vực rõ ràng: Tutorials, How-to Guides, Reference, Explanation (có thể Việt hóa: Học từ đầu / Hướng dẫn thao tác / Tra cứu / Giải thích). Cấu trúc này báo hiệu trực quan cho người viết lẫn người đọc.
Bước 3 — Khi viết, xác định loại TRƯỚC khi viết chữ đầu tiên. Tự hỏi: người đọc trang này đang học hay đang làm? Đang cần bước làm hay hiểu biết? Câu trả lời quyết định giọng văn và cấu trúc.
Bước 4 — Áp dụng luật liên kết thay vì trộn. Nếu một how-to cần giải thích, đừng nhét giải thích vào — hãy link sang trang explanation tương ứng. Đây là cách giữ mỗi tài liệu "thuần khiết" mà vẫn kết nối được.
Bước 5 — Gắn documentation vào Definition of Done. Với mỗi feature hoặc service mới, coi việc cập nhật reference và (nếu cần) thêm how-to là một phần của "hoàn thành", không phải việc làm thêm.
Bước 6 — Định kỳ rà soát. Reference dễ lỗi thời nhất. Lên lịch review reference mỗi quý; tutorial nên được một người mới thử làm lại để phát hiện chỗ đứt gãy.
Lỗi thường gặp & mẹo
Lỗi 1 — Trộn tutorial và how-to. Đây là lỗi phổ biến nhất. Nhớ: tutorial dành cho người chưa biết gì và mục tiêu là học; how-to dành cho người đã biết và mục tiêu là hoàn thành việc. Một tutorial không nên có 15 nhánh "nếu bạn muốn X thì làm Y"; một how-to không nên giải thích khái niệm cơ bản.
Lỗi 2 — Explanation trá hình thành reference. Nhiều team viết một trang "Kiến trúc hệ thống" nhưng nhét đầy chi tiết config vào. Explanation nên trả lời "tại sao", reference trả lời "cái gì / như thế nào một cách chính xác".
Lỗi 3 — Bỏ quên explanation hoàn toàn. Nhiều team kỹ thuật giỏi viết how-to và reference nhưng lười viết explanation, khiến team mất "trí nhớ tổ chức" về lý do các quyết định. Khi người cũ rời đi, không ai nhớ vì sao hệ thống được thiết kế thế này.
Lỗi 4 — Coi Diátaxis là để phân loại chứ không phải để định hướng viết. Giá trị lớn nhất của framework đến trong lúc viết, không phải lúc dán nhãn xong xuôi.
Mẹo: Đặt câu hỏi định vị ngay đầu mỗi trang trong lúc soạn: "Ai đọc? Họ đang học hay đang làm?". Mẹo nữa: dùng tên trang phản ánh loại tài liệu — "Hướng dẫn: Deploy service" (how-to), "Tham chiếu: Config API" (reference) — để người đọc biết ngay kỳ vọng.
Bài tập thực hành
- Audit thực tế: Chọn 5 trang tài liệu ở công ty/dự án bạn. Với mỗi trang, xác định nó thuộc góc phần tư nào, hoặc chỉ ra nó đang trộn những loại nào. Ghi lại ít nhất một trang "lai" và phác thảo cách tách.
- Viết bốn phiên bản: Chọn một chủ đề bạn quen (ví dụ: "gửi email qua service nội bộ"). Viết ngắn gọn cả bốn loại tài liệu về nó: một tutorial mở đầu, một how-to, một mục reference, và một đoạn explanation. Cảm nhận sự khác biệt về giọng văn và cấu trúc.
- Thiết kế điều hướng: Phác thảo cây thư mục tài liệu bốn nhánh cho một sản phẩm hoặc service bạn đang làm, liệt kê 3–4 trang mẫu dưới mỗi nhánh.
- Quy tắc "lần thứ ba": Ghi lại ba câu hỏi lặp mà team bạn hay nhận, phân loại mỗi câu thuộc loại tài liệu nào, và viết bản nháp cho một trong số đó.
Tóm tắt
Diátaxis, do Daniele Procida phát triển, phân loại mọi tài liệu kỹ thuật thành bốn loại theo hai trục — học tập vs làm việc, và thực hành vs lý thuyết:
- Tutorial (thực hành + học): dẫn dắt người mới đến thành công đầu tiên.
- How-to Guide (thực hành + làm): công thức giải quyết vấn đề cụ thể cho người đã biết.
- Reference (lý thuyết + làm): mô tả chính xác, đầy đủ để tra cứu.
- Explanation (lý thuyết + học): bối cảnh, lý do, đánh đổi để hiểu sâu.