Trở thành đồng tác giả

Cẩm nang được viết mở, cộng tác qua GitHub. Mỗi chương là một file Markdown; mọi thay đổi đi qua Pull Request để có review và lịch sử.

Ba vai trò

• Author — chịu trách nhiệm nội dung 1 hoặc nhiều chương. Đặt tên mình vào owners: ở đầu file chương.
• Coordinator — review PR, merge, quản lý lịch. Có quyền write trên repo.
• Reviewer — chuyên gia mời để đọc và bình luận. Không cần quyền write, có thể comment trên PR hoặc mở Issue.

Ba cách chỉnh sửa — chọn theo thói quen

Mỗi trang chương có sẵn 3 nút. Chọn cái bạn thấy tiện nhất.

1. ✨ Soạn trong CMS (không cần biết Git)

Mở trực tiếp ai-yte.vn/admin. Login bằng GitHub. Thấy danh sách 18 chương dạng bảng, lọc theo trạng thái / phần. Bấm chương → editor Markdown có preview, upload ảnh kéo thả, form frontmatter dạng dropdown. Save → CMS tự tạo branch và PR, không cần biết Git.

Có sẵn panel ✨ Chấp bút với AI — dán đoạn Markdown, chọn nhiệm vụ (viết tiếp / tóm tắt / dịch / chuẩn hoá thuật ngữ), AI trả về kết quả để bạn sao chép về CMS. API key của bạn lưu ở trình duyệt, không gửi lên server ai-yte.vn.

2. 💻 VS Code trong trình duyệt (github.dev)

Bấm nút Mở VS Code trong trình duyệt trên mỗi chương — GitHub mở VS Code full trong tab mới, có sidebar duyệt file, search toàn repo, markdown preview. Nếu bạn có GitHub Copilot, Copilot Chat hoạt động ngay. Commit thuận tiện cho ai biết VS Code.

3. Sửa nhanh trên GitHub

Editor cổ điển — chỉ textarea. Dùng khi cần sửa 1–2 dòng.

Quy trình chung sau khi chỉnh sửa

1. Dù chọn cách nào ở trên, thay đổi sẽ đi đến một Pull Request.
2. Vercel tự tạo preview URL cho PR — xem bản render trước merge.
3. Reviewer comment theo dòng, approve. Coordinator merge → tự deploy.

Frontmatter mỗi chương

Đầu file chương có khối YAML điều khiển hiển thị. Đây là ví dụ:

---
number: 4
title: "Nền tảng AI đa nhiệm"
part: "Phần II — Hiện trạng"
status: draft         # draft | review | final
domains: ["Technical", "Communication"]
miller: "Knows How → Shows How"
owners: ["Tú"]
updated: "2026-09-09"
summary: "Cửa vào cho L0/L1..."
---

Chỉ cần đổi status: thành review hoặc final là dashboard tiến độ tự cập nhật.

Quy ước viết

• Tiếng Việt, giọng thực hành, tránh học thuật khô.
• Mỗi chương có 5 phần cố định: Định nghĩa · Hiện trạng · Case · Hướng dẫn L0–L3 · Rủi ro/Tuân thủ. Cuối chương có mô tả Lab.
• Trích dẫn nguồn bằng Markdown link: [Tên nguồn](https://...).
• Case của tác giả đặt trong blockquote để phân biệt.
• Bảng dùng Markdown table thường. Sơ đồ phức tạp có thể vẽ Mermaid ở giai đoạn sau.

Cần hỗ trợ?

Mở Issue tại https://github.com/darkbaronuk/ai-yte-handbook/issues/new hoặc liên hệ coordinator qua email trong file MAINTAINERS.md.