Git & Pull Request cho tài liệu — để docs đi cùng nhịp với code

Bài này đưa tài liệu vào nhịp làm việc thật: branch, pull request, review, CODEOWNERS và quy tắc docs + code đi cùng nhau.

Mục tiêu học tập

Sau bài học này, bạn sẽ:

1. Nắm được những khái niệm Git tối thiểu mà người viết tài liệu cần — không phải toàn bộ Git của lập trình viên.
2. Đi qua được luồng chuẩn branch → edit → pull request (PR) thay vì sửa trực tiếp lên main (nhánh chính).
3. Viết được commit message (thông điệp commit) tốt cho tài liệu, phân biệt ví dụ tốt và ví dụ xấu.
4. Review (rà soát) một thay đổi tài liệu giống như review code, dựa trên một checklist (danh sách kiểm) cụ thể.
5. Hiểu vai trò của CODEOWNERS, branch protection (bảo vệ nhánh), và mô hình quản trị BDFL-hybrid của repo này.
6. Áp dụng nguyên tắc chống doc drift (lệch tài liệu): tài liệu và code đi chung trong cùng một PR.

1. Git căn bản cho người viết (không phải lập trình viên)

Nếu bạn chưa từng dùng Git, đừng lo. Để cộng tác tài liệu, bạn chỉ cần nắm bốn khái niệm. Phần còn lại của Git là dành cho việc khác và bạn có thể học sau.

Repo (repository — kho chứa). Một thư mục dự án mà Git đang theo dõi. Nó chứa toàn bộ file và toàn bộ lịch sử thay đổi của chúng. Repo docs-as-code-kit mà bạn đang học chính là một repo. Khi bạn git clone (sao về máy), bạn nhận được cả lịch sử, không chỉ bản mới nhất.

Commit (bản ghi thay đổi). Một "ảnh chụp" các thay đổi tại một thời điểm, kèm một thông điệp giải thích vì sao bạn thay đổi. Hãy nghĩ commit như một mục trong nhật ký: "Hôm nay tôi đã sửa đoạn này, vì lý do kia." Mỗi commit có một mã định danh và gắn tên tác giả — nên về sau bất kỳ ai cũng biết ai đã đổi gì, khi nào, và tại sao.

Branch (nhánh). Một dòng làm việc song song, tách ra từ main. Bạn tạo nhánh để sửa tài liệu mà không đụng tới bản chính thức, cho tới khi sửa xong và được duyệt. Hãy hình dung main là bản thảo "đã xuất bản" đặt trong tủ kính, còn branch là bản photocopy bạn cầm về bàn để viết tay lên — sửa thoải mái, hỏng cũng không sao, vì bản trong tủ kính vẫn nguyên vẹn.

History (lịch sử). Chuỗi tất cả commit theo thời gian. Đây là điều khiến Git mạnh hơn Google Docs cho tài liệu kỹ thuật: bạn trả lời được "đoạn này thêm lúc nào, bởi ai, trong PR nào?" chỉ bằng cách đọc lịch sử — vô giá với tài liệu sản phẩm, nơi một câu sai có thể khiến đội dev build nhầm.

Bốn lệnh đủ cho 90% công việc tài liệu:

Bạn không cần thuộc lòng rebase, cherry-pick, hay reset --hard để đóng góp tài liệu. Khi cần, hãy hỏi maintainer (người bảo trì). Mục tiêu của bài này là cộng tác an toàn, không phải trở thành chuyên gia Git.

2. Luồng branch → edit → pull request

Phản xạ sai phổ biến nhất của người mới là sửa thẳng lên main. Cách đó có thể ổn với ghi chú cá nhân, nhưng với tài liệu chung của một super-app (siêu ứng dụng) thì nguy hiểm: không ai review, không ai biết bạn đổi gì, và nếu bạn viết sai một yêu cầu, nó lập tức thành "sự thật" cho cả đội.

Luồng đúng có bốn bước, và nó giống hệt cách đội kỹ thuật quản lý code:

1. Tạo branch  →  2. Sửa doc  →  3. Mở pull request  →  4. Review & merge

Hãy đi qua một ví dụ cụ thể. Giả sử trong super-app NovaApp, mini-app (ứng dụng con chạy bên trong shell) Booking vừa đổi chính sách huỷ đặt chỗ: trước đây cho huỷ miễn phí trong 24 giờ, nay rút xuống còn 2 giờ. Tài liệu cần cập nhật theo.

Bước 1 — Tạo branch. Bạn tách một nhánh đặt tên mô tả rõ nội dung. Quy ước đặt tên: tiền tố loại thay đổi, rồi mảng, rồi mô tả ngắn bằng kebab-case (chữ thường nối bằng gạch ngang).

git checkout main
git pull                                   # lấy bản mới nhất trước khi tách nhánh
git checkout -b docs/booking-cancel-window

Tên nhánh docs/booking-cancel-window nói ngay cho người khác biết: đây là thay đổi tài liệu, thuộc mảng booking, về cửa sổ thời gian huỷ. Tránh tên mơ hồ như fix, update, hay branch-cua-toi.

Bước 2 — Sửa doc. Bạn mở file tài liệu của Booking và cập nhật nội dung. Quan trọng: bạn sửa cả tài liệu lẫn mọi thứ liên quan trong cùng nhánh — ví dụ nếu có một bảng tham số cấu hình cancel_window_hours: 24, bạn đổi luôn thành 2 ở đây, để tài liệu và cấu hình không lệch nhau (xem mục 6).

# (bạn chỉnh sửa trong editor)
git add docs/booking/cancel-policy.md examples/booking/config.sample.yaml
git commit -m "docs(booking): rút cửa sổ huỷ miễn phí từ 24h xuống 2h"

Bước 3 — Mở pull request. Bạn đẩy nhánh lên và mở một PR. PR là lời đề nghị hợp nhất nhánh của bạn vào main, kèm phần mô tả để người review hiểu bối cảnh.

git push -u origin docs/booking-cancel-window
# rồi mở PR trên giao diện web của GitHub

Phần mô tả PR nên trả lời ba câu: thay đổi gì, vì sao, cần ai để ý gì. Một mô tả PR tốt cho ví dụ Booking:

Tiêu đề: docs(booking): rút cửa sổ huỷ miễn phí từ 24h xuống 2h

Thay đổi gì: Cập nhật cancel-policy.md và file cấu hình mẫu để phản ánh chính sách mới (huỷ miễn phí trong 2 giờ thay vì 24 giờ).

Vì sao: Quyết định kinh doanh BRD-Booking-014 (giảm tỷ lệ huỷ phút chót). Đính kèm link tới yêu cầu gốc.

Cần để ý: Có 1 ví dụ trong tài liệu vẫn dùng "24h" trong phần FAQ — tôi đã sửa, nhờ reviewer kiểm chéo xem còn sót chỗ nào nhắc tới 24h không.

Bước 4 — Review & merge. Một maintainer (hoặc đồng đội được CODEOWNERS gán) sẽ đọc, để lại nhận xét, yêu cầu chỉnh nếu cần, rồi approve (duyệt). Khi đã có ít nhất một lượt duyệt và CI (kiểm tra tự động) xanh, PR được merge (hợp nhất) vào main. Lúc đó — và chỉ lúc đó — thay đổi của bạn mới thành chính thức.

Lợi ích của vòng này: mọi thay đổi tài liệu đều có một người thứ hai nhìn qua, có bối cảnh ghi lại trong mô tả PR, và có đường lui — nếu sai, chỉ cần revert (hoàn tác) đúng PR đó, không ảnh hưởng phần còn lại.

3. Viết commit message tốt cho docs

Commit message là thứ "bạn của tương lai" (và đồng đội) sẽ đọc khi truy lịch sử. Một thông điệp tốt giải thích vì sao, không chỉ cái gì — vì "cái gì" thì xem diff (so sánh thay đổi) đã thấy, còn "vì sao" thì chỉ người viết mới biết.

Quy ước gọn mà repo này khuyến nghị, theo phong cách Conventional Commits:

<loại>(<phạm vi>): <mô tả ngắn, thể mệnh lệnh, không dấu chấm cuối>

• loại cho tài liệu thường là docs. (Code dùng feat, fix, chore, refactor.)
• phạm vi là mảng tài liệu: booking, payments, wallet, rewards, hoặc shell cho tài liệu nền tảng dùng chung.
• mô tả viết như đang ra lệnh: "thêm", "sửa", "làm rõ", "xoá" — chứ không phải "đã thêm" hay "đang sửa".

Ví dụ TỐT — cụ thể, có loại + phạm vi, nói rõ hành động:

docs(booking): rút cửa sổ huỷ miễn phí từ 24h xuống 2h
docs(payments): thêm mục xử lý lỗi timeout khi gọi cổng thanh toán
docs(wallet): sửa số dư tối thiểu trong ví dụ nạp tiền (10k → 50k)
docs(shell): làm rõ thứ tự khởi tạo mini-app trong tài liệu vòng đời
docs(rewards): xoá mục khuyến mãi đã hết hạn khỏi bảng quyền lợi

Ví dụ XẤU — mơ hồ, không truy được, hoặc gộp nhiều việc:

update                          ← cập nhật cái gì? mảng nào?
sửa tí                          ← sửa gì, vì sao?
fix docs                        ← chung chung, vô dụng khi đọc lịch sử
WIP                             ← "đang làm" không nên có trong lịch sử main
cập nhật booking và payments và wallet và sửa typo   ← một commit ôm quá nhiều việc

Hai nguyên tắc đáng nhớ:

1. Một commit = một ý. Nếu bạn vừa sửa chính sách huỷ của Booking vừa sửa lỗi chính tả ở Wallet, hãy tách thành hai commit. Khi cần hoàn tác một phần, bạn sẽ cảm ơn chính mình.

2. Mô tả ngắn gọn ở dòng đầu (≤ ~72 ký tự), chi tiết để xuống thân commit. Nếu cần giải thích dài hoặc link tới yêu cầu gốc, để một dòng trống rồi viết thân:

docs(booking): rút cửa sổ huỷ miễn phí từ 24h xuống 2h

Theo quyết định BRD-Booking-014 nhằm giảm tỷ lệ huỷ phút chót.
Đồng bộ luôn file cấu hình mẫu để tài liệu và config không lệch.

4. Review docs như review code

Tài liệu sai gây hại không kém code sai: đội dev build nhầm theo một yêu cầu mô tả sai, và lỗi chỉ lộ ra khi đã muộn. Vì vậy repo này áp dụng chuẩn "review tài liệu như review code". Khi bạn được gán review một PR tài liệu, bạn không chỉ bắt lỗi chính tả — bạn kiểm bốn thuộc tính.

Dưới đây là review checklist cho docs mà bạn có thể dán vào mỗi PR tài liệu:

• Khớp nguồn: Mọi con số, tên trường, tên API trong tài liệu có khớp với code/cấu hình thật không? (đã grep để kiểm chéo)
• Truy vết: Thay đổi có link tới yêu cầu gốc (BRD/PRD/FR) không, để biết vì sao?
• Đầy đủ: Có nêu trường hợp lỗi và điều kiện biên, không chỉ luồng thuận lợi?
• Nhất quán: Thuật ngữ, định dạng, cách đặt tên theo đúng quy ước của repo?
• Không drift: Nếu PR đụng code, tài liệu liên quan có được sửa trong cùng PR không?
• Đọc được: Câu rõ ràng; nếu là nội dung hướng người dùng cuối thì song ngữ (EN + VI) theo chuẩn repo.

Cho feedback xây dựng quan trọng không kém việc bắt lỗi. Vài nguyên tắc:

• Phê bình nội dung, không phê bình người. Viết "Đoạn này có thể hiểu theo hai cách —" thay vì "Bạn viết khó hiểu quá."
• Phân biệt bắt buộc và gợi ý. Đánh dấu rõ: [blocking] (phải sửa mới merge được) so với [nit] (gợi ý nhỏ, tuỳ tác giả). Đừng để một góp ý nhỏ về dấu phẩy chặn cả một PR tốt.
• Đề xuất cụ thể. Thay vì "chỗ này chưa ổn", hãy viết lại giúp một câu mẫu. Người viết dễ tiếp thu hơn nhiều.
• Khen điều làm tốt. Một dòng "Phần xử lý lỗi viết rất rõ, cảm ơn" giữ cho cộng tác lành mạnh và bền.

Mục tiêu của review không phải để "bắt lỗi nhau" mà để bản tài liệu cuối tốt hơn bản đầu vào — đúng như review code làm cho phần mềm tốt hơn.

5. CODEOWNERS + branch protection: ai gác cổng

Khi repo lớn lên, bạn không muốn mọi PR đều đổ dồn cho một người, cũng không muốn ai đó vô tình merge nhầm vào main. Hai cơ chế của Git/GitHub lo việc này.

CODEOWNERS — tự gán reviewer theo mảng. Đây là một file ở gốc repo, ánh xạ đường dẫn file tới người sở hữu. Khi một PR đụng tới file khớp một dòng, người (hoặc nhóm) đó được tự động gán làm reviewer. Không ai phải nhớ "ai phụ trách mảng booking" — Git nhớ giúp.

File CODEOWNERS của repo này hiện ở dạng tối giản, đúng tinh thần BDFL-hybrid:

# BDFL-hybrid: lead maintainer sở hữu mọi thứ mặc định.
*                       @leduykhuong-daniel

# Thêm owner theo mảng khi đội core lớn lên, ví dụ:
# skills/                @some-trusted-maintainer

Dòng * nghĩa là mọi đường dẫn mặc định thuộc lead maintainer. Khi đội core mở rộng, bạn mở comment để gán owner riêng cho từng mảng — ví dụ tài liệu mini-app Payments giao cho một maintainer chuyên về thanh toán:

docs/payments/          @payments-maintainer
docs/booking/           @booking-maintainer

Branch protection — bảo vệ nhánh main. Đây là cấu hình phía GitHub đặt ra "luật cứng" cho main. Trong repo này, main được bảo vệ với các điều kiện:

• Mọi thay đổi phải qua PR — không ai được push thẳng lên main, kể cả maintainer.
• Ít nhất một lượt duyệt trước khi merge.
• CI phải xanh — các kiểm tra tự động (ví dụ scripts/validate-skills.sh) phải pass.

Ba điều này biến "review docs như code" từ một lời khuyên thành một rào cản kỹ thuật: dù bạn vội đến đâu, hệ thống vẫn buộc thay đổi đi qua một lượt mắt thứ hai.

Mô hình quản trị BDFL-hybrid. Repo này theo mô hình BDFL-hybrid — kết hợp một lead maintainer (BDFL — "nhà độc tài nhân từ trọn đời", người ra quyết định cuối) với một core team tin cậy và đóng góp công khai từ cộng đồng:

• Core team (xem MAINTAINERS.md) có quyền ghi, được review và merge PR.
• Người ngoài đóng góp qua PR từ một bản fork; PR qua CI rồi maintainer review và merge.
• Đóng góp chất lượng, bền bỉ theo thời gian có thể dẫn tới lời mời vào core team — quyết định thuộc về lead maintainer.

Ba tài liệu quản trị bạn nên đọc trước khi đóng góp lần đầu:

6. Chống doc drift: tài liệu và code trong CÙNG một PR

Doc drift (lệch tài liệu) là khi tài liệu và sản phẩm thật dần dần "trôi" ra xa nhau. Code đổi, tài liệu thì không — và sau vài tháng, tài liệu trở thành thông tin sai, tệ hơn cả không có tài liệu, vì nó khiến người đọc tin nhầm.

Nguyên nhân gốc gần như luôn giống nhau: thay đổi code và cập nhật tài liệu được tách thành hai việc, hai thời điểm — và việc thứ hai bị quên. "Để mai cập nhật doc" là câu mở đầu của mọi tài liệu lỗi thời.

Giải pháp của docs-as-code đơn giản đến mức dễ bị xem thường:

Tài liệu và code thay đổi cùng nhau, trong cùng một pull request.

Vì sao điều này giữ tài liệu đồng bộ:

• Cùng một review. Reviewer nhìn diff code và diff tài liệu cạnh nhau, lập tức thấy nếu tài liệu chưa khớp hành vi mới. Drift bị chặn ngay tại cổng, thay vì lộ ra sau ba tháng.
• Cùng một lịch sử. Lịch sử Git ghi rằng "hành vi X được thêm kèm tài liệu của nó" trong một commit/PR. Sau này truy vết, bạn thấy code và doc luôn đi đôi.
• Cùng một đường lui. Nếu phải revert tính năng, bạn revert đúng PR đó — và tài liệu tự động lùi theo. Không còn cảnh "code đã gỡ nhưng doc vẫn quảng cáo tính năng không tồn tại".

Quay lại ví dụ Booking ở mục 2: chính vì bạn đổi cancel-policy.md và config.sample.yaml trong cùng nhánh docs/booking-cancel-window, reviewer chỉ cần một lượt nhìn là xác nhận được tài liệu khớp cấu hình. Nếu bạn chỉ sửa tài liệu mà bỏ quên file cấu hình mẫu, reviewer sẽ thấy ngay sự thiếu nhất quán và yêu cầu bổ sung trước khi merge.

Checklist PR của repo (cũng nằm trong CONTRIBUTING.md) mã hoá nguyên tắc này thành một ô bắt buộc tick: "Docs and code changed together (no doc drift)". Đó không phải hình thức — đó là tuyến phòng thủ chính chống lại căn bệnh tài liệu lỗi thời.

🛠 Bài tập thực hành

Bài tập này luyện trọn vòng cộng tác tài liệu cho một mini-app NovaApp giả định. Làm được theo cặp lẫn một mình — nếu tự học, xem "Biến thể solo" ở cuối.

Chuẩn bị. Bạn làm trong một repo tập của riêng mình (một thư mục bất kỳ đã git init). Tự tạo file docs/rewards/earn-policy.md với nội dung mẫu có nhắc con số cũ ở vài chỗ (mục chính + một ví dụ + một dòng FAQ) — đây là tài liệu bạn sẽ sửa.

Bối cảnh. Mini-app Rewards của NovaApp vừa đổi quy tắc tích điểm: trước đây mỗi 10.000đ chi tiêu được 1 điểm, nay đổi thành mỗi 20.000đ được 1 điểm. Tài liệu cần cập nhật.

Phần A — Mở một pull request (branch → edit → PR):

1. Tạo branch với tên mô tả rõ:

   git checkout main && git pull
   git checkout -b docs/rewards-earn-rate

2. Sửa doc. Trong file tài liệu Rewards (giả định docs/rewards/earn-policy.md), cập nhật tỷ lệ tích điểm từ 10.000đ = 1 điểm thành 20.000đ = 1 điểm. Nhớ rà soát mọi chỗ nhắc tới con số cũ — kể cả ví dụ và FAQ — để tránh drift.
3. Commit với thông điệp tốt theo quy ước mục 3:

   git add docs/rewards/earn-policy.md
   git commit -m "docs(rewards): đổi tỷ lệ tích điểm từ 10k xuống còn 20k/điểm"

4. Đẩy nhánh và mở PR. Viết mô tả PR trả lời ba câu: thay đổi gì, vì sao, cần reviewer để ý gì. Cài ít nhất một điểm "nhờ kiểm chéo" (ví dụ: "nhờ kiểm xem còn chỗ nào nhắc 10k không").

Phần B — Review chéo PR của đồng đội:

5. Mở PR của đồng đội và áp review checklist cho docs (mục 4). Với mỗi mục, tự hỏi và để lại nhận xét.
6. Tìm chủ đích ít nhất một vấn đề — một con số sót, một câu mơ hồ, hay một trường hợp biên bị bỏ qua. Viết feedback xây dựng: đánh dấu [blocking] hay [nit], và đề xuất câu sửa cụ thể.
7. Khi tác giả đã chỉnh, để lại một lời approve kèm một câu khen điều họ làm tốt.

Tiêu chí hoàn thành: Cả hai PR đều (a) có tên nhánh và commit message theo quy ước, (b) sửa mọi chỗ nhắc tới con số cũ (không drift), (c) nhận được ít nhất một feedback xây dựng đã được giải quyết trước khi "merge giả lập". Nếu một người lần ngược được từ PR tới lý do kinh doanh của thay đổi qua phần mô tả, bạn đã làm đúng tinh thần truy vết.

Biến thể solo (tự học một mình). Sau khi xong Phần A, tự đóng vai reviewer: tạo một nhánh thứ hai, cố ý để sót một chỗ vẫn ghi 10.000đ, mở PR thứ hai, rồi áp checklist Phần B lên chính PR của mình — tìm cho ra chỗ sót đó. Bạn vừa luyện cả viết lẫn review mà không cần đồng đội.

👉 Tham khảo đáp án: xem examples/nova-superapp/CODEOWNERS để thấy cách gán owner theo mini-app, và mini-apps/booking/docs/refund-integration.md cho một tài liệu mini-app thật.

Lỗi Git thường gặp (đọc khi vướng)

Người mới dùng Git cho tài liệu hay gặp ba tình huống sau:

💡 Đừng sợ các lỗi này — chúng là "phản xạ bình thường" của Git, không phải hỏng hóc. Mỗi lần gặp và xử lý xong, bạn vững thêm một bậc.

Tóm tắt

• Người viết tài liệu chỉ cần bốn khái niệm Git: repo, commit, branch, history — và bốn lệnh clone / checkout -b / add / commit.
• Luồng chuẩn là branch → edit → pull request → review & merge; không sửa thẳng lên main. Branch là "bản photocopy" để sửa an toàn; main là bản đã xuất bản trong tủ kính.
• Commit message tốt dùng quy ước docs(<phạm vi>): <mô tả mệnh lệnh>, một commit một ý, giải thích vì sao chứ không chỉ cái gì.
• Review docs như review code kiểm bốn thuộc tính — đúng, rõ, đủ, không drift — qua một checklist, và cho feedback xây dựng (phân biệt [blocking] với [nit]).
• CODEOWNERS tự gán reviewer theo mảng; branch protection buộc mọi thay đổi main qua PR + ≥1 duyệt + CI xanh, kể cả maintainer. Repo theo mô hình quản trị BDFL-hybrid (lead + core team + đóng góp công khai).
• Chống doc drift bằng một quy tắc duy nhất: tài liệu và code thay đổi trong cùng một PR — cùng review, cùng lịch sử, cùng đường lui.

Đọc tiếp

• Lesson 5 — Tự động hoá & Mở rộng: Khi luồng PR đã quen tay, bước tiếp là để máy lo phần lặp lại — CI tự kiểm tài liệu, validate frontmatter, build site, và phát hiện drift tự động. Lesson 5 sẽ chỉ cách dựng các kiểm tra này trên cùng đường ống PR bạn vừa học.
• Tham chiếu quản trị: Trước khi mở PR thật đầu tiên, đọc CONTRIBUTING.md để nắm checklist PR và chuẩn "review docs như code", rồi liếc MAINTAINERS.md và CODEOWNERS để biết ai sẽ review thay đổi của bạn.