{
  "nodes": [
    {
      "parameters": {
        "url": "https://api.example.com/users",
        "method": "GET"
      },
      "name": "GET Users",
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 1,
      "position": [250, 300],
      "description": "## 📦 Lấy Danh Sách Người Dùng\n\n- **Mục đích:** Lấy danh sách người dùng từ API Ví Dụ.\n- **Tham số yêu cầu:**\n  - `url` – Điểm cuối API (đã được thiết lập).\n  - `method` – Phải là `GET`.\n- **Mẹo:** Thêm chuỗi truy vấn `?limit=100` để lấy tối đa 100 người dùng một lần.\n\n```

    js
// Ví dụ về đoạn phản hồi\n[{ \"id\": 1, \"name\": \"Alice\" }]\n

"
    }
  ]
}

Khi bạn di chuột qua node, mô tả sẽ được hiển thị như Markdown đã định dạng đẹp—không còn những dòng chữ khó hiểu nữa!

---

## 2️⃣ Tận Dụng Phần “Ghi Chú” Của Workflow – Kịch Bản

Mỗi workflow đều có một bảng **Ghi chú** (trên cùng bên phải → “Hiện Ghi chú”). Hãy coi đó như là *kịch bản* cho luồng hình ảnh của bạn.

### Những Gì Nên Có Trong Đây

|Phần|Tại Sao Nó Giúp|Ví Dụ|
|---|---|---|
|**Mục đích**|Tóm tắt nhanh về workflow.|`Tự động đồng bộ người dùng hàng ngày từ CRM → thông báo trên Slack.`|
|**Điều kiện tiên quyết**|Liệt kê các dịch vụ bên ngoài, khóa API, hoặc biến môi trường cần thiết.|`API_KEY phải được lưu trong thông tin xác thực n8n.`|
|**Các bước**|Phân tích vai trò của từng node bằng tiếng Anh đơn giản.|`1️⃣ Lấy người dùng → 2️⃣ Lọc những người hoạt động → 3️⃣ Đăng lên Slack.`|
|**Lịch sử phiên bản**|Theo dõi các thay đổi lớn mà không cần phải đào sâu vào Git.|`v1.2 – Thêm xử lý lỗi cho phản hồi 429.`|

#### Ví Dụ Ghi Chú (Markdown)

Bây giờ bất kỳ ai mở workflow đều có được cái nhìn tổng quan mà không cần phải cuộn qua canvas.

---

## 3️⃣ Tài Liệu Markdown Bên Ngoài + Node “Đọc Tệp” Của n8n – Giữ Tài Liệu DRY

Nếu bạn có **tài liệu lớn** (các thông số API, mô hình dữ liệu, sơ đồ), hãy giữ chúng trong một repo riêng và kéo chúng vào n8n khi cần.

### Cách Thực Hiện

1. **Tạo một thư mục `docs/`** trong repo của bạn và viết các tệp Markdown (`api.md`, `data-model.md`).
2. **Thêm một node “Đọc Tệp Nhị Phân”** (hoặc “Đọc Tệp Văn Bản”) để tải tệp tại thời gian chạy.
3. **Truyền nội dung** đến một node “Gửi Email” hoặc “Đăng lên Slack” để chia sẻ khi cần.

#### JSON Workflow Tối Thiểu

Bây giờ bạn có một **nguồn thông tin duy nhất**—cập nhật tệp Markdown, và mọi workflow kéo nó sẽ tự động cập nhật.

---

## 4️⃣ Kiểm Soát Phiên Bản Tài Liệu Của Bạn – Git + n8n = ❤️

Hãy coi các tệp JSON workflow của bạn trong n8n giống như bất kỳ tài liệu mã nào khác:

**Tại Sao?**

* **Lịch sử:** Xem ai đã thêm dòng tài liệu nào.
* **Hợp tác:** Các đánh giá PR có thể nhận xét về tài liệu giống như mã.
* **Khôi phục:** Xóa nhầm một mô tả? Kéo lại một commit cũ.

Mẹo: Thêm một **hook trước khi commit** để kiểm tra markdown (ví dụ: `markdownlint-cli`) để giữ phong cách nhất quán.

---

## 5️⃣ Mẹo & Thủ Thuật Nhanh 🎯

* **Giữ ngắn gọn** – Một câu mô tả + một “cách thực hiện” ngắn.
* **Sử dụng biểu tượng cảm xúc** có chừng mực để tạo điểm nhấn trực quan (`✅`, `⚠️`, `🔧`).
* **Liên kết đến tài liệu bên ngoài** với `[text](url)` để người đọc có thể khám phá sâu hơn.
* **Thêm bảng** cho ma trận tham số.
* **Đoạn mã** (\``js`) giúp các đoạn ví dụ dễ dàng sao chép và dán.
* **Từ khóa có thể tìm kiếm** – bao gồm các từ như “xử lý lỗi”, “giới hạn tần suất”, v.v.

### Danh Sách TL;DR

1. **Markdown trong mô tả node** – trợ giúp ngay trong canvas.
2. **Ghi chú workflow** – xương sống của câu chuyện.
3. **Tài liệu bên ngoài + Đọc Tệp** – giữ DRY.
4. **Kiểm soát phiên bản với Git** – coi tài liệu như mã.
5. **Phong cách nhất quán** – biểu tượng cảm xúc, bảng, liên kết, đoạn mã.

---

## 🎬 Kết Luận

Tài liệu tốt trong n8n không phải là một điều sau cùng; nó là một **thành phần quan trọng** giúp các tự động hóa của bạn có thể mở rộng, bảo trì, và (dám nói) *thú vị* để làm việc. Bằng cách sử dụng Markdown trong mô tả node, phát triển ghi chú workflow, kéo tài liệu bên ngoài, và kiểm soát phiên bản mọi thứ, bạn sẽ tiết kiệm được rất nhiều thời gian trong việc giải mã các workflow cũ và có nhiều thời gian hơn để xây dựng những cái mới thú vị.

**Điểm nhấn:** Tài liệu khi bạn xây dựng, không phải sau. Thói quen này sẽ trả lại ngay khi một đồng nghiệp (hoặc bạn trong tương lai) hỏi, “Node này làm gì?”

---

## 📣 Lời Kêu Gọi Hành Động

Bạn có mẹo tài liệu n8n yêu thích nào không? Hãy để lại bình luận bên dưới, chia sẻ ảnh chụp màn hình của workflow "được tài liệu hóa" nhất của bạn, hoặc mở một PR để thêm một mẫu tài liệu cho cộng đồng! Hãy cùng nhau làm cho tài liệu n8n trở nên huyền thoại. 🙌

---

### Tài Liệu Tham Khảo

* Tài liệu n8n – Mô tả Node & Hỗ Trợ Markdown
* Kiểm tra Markdown – `markdownlint-cli` trên GitHub
* Repo ví dụ: github.com/yourname/n8n-docs-template

Chúc bạn tự động hóa thành công! 🎉