"Giải thích Như thể Chính Tôi Đã Xây dựng Nó" Tài liệu Kỹ thuật dành cho Nhà sáng lập Không chuyên Kỹ thuật

Bạn là một chuyên gia viết tài liệu kỹ thuật (technical writer) cấp cao chuyên làm cho các hệ thống phức tạp trở nên dễ hiểu đối với những người không phải là kỹ sư. Bạn có năng khiếu sử dụng phép tương tự (analogy), lối kể chuyện và biến các sơ đồ kiến trúc khô khan thành những câu chuyện sinh động. Tôi cần bạn phân tích dự án này và viết một tệp tài liệu toàn diện có tên là `FORME.md` giải thích mọi thứ về dự án này bằng ngôn ngữ đời thường dễ hiểu. ## Ngữ cảnh Dự án - **Tên dự án:** - **Dự án làm gì (trong một câu):** [ví dụ: "Một nền tảng SaaS giúp các nhà hàng tự quản lý việc đặt món trực tuyến của riêng họ mà không phải trả hoa hồng cho các bên trung gian"] - **Vai trò của tôi:** [ví dụ: "Tôi là nhà sáng lập / chủ sở hữu sản phẩm / nhà thiết kế — tôi không viết mã nhưng tôi đưa ra mọi quyết định về sản phẩm và kiến trúc"] - **Ngăn xếp công nghệ (nếu bạn biết):** [ví dụ: "Next.js, Supabase, Tailwind" hoặc "Tôi không chắc lắm, hãy tự tìm hiểu từ mã nguồn nhé"] - **Giai đoạn:** [MVP / v1 đang chạy thực tế / đang mở rộng quy mô / tái cấu trúc hệ thống cũ] ## Cơ sở Mã nguồn (Codebase) [Tải các tệp lên, cung cấp đường dẫn hoặc dán các tệp quan trọng vào đây] ## Cấu trúc Tài liệu Hãy viết tệp FORME.md với các phần sau đây, theo đúng thứ tự này: ### 1. Bức tranh Toàn cảnh (Tổng quan Dự án) Bắt đầu bằng một bản tóm tắt điều hành dài 3-4 câu mà bất kỳ ai cũng có thể hiểu được. Sau đó cung cấp: - Dự án này giải quyết vấn đề gì và cho ai - Cách người dùng tương tác với nó (hành trình người dùng bằng ngôn từ giản dị) - Một phép ẩn dụ kiểu "nếu hệ thống này là một nhà hàng" (hoặc tương tự) cho toàn bộ hệ thống ### 2. Kiến trúc Kỹ thuật — Bản Thiết kế Tổng thể Giải thích cách hệ thống được thiết kế và TẠI SAO những lựa chọn đó lại được đưa ra. - Vẽ sơ đồ kiến trúc bằng sơ đồ văn bản đơn giản (các khung hộp và mũi tên) - Giải thích từng lớp / dịch vụ chính như thể bạn đang dẫn khách đi tham quan một tòa nhà: "Đây là khu bếp (lớp API) — mọi công việc chế biến thực sự đều diễn ra ở đây. Đơn đặt hàng được chuyển vào từ quầy lễ tân (frontend), được xử lý tại đây, và kết quả được lưu vào tủ hồ sơ (cơ sở dữ liệu)." - Đối với mọi quyết định kiến trúc, hãy trả lời câu hỏi: "Tại sao lại chọn cái này mà không phải là phương án thay thế hiển nhiên kia?" - Làm nổi bật bất kỳ lựa chọn thông minh hoặc khác thường nào mà nhà phát triển đã thực hiện ### 3. Cấu trúc Mã nguồn — Hệ thống Tủ Hồ sơ Lập bản đồ tổ chức tệp và thư mục của dự án. - Hiển thị cây thư mục (2-3 cấp độ cao nhất) - Đối với mỗi thư mục chính, hãy giải thích: - Những gì nằm ở đây (bằng ngôn từ dễ hiểu) - Khi nào một người sẽ cần mở thư mục này ra - Mối liên hệ của nó với các thư mục khác - Gắn cờ lưu ý bất kỳ quy ước đặt tên nào không hiển nhiên - Xác định các "điểm khởi đầu" ("entry points") — những tệp nơi mọi thứ bắt đầu chạy ### 4. Kết nối & Luồng Dữ liệu — Cách Mọi thứ Trò chuyện Với Nhau Truy vết cách dữ liệu di chuyển xuyên suốt hệ thống. - Chọn 2-3 hành động cốt lõi của người dùng (ví dụ: "người dùng đăng ký", "người dùng đặt hàng") - Đối với mỗi hành động, hãy dẫn dắt qua TOÀN BỘ hành trình từng bước một: "Khi người dùng nhấp vào nút 'Đặt hàng' ('Place Order'), đây là những gì diễn ra ở hậu trường: 1. Nút bấm kích hoạt một hàm trong [file] — hãy hình dung nó giống như việc bấm chuông gọi món 2. Tiếng chuông đó truyền tới — nhà bếp nghe thấy đơn hàng 3. Nhà bếp kiểm tra với [database] — chúng ta còn đủ nguyên liệu không? 4. Nếu có, nó gửi trả lại một xác nhận — người phục vụ mang hóa đơn ra cho khách" - Giải thích các kết nối dịch vụ bên ngoài (thanh toán, email, các API) và chuyện gì sẽ xảy ra nếu chúng gặp sự cố - Mô tả luồng xác thực (làm sao ứng dụng biết bạn là ai?) ### 5. Lựa chọn Công nghệ — Hộp Đồ nghề Đối với mỗi công nghệ / thư viện / dịch vụ quan trọng được sử dụng: - Nó là gì (một câu, không dùng biệt ngữ chuyên môn) - Nó đảm nhận công việc cụ thể gì trong dự án này - Tại sao nó được chọn thay vì các phương án khác (hãy cụ thể: "Chúng ta sử dụng Supabase thay vì Firebase bởi vì...") - Bất kỳ hạn chế hoặc sự đánh đổi nào mà bạn cần biết - Hệ quả về chi phí (có gói miễn phí không? trả phí cố định? hay tính theo mức sử dụng?) Định dạng thành một bảng: | Công nghệ | Vai trò Tại đây | Tại sao Chọn Nó | Điểm Cần Lưu ý | |-----------|------------------|-------------|---------------| ### 6. Môi trường & Cấu hình Giải thích cách thiết lập mà không giả định người đọc đã có kiến thức kỹ thuật: - Những biến môi trường (environment variables) nào đang tồn tại và mỗi biến điều khiển cái gì (bằng ngôn ngữ đời thường) - Cách các môi trường khác nhau hoạt động (phát triển - development so với thử nghiệm - staging so với thực tế - production) - "Nếu bạn cần thay đổi [X], bạn sẽ cập nhật tại [Y] — nhưng hãy cẩn thận vì [Z]" - Bất kỳ mã bí mật / khóa (secrets/keys) nào và chúng kết nối tới dịch vụ nào (KHÔNG ghi giá trị thực tế của khóa ra) ### 7. Bài học Kinh nghiệm — Những Câu chuyện Chiến trường Đây là phần giá trị nhất. Hãy ghi chép lại: **Lỗi & Cách Khắc phục (Bugs & Fixes):** - Các lỗi lớn đã gặp phải trong quá trình phát triển - Nguyên nhân gây ra chúng (giải thích đơn giản) - Cách chúng đã được sửa - Cách tránh các vấn đề tương tự trong tương lai **Cạm bẫy & Bãi mìn (Pitfalls & Landmines):** - Những thứ nhìn bề ngoài có vẻ đơn giản nhưng thực chất lại cực kỳ phức tạp - "Nếu có lúc nào đó bạn cần thay đổi [X], hãy hết sức cẩn thận vì nó cũng làm ảnh hưởng tới [Y] và [Z]" - Nợ kỹ thuật (technical debt) đã biết và lý do tại sao nó tồn tại **Những Khám phá (Discoveries):** - Các công nghệ hoặc kỹ thuật mới đã được tìm hiểu - Những gì hoạt động hiệu quả và những gì không - "Nếu được làm lại từ đầu, tôi sẽ..." **Đúc kết Kỹ thuật (Engineering Wisdom):** - Các phương pháp thực hành tốt nhất đúc kết được từ dự án này - Các mẫu thiết kế (patterns) đã chứng minh được độ tin cậy - Cách các kỹ sư giàu kinh nghiệm tư duy về những vấn đề này ### 8. Thẻ Tham khảo Nhanh (Quick Reference Card) Một bảng tra cứu tóm tắt ở cuối tài liệu: - Cách chạy dự án trên máy cục bộ (từng bước một, giả định máy chưa cài đặt gì) - Các URL quan trọng (production, staging, trang quản trị admin, bảng điều khiển) - Cần tìm ai / ở đâu khi có thứ gì đó bị hỏng - Các câu lệnh thường dùng nhất ## Quy tắc Viết — KHÔNG THỂ THƯƠNG LƯỢNG 1. **Không dùng biệt ngữ mà không giải thích.** Mọi thuật ngữ kỹ thuật đều phải đi kèm ngay một lời giải thích bằng ngôn ngữ đời thường hoặc một phép ẩn dụ trong lần đầu tiên xuất hiện. Bạn có thể sử dụng thuật ngữ kỹ thuật đó ở các đoạn sau, nhưng người đọc phải hiểu được nó trước đã. 2. **Tích cực sử dụng phép ẩn dụ.** Hãy so sánh các hệ thống với nhà hàng, bưu điện, thư viện, nhà máy, dàn nhạc giao hưởng — bất cứ thứ gì giúp khái niệm trở nên dễ hiểu ngay lập tức. Phép ẩn dụ phải NHẤT QUÁN trong phạm vi một phần (đừng đang ví von với nhà hàng lại nhảy sang bệnh viện ở giữa chừng lời giải thích). 3. **Kể câu chuyện TẠI SAO.** Đừng chỉ ghi chép lại những gì đang tồn tại. Hãy giải thích tại sao các quyết định lại được đưa ra, những phương án thay thế nào đã được cân nhắc, và những sự đánh đổi nào đã được chấp nhận. "Chúng ta chọn đi theo hướng X bởi vì Y, mặc dù điều đó có nghĩa là sau này chúng ta sẽ khó làm Z một cách dễ dàng." 4. **Viết thật cuốn hút.** Sử dụng giọng văn trò chuyện tự nhiên, các câu hỏi tu từ, chút hài hước nhẹ nhàng ở những chỗ phù hợp. Tài liệu này phải là thứ mà người ta thực sự MUỐN đọc, chứ không phải thứ họ bị ép phải đọc. Nếu một phần nào đó terdengar nhàm chán, hãy viết lại cho đến khi nó hết chán. 5. **Trung thực về các vấn đề.** Hãy gắn cờ chỉ rõ các khoản nợ kỹ thuật, các sự cố đã biết, và những quyết định kiểu "chúng ta làm thế này vì áp lực thời gian". Tài liệu này sẽ hữu ích hơn nhiều khi nó chân thực thay vì cố tỏ ra bóng bẩy hoàn hảo. 6. **Bao gồm mục "chuyện gì có thể trục trặc" cho mọi hệ thống chính.** Không phải để hù dọa, mà là để chuẩn bị sẵn sàng. "Nếu dịch vụ thanh toán bị sập, đây là những gì sẽ xảy ra và đây là những gì cần làm." 7. **Sử dụng kỹ thuật hé lộ thông tin tăng dần (progressive disclosure).** Bắt đầu mỗi phần bằng phiên bản đơn giản trước, sau đó mới đi sâu hơn. Người đọc có thể dừng lại ở bất kỳ điểm nào mà vẫn nắm được một lượng kiến thức hữu ích. 8. **Định dạng để dễ đọc lướt (scannability).** Sử dụng các tiêu đề, in đậm các thuật ngữ quan trọng, chia đoạn văn ngắn và dùng gạch đầu dòng cho các danh sách. Nhưng hãy viết bằng văn xuôi (không dùng gạch đầu dòng) đối với các phần giải thích và dẫn chuyện. ## Ví dụ về Giọng văn SAI — khô khan và nặng nề biệt ngữ: "Ứng dụng triển khai kết xuất phía máy chủ (server-side rendering) với cơ chế tái tạo tĩnh tăng dần (incremental static regeneration), tận dụng Next.js App Router cùng React Server Components để đạt chỉ số TTFB tối ưu." ĐÚNG — rõ ràng và lôi cuốn: "Khi có ai đó truy cập trang web của chúng ta, máy chủ sẽ dựng sẵn trang đó trước khi gửi đi — giống như một nhà hàng chuẩn bị sẵn món ăn trước khi bạn bước vào quán thay vì đợi bạn ngồi xuống rồi mới bắt đầu nấu từ đầu. Kỹ thuật này được gọi là 'kết xuất phía máy chủ' ('server-side rendering') và đó là lý do tại sao các trang web tải rất nhanh. Chúng ta sử dụng Next.js App Router cho việc này, nó giống như hệ thống điều phối quy trình làm việc của nhà bếp giúp quyết định món nào cần sơ chế trước và món nào sẽ nấu ngay khi có khách gọi." SAI — liệt kê trống không thiếu ngữ cảnh: "Các gói phụ thuộc: React 18, Next.js 14, Tailwind CSS, Supabase, Stripe" ĐÚNG — giải thích như một đội ngũ nhân sự: "Hãy hình dung ngăn xếp công nghệ (tech stack) của chúng ta như một đoàn làm phim, mỗi thành viên có một chuyên môn riêng: - **React** là nhà thiết kế bối cảnh — nó dựng nên mọi thứ bạn nhìn thấy trên màn hình - **Next.js** là quản lý sân khấu — nó điều phối thời điểm và cách thức mọi thứ xuất hiện - **Tailwind** là bộ phận phục trang — nó phụ trách toàn bộ phần tạo kiểu hình ảnh - **Supabase** là nhân viên lưu trữ hồ sơ — nó cất giữ và truy xuất toàn bộ dữ liệu của chúng ta - **Stripe** là nhân viên thu ngân — nó xử lý mọi vấn đề liên quan đến tiền bạc một cách an toàn"