Tạo Tài Liệu Kỹ Thuật — Hướng Dẫn

Tạo Tài Liệu Kỹ Thuật

Tham Khảo Nhanh

Đối tượng: Developer, Tech Lead

Đầu ra: 4 file .md (architecture, database, deployment, data-flow)

Thời gian: ~10 phút

Yêu cầu: Project cần có source code để quét

Yêu Cầu

DocKit Master đã cài đặt (xem Hướng dẫn triển khai)
Có source code project cần tạo tài liệu
Đang ở trong session Google Antigravity

Hướng Dẫn Từng Bước

Bước 1: Trigger DocKit Master

Mở Google Antigravity chat
Gõ một trong các câu sau:

Dùng DocKit Master để tạo tài liệu kỹ thuật cho project tại /path/to/project

Hoặc sử dụng CLI:

bash ~/.gemini/antigravity/skills/doc-kit/scripts/doc-gen.sh

Bước 2: Trả Lời Cấu Hình

Agent sẽ hiển thị form 10 câu hỏi. Trả lời ngắn gọn:

Câu hỏi	Trả lời cho Tech Docs
Loại tài liệu	`tech`
Định dạng output	`astro` hoặc `markdown`
Phạm vi quét	`full`
Ngôn ngữ	Auto-detect từ ngôn ngữ bạn chat
SEO	`yes` (khuyến nghị)
LLM optimize	`yes` (khuyến nghị)

Bước 3: Chờ Quét Code

Agent sẽ tự động:

Quét toàn bộ codebase (skills/analyze-codebase.md)
Detect tech stack, frameworks, dependencies
Map architecture layers
Extract routes, database schema
Tạo docs/analysis.md

Bước 4: Review Output

Sau khi hoàn thành, kiểm tra 4 file được tạo:

File	Nội dung	Check
`docs/architecture.md`	Sơ đồ kiến trúc, ADR, components	≥2 Mermaid diagrams
`docs/database.md`	Database schema, ER diagram	Table schema chi tiết
`docs/deployment.md`	Cài đặt, CI/CD, monitoring	Copy-paste commands
`docs/data-flow.md`	Pipeline, sequence diagrams	≥3 Mermaid diagrams

Bước 5: Build Site (Nếu chọn Astro)

cd astro-site
npm install
npm run build
npm run preview -- --port 4321

Mở http://localhost:4321 để xem kết quả.

Kết Quả Mong Đợi

✅ Mỗi file có Quick Reference card ở đầu
✅ Mỗi file có ≥2 Mermaid diagrams với dark-mode colors
✅ Mỗi claim cite (file_path:line_number)
✅ SEO frontmatter đầy đủ (title, description, keywords, robots)
✅ ≥2 internal links per page

Xử Lý Sự Cố

🔴 Mermaid diagram không render

Nguyên nhân: Astro Starlight không hỗ trợ Mermaid mặc định.

Giải pháp:

Cài remark-mermaidjs:

cd astro-site && npm install remark-mermaidjs

Thêm vào astro.config.mjs:

import remarkMermaid from 'remark-mermaidjs';
// ...
markdown: { remarkPlugins: [remarkMermaid] }

🔴 Build fail: Missing title in frontmatter

Nguyên nhân: Starlight yêu cầu mọi .md file phải có title trong frontmatter.

Giải pháp: Thêm title: "..." vào YAML frontmatter ở đầu file.

FAQ

Q: Tech docs có tự cập nhật khi code thay đổi không?

A: Không tự động. Bạn cần chạy lại DocKit Master khi code thay đổi đáng kể. Tuy nhiên, quá trình chạy lại rất nhanh (~5 phút) vì Agent sẽ quét code mới và ghi đè docs cũ.

Q: Có thể tạo tech docs cho 1 module cụ thể thay vì toàn bộ project?

A: Có. Chọn focused ở câu hỏi “Phạm vi quét” và chỉ định tên module/thư mục cụ thể.

Xem thêm: Tạo SOP guides · Sử dụng CLI