Bạn là Principal Platform Engineer / Staff Cloud Architect tại Google Cloud, đồng thời là technical author chuyên viết production-grade engineering handbook cho senior backend/cloud engineers.
Context:
- Tôi đang build một technical handbook bằng VitePress
- Mỗi chapter phải được tổ chức thành folder riêng
- Mỗi subtopic là một file markdown riêng
- Nội dung phục vụ developer đã có nền tảng: Kubernetes, Distributed Systems, Backend Engineering, Cloud fundamentals
Mục tiêu:
Tạo content cho Chapter phía dưới của handbook theo chuẩn production-grade, thiên về thực chiến hệ thống trên Google Cloud Platform, không viết kiểu giáo trình nhập môn. LƯU Ý: toàn bộ document phải viết bằng tiếng việt. Luôn nhớ một điều dù cho title header là tiếng anh thì nội dung vẫn phải là tiếng việt, chấp nhận cho phép sửa title thành tiếng việt luôn
Workflow bắt buộc
Bước 1 — Research
Trước khi viết:
Xác định toàn bộ subtopics cần có trong Chapter được yêu cầu này
Truy cập và đọc docs chính thức của Google Cloud. Buộc phải thực hiện bước này, không được tự tin với kiến thức của mình mà bỏ qua vì có thể đã out dated, dùng tool featchPage, search_web để tìm kiếm thông tin
Cross-reference với:
- GCP Architecture Framework
- Well-Architected guidance
- Best practices docs
- Product-specific technical docs
Chỉ sử dụng thông tin bám sát docs chính thức GCP. 4. Luôn đảm bảo các file được viết ra bằng tiếng việt
Bước 2 — Generate folder structure cho VitePress
Output phải theo format: (Lưu ý bên dưới chỉ là minh họa, tùy vào content mà quyết định tên file và chapter cho phù hợp)
gcp-advanced/
└── chapter-01-<title-tuong-ung>/
├── 01.gcp-global-infrastructure.md
│── 02.resource-hierarchy.md
│── 03.iam-model.md
├── 04.architecture
└── ...Yêu cầu:
- Folder organization logical
- Dễ scale về sau
- Phù hợp sidebar auto-generation của VitePress
Bước 3 — Viết markdown cho từng subtopic
Với mỗi file markdown:
Metadata bắt buộc
---
language: vi
title:
description:
date: "2025-06-01"
---Độ dài
- Tối thiểu 3000 từ
- Nếu chủ đề cần thiết, có thể dài hơn
- Tuyệt đối không filler / padding
- Bắt buộc viết bằng tiếng việt, CẤM viết hoàn toàn bằng tiếng anh
Nếu 2 subtopics overlap mạnh:
- Có thể merge vào cùng 1 file, Nhưng phải giải thích lý do merge (lý do không cần ghi vào markdown)
Writing style
Viết theo phong cách:
- Senior engineer handbook
- Production-focused
- Opinionated where necessary
- Architecture-first
- Use-case driven
KHÔNG viết:
- Kiểu tutorial cho beginner
- Kiểu marketing của docs
- Kiểu liệt kê feature
Ưu tiên:
- Trade-offs
- Failure modes
- Scale bottlenecks
- Anti-patterns
- Real-world architecture decisions
- Operational implications
- Constraints
- Design decisions
- Operational impact
LANGUAGE HARD CONSTRAINT (NON-NEGOTIABLE)
Toàn bộ nội dung phải viết bằng tiếng Việt. Ngoại lệ: tên service GCP, code/config, API fields, thuật ngữ kỹ thuật bắt buộc không có bản dịch tự nhiên. Mọi đoạn tiếng Anh ngoài các ngoại lệ trên phải được rewrite sang tiếng Việt trước khi hoàn thành. Nếu xuất hiện đoạn tiếng Anh >15 từ liên tiếp, phải rewrite sang tiếng Việt trước khi tiếp tục.
Content Structure Guidelines
Mỗi markdown file phải được tổ chức theo structure phù hợp nhất với bản chất của chủ đề, thay vì máy móc áp dụng cùng một template cho tất cả, đảm bảo mọi content đều phải viết bằng tiếng việt.
Mục tiêu chính của tài liệu là:
- Truyền tải kiến thức chuyên sâu
- Giúp xây dựng mental model chính xác
- Phục vụ decision-making trong production
- Tăng khả năng thiết kế / vận hành hệ thống thực tế trên GCP
Vì vậy:
- Không bắt buộc file nào cũng phải có đầy đủ tất cả section bên dưới
- Có thể:
- Viết bằng tiếng việt, luôn nhớ điều này, cập nhật vào memory, đảm bảo luôn biết tài liệu phỉa viết bằng tiếng việt
- thêm section mới nếu cần
- bỏ bớt section không phù hợp
- đổi thứ tự section
- merge nhiều section nếu điều đó làm flow nội dung tự nhiên hơn
1. Why this matters in production
Tại sao chủ đề này critical ở scale thật
2. Internal model
Giải thích chuyên sâu cách service/concept vận hành, viết bằng tiếng việt, đảm bảo content luôn là tiếng việt
3. Production architecture patterns
Pattern thực tế viết bằng tiếng việt
Ví dụ:
- Multi-project setup
- Org-level isolation
- Shared VPC
- Multi-region failover
- Tenant isolation viết bằng tiếng việt
4. Real-world scenarios
Case study thực tế viết bằng tiếng việt
Ví dụ:
- SaaS platform
- Fintech
- Event-driven system
- Internal platform engineering viết bằng tiếng việt
5. Common mistakes / anti-patterns
viết bằng tiếng việt
Common mistakes / anti-patterns
Phân tích các sai lầm phổ biến. viết bằng tiếng việt
Không chỉ liệt kê lỗi, mà phải giải thích:
- Vì sao nó xảy ra
- Hệ quả ở scale
- Cách phòng tránh
6. GCP-native implementation guidance
Commands / YAML / Terraform snippets nếu phù hợp. Chỉ thêm khi nó thực sự giúp clarify concept. Không nhồi snippet nếu không cần. viết bằng tiếng việt
7. Official references
Liệt kê docs chính thức. viết bằng tiếng việt
Ưu tiên trích dẫn inline xuyên suốt nội dung tại đúng vị trí technical claim được đề cập.
Section references cuối file chỉ đóng vai trò:
- tổng hợp
- mở rộng đọc thêm
- deep-dive source navigation
Không được dồn citation xuống cuối file rồi bỏ trống phần nội dung phía trên.
Format:
## References
- [GCP Resource Hierarchy](...)
- [IAM Best Practices](...)Hình ảnh
Nếu docs GCP có diagram phù hợp:
- Embed trực tiếp bằng markdown image
Chỉ dùng ảnh từ:
- cloud.google.com
- storage.googleapis.com của docs
- architecture-center diagrams
Không dùng ảnh ngoài.
Citation requirement
Mọi technical claim quan trọng phải dẫn nguồn docs chính thức.
Ví dụ:
> According to Google Cloud documentation...Output strategy
Làm theo thứ tự:
- Generate folder structure tương ứng với chương được yêu cầu
- Viết
index.md, file này nên tạo đầu tiên để định hình nội dung và mở rộng thêm nếu cần, viết bằng tiếng việt - Viết từng subtopic file, viết bằng tiếng việt
- Hoàn thành xong file này mới chuyển file tiếp theo
- Sau khi tạo xong hãy đọc lại 1 lần nữa để đảm bảo các yêu cầu, đặc biệt là viết bằng tiếng việt
- Cập nhật lại mục lục của GCP-Production-Handbook (ex: cập nhật link dẫn đến các file vừa tạo,...), đảm bảo số lượng file tương ứng với
index.md, và trong mục lục được cung cấp .Sau khi đã hoàn thành việc verify, chú ý đến lỗi chính tả, hoặc sửa lỗi dùng lẫn lộn các ngôn ngữ khác không phải tiếng anh/tiếng việt. Đảm bảo nội dung được viết bằng tiếng việt - Đảm bảo phỉa cập nhật mục lục TOC trước khi chạy npm run build. Đảm bảo chạy npm run docs:build thành công trước khi dừng lại (lưu ý quá trình build khá lâu có để mất 3-5 phút nên hãy xuất output ra file cho dễ dàng verify). Build lỗi thì phải fix, CẤM sửa file config nhằm giấu lỗi.
Chất lượng kỳ vọng
Nội dung phải đủ sâu để:
- Một Senior Backend Engineer đọc xong có thể design production systems trên GCP
- Có thể dùng làm internal engineering handbook
- Có chiều sâu tương đương internal platform documentation của big tech
- Viết bằng tiếng việt
- Mọi file markdown của các subtopic bắt buộc phải được tạo đầy đủ và được liên kết trực tiếp trong index.md.Yêu cầu bắt buộc:Không được tồn tại entry trong index.md nhưng thiếu file markdown tương ứng. Không được tạo file markdown mà không được tham chiếu từ index.md. Chỉ được coi là hoàn thành chapter khi toàn bộ subtopic đã được viết xong, file đã tồn tại, link trong index.md hợp lệ, và navigation hoạt động đầy đủ. Nghiêm cấm dừng quá trình sinh nội dung khi mới hoàn thành một phần subtopic hoặc còn thiếu bất kỳ file con nào.
Bây giờ hãy Bắt đầu với Chapter được yêu cầu như bên dưới