---
description: Workflows chỉnh sửa và cập nhật docs của microservices theo chuẩn EN/VI
---

# Workflow: Microservices Documentation Update

## Mục Đích / Purpose

Workflow này giúp Agent cập nhật và duy trì documentation của microservices theo cấu trúc chuẩn:
```
docs/
  en/
    ARCHITECTURE.md
    README.md
    API.md (optional)
    ... (other docs)
  vi/
    ARCHITECTURE.md
    README.md
    API.md (optional)
    ... (other docs)
README.md (service root)
```

## Khi Nào Sử Dụng / When to Use

- Tạo mới hoặc cập nhật documentation cho microservices
- Tách bilingual docs thành separate EN/VI files
- Đảm bảo docs đồng bộ giữa EN và VI versions
- Chuẩn hóa Mermaid diagrams và color palettes

---

## ⚠️ AGENT EXECUTION GUIDELINES (CRITICAL)

> **Đọc phần này TRƯỚC KHI thực thi workflow!**

### Quy Trình Thực Thi Đúng

**LUÔN tuân theo các bước sau theo thứ tự:**

1. **Đọc TOÀN BỘ workflow specification** từ đầu đến cuối
2. **Kiểm tra current state** của service documentation
3. **So sánh current state với workflow requirements** (đặc biệt chú ý Bước 2 về filename convention)
4. **Xác định gaps/issues dựa trên workflow** - KHÔNG dựa trên assumption hay kinh nghiệm từ project khác
5. **Thực hiện changes** theo đúng workflow specification
6. **Validate theo workflow checklist** (Bước 7)

### ❌ Common Mistakes to Avoid

**Mistake #1: Không đọc kỹ workflow trước khi thực thi**
- ❌ BAD: Thấy files `KIEN-TRUC.md` → Giả định sai → Đổi tên thành `kien-truc.md`
- ✅ GOOD: Đọc Bước 2 → Thấy "cùng tên file tiếng Anh" → Giữ nguyên `ARCHITECTURE.md`

**Mistake #2: Dựa vào assumptions từ các workflows/projects khác**
- ❌ BAD: "Tôi nghĩ Vietnamese files nên dùng Vietnamese filenames"
- ✅ GOOD: "Workflow nói rõ: Both EN/VI use SAME English filenames"

**Mistake #3: Bỏ qua validation checklist**
- ❌ BAD: Làm xong → Notify user ngay
- ✅ GOOD: Làm xong → Check Bước 7 → Đảm bảo đúng spec → Notify user

### ✅ Pre-Flight Checklist

Trước khi bắt đầu thực thi, hãy xác nhận:

- [ ] Đã đọc toàn bộ workflow specification?
- [ ] Đã hiểu rõ filename convention ở Bước 2?
- [ ] Đã kiểm tra current state của documentation?
- [ ] Đã so sánh current state với workflow requirements?
- [ ] Đã xác định chính xác những gì CẦN thay đổi (không phải GIẢ ĐỊNH)?

**Nếu có bất kỳ câu trả lời "No" nào → Quay lại đọc workflow!**

---

## Bước 1: Xác Định Cấu Trúc Hiện Tại / Identify Current Structure

**Actions:**
1. Kiểm tra cấu trúc `docs/` folder của service
2. Xác định xem có bilingual files hay đã tách riêng EN/VI
3. List tất cả các files cần xử lý

**Expected Output:**
- Danh sách files hiện tại
- Xác định files nào cần tách/cập nhật

---

## Bước 2: Tạo Cấu Trúc Thư Mục Chuẩn / Create Standard Structure

**Actions:**
1. Tạo `docs/en/` nếu chưa có
2. Tạo `docs/vi/` nếu chưa có
3. Đảm bảo có `README.md` tại service root
4. **Sử dụng cùng tên file tiếng Anh cho cả EN và VI**

**Commands:**
```bash
mkdir -p docs/en docs/vi
```

**IMPORTANT - Filename Convention:**
- ✅ Cả `docs/en/` và `docs/vi/` dùng **CÙNG tên file tiếng Anh**
- ✅ Ví dụ: `ARCHITECTURE.md`, `README.md`, `API.md` trong cả 2 folders
- ✅ Lợi ích: Dễ tìm file tương ứng, không cần nhớ 2 bộ tên khác nhau

**Example Structure:**
```
docs/
├── en/
│   ├── README.md           # English content
│   ├── ARCHITECTURE.md     # English content
│   └── API.md              # English content
└── vi/
    ├── README.md           # Vietnamese content (same filename!)
    ├── ARCHITECTURE.md     # Vietnamese content (same filename!)
    └── API.md              # Vietnamese content (same filename!)
```


---

## Bước 3: Tách Nội Dung EN/VI / Separate EN/VI Content

### 3.1 Xử Lý Bilingual Files (Nếu Có)

**Pattern 1: Side-by-side format**
```markdown
# Title / Tiêu Đề
Description in English.
Mô tả bằng tiếng Việt.
```
→ Split into separate files

**Pattern 2: Sections format**
```markdown
# English Section
...
---
# Phần Tiếng Việt
...
```
→ Extract each section to corresponding file

**Pattern 3: Comments**
```markdown
# EN: English comment
# VI: Vietnamese comment
```
→ Remove VI comments from EN files, EN comments from VI files

### 3.2 Làm Sạch Nội Dung / Clean Content

**For EN files:**
- ✅ Keep: `# EN:` comments (optional)
- ❌ Remove: `# VI:` comments
- ❌ Remove: Vietnamese inline translations (after slashes)
- ❌ Remove: `> **Lưu ý**:` Vietnamese notes

**For VI files:**
- ✅ Keep: `# VI:` comments (optional)
- ❌ Remove: `# EN:` comments
- ❌ Remove: English inline translations
- ❌ Remove: `> **Note**:` English notes

**Example:**
```markdown
❌ BAD (in EN file):
## Configuration / Cấu Hình
> **Note**: This is important
> **Lưu ý**: Điều này rất quan trọng

✅ GOOD (in EN file):
## Configuration
> **Note**: This is important

✅ GOOD (in VI file):
## Cấu Hình
> **Lưu ý**: Điều này rất quan trọng
```

---

## Bước 4: Chuẩn Hóa Mermaid Diagrams / Standardize Mermaid Diagrams

### 4.1 Syntax Check

**Common Issues Checklist:**
- [ ] Có xuống dòng sau `flowchart TD` / `graph TD`?
- [ ] Arrow sử dụng `--&gt;` không phải `-&gt;`?
- [ ] Không có Node ID trùng lặp?
- [ ] Labels có ký tự đặc biệt được quote? `["Label (with parens)"]`
- [ ] Subgraph format: `subgraph ID["Label"]`?

### 4.2 Apply Dark Color Palette

**LUÔN sử dụng bảng màu tối:**

| Node Type | Fill Color | Border | Stroke Width |
|-----------|-----------|--------|--------------|
| **Start** | `#2C3E50` | `#34495E` | `3px` |
| **End/Success** | `#27AE60` | `#229954` | `3px` |
| **Decision** | `#E67E22` | `#D35400` | `2px` |
| **Error** | `#C0392B` | `#A93226` | `2px` |
| **Process** | `#8E44AD` | `#7D3C98` | `2px` |
| **Database/Cache** | `#34495E` | `#2C3E50` | `2px` |
| **Gateway/API** | `#3498DB` | `#2980B9` | `3px` |
| **Neutral** | `#7F8C8D` | `#5D6D7E` | `2px` |

**Text Color:** `#ECF0F1` (light text cho contrast)

**Style Template:**
```mermaid
style NodeName fill:#2C3E50,color:#ECF0F1,stroke:#34495E,stroke-width:3px
```

### 4.3 Example: Before/After

**❌ BEFORE (no styling):**
```mermaid
graph TD
    A[Start] --> B[Process]
    B --> C{Decision}
    C -->|Yes| D[Success]
    C -->|No| E[Error]
```

**✅ AFTER (with dark palette):**
```mermaid
graph TD
    A[Start] --> B[Process]
    B --> C{Decision}
    C -->|Yes| D[Success]
    C -->|No| E[Error]
    
    style A fill:#2C3E50,color:#ECF0F1,stroke:#34495E,stroke-width:3px
    style B fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
    style C fill:#E67E22,color:#ECF0F1,stroke:#D35400,stroke-width:2px
    style D fill:#27AE60,color:#ECF0F1,stroke:#229954,stroke-width:3px
    style E fill:#C0392B,color:#ECF0F1,stroke:#A93226,stroke-width:2px
```

### 4.4 Visual Indicators (Optional)

Có thể thêm emoji cho clarity:
- 🚀 Start/Launch
- ✅ Success/Done
- ❌ Error/Failed
- ⚠️ Warning/Decision
- 🔐 Security/Auth
- 💾 Database
- ⚙️ Processing
- 🌐 API/Network

---

## Bước 5: Đảm Bảo Đồng Bộ EN/VI / Ensure EN/VI Consistency

**Checklist:**
- [ ] Cả EN và VI đều có cùng sections (headings)
- [ ] Mermaid diagrams có cùng structure (chỉ khác labels)
- [ ] Code examples giống nhau (chỉ khác comments)
- [ ] File names khớp: `en/ARCHITECTURE.md` ↔ `vi/ARCHITECTURE.md`

**EN Diagram Example:**
```mermaid
graph TD
    A[Request] --> B{Valid?}
    B -->|Yes| C[Process]
    B -->|No| D[Error]
```

**VI Diagram Example (same structure, Vietnamese labels):**
```mermaid
graph TD
    A[Yêu cầu] --> B{Hợp lệ?}
    B -->|Có| C[Xử lý]
    B -->|Không| D[Lỗi]
```

---

## Bước 6: Cập Nhật Service Root README / Update Service README

Service root `README.md` phải link đến EN/VI docs:

**Template:**
```markdown
# Service Name

> **EN**: [English Documentation](docs/en/README.md)  
> **VI**: [Tài liệu Tiếng Việt](docs/vi/README.md)

## Quick Links

- 📖 [Architecture Documentation](docs/en/ARCHITECTURE.md) / [Tài liệu Kiến trúc](docs/vi/ARCHITECTURE.md)
- 🚀 [Quick Start](docs/en/README.md#quick-start)
- 🔧 [Configuration](docs/en/README.md#configuration)

## Tech Stack

- .NET 8
- PostgreSQL
- Redis
- RabbitMQ

## Development

\`\`\`bash
dotnet build
dotnet run
\`\`\`

See detailed documentation in [docs/en/](docs/en/) or [docs/vi/](docs/vi/).
```

---

## Bước 7: Validation / Kiểm Tra Chất Lượng

### 7.1 Content Checklist

**For each EN file:**
- [ ] No Vietnamese text (except code comments if needed)
- [ ] No bilingual patterns (`Text / Chữ`)
- [ ] All Mermaid diagrams have dark color palette
- [ ] No syntax errors in Mermaid
- [ ] Links work correctly

**For each VI file:**
- [ ] No English text (except technical terms)
- [ ] No bilingual patterns
- [ ] All Mermaid diagrams have dark color palette
- [ ] Mermaid structure matches EN version
- [ ] Links work correctly

### 7.2 Structure Checklist

- [ ] `docs/en/` exists with all required files
- [ ] `docs/vi/` exists with mirror files (same count)
- [ ] Service root `README.md` links to both EN/VI
- [ ] **Both EN and VI folders use SAME English filenames** (e.g., `ARCHITECTURE.md` in both)
- [ ] File count matches between EN/VI directories (e.g., 4 files in EN = 4 files in VI)

### 7.3 Filename Convention Validation

**✅ CORRECT Convention (as per Bước 2):**

Both `docs/en/` and `docs/vi/` use **SAME English filenames**:

```bash
docs/en/ARCHITECTURE.md   ↔ docs/vi/ARCHITECTURE.md  ✅
docs/en/API.md            ↔ docs/vi/API.md           ✅
docs/en/README.md         ↔ docs/vi/README.md        ✅
docs/en/TWITTER_SETUP.md  ↔ docs/vi/TWITTER_SETUP.md ✅
```

**❌ INCORRECT (Common mistakes):**

```bash
# Mistake 1: Using Vietnamese filenames in VI folder
docs/en/ARCHITECTURE.md   ↔ docs/vi/kien-truc.md     ❌ WRONG!
docs/en/TWITTER_SETUP.md  ↔ docs/vi/cai-dat-twitter.md ❌ WRONG!

# Mistake 2: Case inconsistency
docs/en/ARCHITECTURE.md   ↔ docs/vi/architecture.md  ❌ WRONG!

# Correct approach
docs/en/ARCHITECTURE.md   ↔ docs/vi/ARCHITECTURE.md  ✅ CORRECT!
```

**Why this convention?**
- ✅ Easier to find corresponding files
- ✅ No need to remember two naming schemes
- ✅ Better cross-reference in documentation
- ✅ Simpler maintenance

### 7.4 Mermaid Validation

```bash
# Optional: validate Mermaid syntax using mermaid-cli
mmdc -i docs/en/ARCHITECTURE.md -o /tmp/test.svg
```

---

## Resources / Tài Nguyên

**Related Skills:**
- [Documentation Skill](../.agent/skills/documentation/SKILL.md) - Documentation guidelines
- [Mermaid Diagrams Skill](../.agent/skills/mermaid-diagrams/SKILL.md) - Diagram patterns
- [Skill Authoring](../.agent/skills/skill-authoring/SKILL.md) - How to write skills

**Tools:**
- [Mermaid Live Editor](https://mermaid.live/) - Test diagrams
- [Mermaid Documentation](https://mermaid.js.org/)

---

## Example: Complete Workflow Execution

```bash
# 1. Create structure
mkdir -p services/my-service-net/docs/{en,vi}

# 2. Split bilingual ARCHITECTURE.md into EN/VI
# (Agent processes content, removes cross-language text)

# 3. Apply Mermaid formatting
# (Agent adds dark color palette to all diagrams)

# 4. Update root README.md
# (Agent creates bilingual link structure)

# 5. Validate
# Check all files exist, links work, diagrams render
```

**Result:**
```
services/my-service-net/
├── README.md               (links to docs/en and docs/vi)
└── docs/
    ├── en/
    │   ├── README.md        (English content)
    │   ├── ARCHITECTURE.md  (English content)
    │   └── API.md           (English content)
    └── vi/
        ├── README.md        (Vietnamese content, same filename!)
        ├── ARCHITECTURE.md  (Vietnamese content, same filename!)
        └── API.md           (Vietnamese content, same filename!)
```

---

## Quick Tips / Mẹo Nhanh

### Mermaid Common Issues
- Missing line break after `flowchart TD` → Add newline
- Single dash in arrow `-&gt;` → Change to `--&gt;`
- Duplicate node IDs → Rename nodes (A, B, C, etc.)
- Missing quotes on special chars → Wrap in `["label"]`

### Color Pattern Quick Reference
```markdown
🟦 Start = #2C3E50 / #34495E
🟩 Success = #27AE60 / #229954  
🟧 Decision = #E67E22 / #D35400
🟥 Error = #C0392B / #A93226
🟪 Process = #8E44AD / #7D3C98
⬛ Database = #34495E / #2C3E50
🔷 API = #3498DB / #2980B9
```

### Visual Indicators
- Use emojis consistently: 🚀 ✅ ❌ ⚠️ 🔐 💾 ⚙️ 🌐
- Dark palette mandatory for all diagrams
- Light text color `#ECF0F1` for contrast