Viết tài liệu bàn giao để khách tự vận hành mà không cần gọi lại FDE

Thử hình dung thứ Sáu là ngày cuối của bạn ở dự án. Pipeline đồng bộ đơn hàng từ ERP của khách sang kho dữ liệu đã chạy ổn hai tuần, demo xong, khách hài lòng. Ba tuần sau, khách nhắn cho bạn: job đêm qua fail, nhờ anh xem giúp.

Tin nhắn đó cho thấy việc bàn giao đã thất bại, dù code không có lỗi gì. Sổ tay FDE của PostHog đặt tiêu chuẩn “xong” cho một sản phẩm bàn giao rất rõ: một người lạ trong đội của khách cầm lên đọc mà không ai giải thích vẫn hiểu phạm vi, làm theo khuyến nghị và không phải ping lại đội FDE.

PostHog gọi giai đoạn tài liệu và đào tạo là lúc chuyển quyền sở hữu, để khách tự làm chủ hệ thống sau khi đội rời đi.

Với một FDE, đây là kỹ năng phân biệt người “làm xong dự án” với người “để lại một hệ thống sống được”. Nó cũng là thứ bạn nên kể lại thật cụ thể khi phỏng vấn, bằng kết quả chứ không bằng tính từ.

Vì sao tài liệu bàn giao thường vô dụng?

Tandem, một công ty viết về quy trình FDE, chỉ ra nguyên nhân rất đời thường: người sắp rời viết tài liệu vào đúng những tuần bận nhất, chồng lên việc hoàn thiện bản build. Kết quả dễ đoán là tài liệu chứa những gì người viết dễ nhớ, chứ không phải những gì người kế nhiệm cần.

Tandem còn nhận xét rằng tài liệu kiểu này là một ảnh chụp không kiểm chứng được. Một câu như “khách đã đồng ý bỏ qua đơn hàng bị hủy” mà không có link tới email hay biên bản họp thì người đọc chỉ còn cách hỏi lại khách. Tandem gói gọn: ghi chú không có nguồn chỉ là lời khẳng định.

Vấn đề thứ ba đến từ thời gian. Sách SRE của Google cảnh báo rằng trong môi trường thay đổi nhanh, tài liệu vận hành lỗi thời rất nhanh. Người mới lại là người cần tài liệu cập nhật nhất, nhưng thường không thấy mình đủ quyền hay đủ hiểu để sửa nó.

Một bộ bàn giao, năm loại văn bản

Cách khắc phục là thôi coi bàn giao là “một file README dài”, mà chia theo mục đích người đọc.

Mô hình Diátaxis của Daniele Procida (Canonical) gợi ý một cách chia dễ dùng. How-to guide là công thức từng bước để làm xong một việc cụ thể. Reference là nơi tra cứu dữ kiện về hệ thống. Explanation là phần giải thích vì sao hệ thống được thiết kế như vậy.

Với một bộ bàn giao, nên đặt thêm hai lớp nữa quanh ba loại này. Trên cùng là trang bìa ngắn, theo gợi ý của Tandem chỉ trả lời bốn câu hỏi: đã hứa gì, đã quyết gì, đang có rủi ro gì, tiếp theo là gì.

Dưới cùng là phần chẩn đoán, vì sách SRE của Google cảnh báo việc đào tạo chỉ bằng quy trình, checklist và playbook: người vận hành cần biết suy luận khi gặp lỗi chưa có trong sách.

Loại	Người đọc cần gì	Ví dụ trong pipeline đơn hàng
Trang bìa	Bức tranh toàn cảnh trong năm phút	Phạm vi, quyết định, rủi ro, việc tiếp theo có tên người
How-to	Làm một việc cụ thể ngay bây giờ	Chạy lại job cho một ngày bị lỡ
Reference	Tra cứu một dữ kiện	Lịch chạy, bảng đích, nơi lưu credential
Explanation	Hiểu vì sao hệ thống như vậy	Vì sao đồng bộ incremental thay vì full
Chẩn đoán	Tự tìm nguyên nhân khi có sự cố lạ	Số dòng lệch giữa ERP và kho dữ liệu

Ví dụ: trang bìa cho pipeline đơn hàng

Quay lại pipeline giả định ở trên. Trang bìa có thể trông như sau, mỗi dòng có link tới nguồn gốc:

# Bàn giao: Pipeline đồng bộ đơn hàng ERP → kho dữ liệu

## Đã hứa
- Đồng bộ đơn hàng mới và đơn sửa đổi mỗi đêm. [link: biên bản kickoff]
- KHÔNG bao gồm dữ liệu kho hàng (để giai đoạn sau). [link: email xác nhận]

## Đã quyết
- Đồng bộ incremental theo cột updated_at. Lý do: xem explanation/incremental.md
- Đơn bị hủy vẫn giữ, gắn cờ is_cancelled. [link: ghi chú họp với đội kế toán]

## Rủi ro
- ERP có thể đổi schema khi nâng cấp; job sẽ fail ở bước validate.

## Tiếp theo (theo thứ tự)
1. Chị Lan (Data) chuyển cảnh báo job fail sang kênh trực của đội mình.
2. Anh Minh (IT) xoay vòng credential ERP trước khi hết hạn.
3. Chị Lan chạy thử how-to/backfill.md trên môi trường staging.

Phần “Tiếp theo” là nơi tài liệu dở thường viết “cần theo dõi thêm”. PostHog yêu cầu các bước tiếp theo phải cụ thể, có thứ tự và giao cho người có tên. Việc không có chủ thì sẽ không ai làm.

Phần “Đã quyết” trỏ sang explanation thay vì chép lại. PostHog dặn khi bàn giao phải ghi lại đã xây gì và vì sao. Lý do quan trọng vì một năm sau, ai đó bên khách sẽ muốn “đơn giản hóa” bằng cách chuyển sang full sync, và chỉ phần explanation mới cho họ biết vì sao lựa chọn đó đã bị loại.

Trang bìa cũng không chép lại lịch chạy hay cấu hình. Tandem cảnh báo rằng nếu tài liệu vượt quá vài trang, nó đang chép lại những thứ lẽ ra một hệ thống phải lưu. Lịch chạy nằm trong file cấu hình của scheduler, và reference chỉ cần trỏ tới đó.

Phần chẩn đoán: dạy cách nghĩ, không chỉ cách bấm

How-to “chạy lại job” giúp khách xử lý được lỗi bạn đã lường trước. Phần chẩn đoán dành cho lỗi bạn chưa lường.

Với pipeline này, một trang chẩn đoán tốt bắt đầu từ triệu chứng (“số đơn trong kho ít hơn ERP”), rồi liệt kê các giả thuyết theo thứ tự dễ kiểm tra nhất: job có chạy không, có đơn nào có updated_at nằm ngoài cửa sổ không, múi giờ có lệch không.

Mỗi giả thuyết đi kèm cách kiểm chứng, ví dụ câu query đếm theo ngày ở hai phía. Người đọc học được cách loại trừ, và lần sau tự áp dụng cho triệu chứng khác.

Tự làm: năm bước

Bước 1: ghi từ tuần đầu, không đợi tuần cuối. Đây là cách tránh cái bẫy Tandem mô tả. Mỗi khi có quyết định, ghi một dòng vào “Đã quyết” kèm link nguồn ngay lúc đó.

Bước 2: viết how-to và reference. Khi sắp bàn giao, viết how-to cho ba đến năm việc khách sẽ phải làm thường xuyên nhất, rồi viết reference trỏ tới nơi cấu hình thật sự nằm.

Bước 3: viết explanation và trang chẩn đoán. Explanation dành cho những quyết định mà người đến sau dễ muốn đảo ngược; trang chẩn đoán dành cho triệu chứng hay gặp nhất.

Bước 4: chạy phép thử của PostHog. Đưa tài liệu cho một người bên khách chưa tham gia dự án, nhờ họ làm một how-to trong khi bạn không nói gì. Mỗi câu họ hỏi là một lỗ hổng cần vá.

Bước 5: chỉ định người giữ tài liệu. Ghi rõ ai bên khách chịu trách nhiệm cập nhật, và đặt tài liệu ở nơi họ sửa được dễ dàng, để người vận hành mới không ngại chỉnh như cảnh báo trong sách SRE.

Những lỗi hay gặp

Lỗi phổ biến nhất là viết cho chính mình: dùng tên viết tắt nội bộ, bỏ qua các bước “hiển nhiên” mà chỉ người xây mới thấy hiển nhiên. Lỗi thứ hai là trộn lẫn mọi thứ trong một file, khiến người đang cần sửa sự cố lúc nửa đêm phải lội qua ba trang lịch sử thiết kế.

Lỗi thứ ba là lưu tài liệu trong wiki của công ty bạn, nơi khách không có quyền sửa. Sách SRE của Google đã cảnh báo tài liệu vận hành cũ đi rất nhanh; nếu người bên khách không sửa được, nó sẽ cứ thế lệch dần khỏi hệ thống thật mà không ai vá.

Kỹ năng này hiện lên ở đâu trong hồ sơ?

Khi đọc JD một vị trí FDE, hãy để ý xem vai trò có nhắc tới việc chuyển giao hệ thống cho đội khách hay không. Trong CV, thay vì ghi “viết tài liệu”, hãy mô tả kết quả: đội nào bên khách đã tự vận hành hệ thống sau khi bạn rời đi, và họ làm được gì mà không cần gọi bạn.

Bài tập tuần này đi theo chiều ngược lại: tìm một tài liệu bàn giao hoặc README mà chính bạn từng nhận, liệt kê mọi câu bạn đã phải đi hỏi người khác, rồi xếp từng câu vào một trong năm lớp ở trên. Lớp nào dồn nhiều câu hỏi nhất là lớp mà chính bạn đang có nguy cơ bỏ quên khi đến lượt mình bàn giao.