feat: Standardize documentation filenames to use the same English names across all languages, removing separate Vietnamese filename conventions.

2026-01-18 23:17:45 +07:00
parent 0758095c7c
commit 497212c2df
1 changed files with 40 additions and 50 deletions
--- a/.agent/skills/documentation/SKILL.md
+++ b/.agent/skills/documentation/SKILL.md
@@ -53,66 +53,56 @@ services/my-service-net/
 ├── README.md                   # Service overview with links to EN/VI docs
 └── docs/
    ├── en/                     # English documentation
-    │   ├── README.md           # English intro, quick start, config
-    │   ├── ARCHITECTURE.md     # Architecture, layers, patterns
-    │   ├── API.md              # API reference (optional)
+    │   ├── README.md           # English content
+    │   ├── ARCHITECTURE.md     # English content
+    │   ├── API.md              # English content (optional)
    │   └── [OTHER].md          # Service-specific docs
-    └── vi/                     # Vietnamese documentation (mirror EN)
-        ├── gioi-thieu.md       # Vietnamese intro, quick start, config
-        ├── kien-truc.md        # Architecture, layers, patterns
-        ├── api.md              # API reference (optional)
-        └── [OTHER].md          # Service-specific docs
+    └── vi/                     # Vietnamese documentation (mirror EN structure)
+        ├── README.md           # Vietnamese content (same filename!)
+        ├── ARCHITECTURE.md     # Vietnamese content (same filename!)
+        ├── API.md              # Vietnamese content (same filename!)
+        └── [OTHER].md          # Service-specific docs (same filename!)
 ```

 **Key Rules:**
- `docs/en/` and `docs/vi/` MUST mirror each other (same files, same structure)
+- `docs/en/` and `docs/vi/` MUST mirror each other (same files, **same filenames**)
 - Each language folder is MONOLINGUAL (no bilingual mixing)
- **Filenames**: EN uses English (UPPERCASE), VI uses Vietnamese (kebab-case)
+- **Filenames**: Use **same English filenames** in both EN and VI folders
 - Service root `README.md` links to both EN/VI documentation
 - Mermaid diagrams MUST use dark color palette (see [Mermaid Diagrams Skill](../mermaid-diagrams/SKILL.md))
- `ARCHITECTURE.md`/`kien-truc.md` is MANDATORY, `README.md`/`gioi-thieu.md` is MANDATORY, other files optional
+- `ARCHITECTURE.md` and `README.md` are MANDATORY in both folders

-### Vietnamese Filename Conventions / Quy Ước Đặt Tên Tiếng Việt
+### Filename Conventions / Quy Ước Đặt Tên File

-**Standard EN/VI Filename Mapping:**
+**IMPORTANT**: Both `docs/en/` and `docs/vi/` use the **same English filenames**.

-| English (docs/en/) | Vietnamese (docs/vi/) | Description |
-|-------------------|----------------------|-------------|
-| `README.md` | `gioi-thieu.md` | Service introduction, quick start |
-| `ARCHITECTURE.md` | `kien-truc.md` | Architecture documentation |
-| `API.md` | `api.md` | API reference (technical term) |
-| `DEPLOYMENT.md` | `trien-khai.md` | Deployment guide |
-| `CONFIGURATION.md` | `cau-hinh.md` | Configuration guide |
-| `TESTING.md` | `kiem-thu.md` | Testing guide |
-| `TROUBLESHOOTING.md` | `khac-phuc-su-co.md` | Troubleshooting |
+**Standard Filenames (used in both EN and VI folders):**

-**Service-Specific Examples:**
+| Filename | Purpose / Mục đích |
+|----------|-------------------|
+| `README.md` | Service introduction, quick start / Giới thiệu dịch vụ, bắt đầu nhanh |
+| `ARCHITECTURE.md` | Architecture documentation / Tài liệu kiến trúc |
+| `API.md` | API reference / Tài liệu API |
+| `DEPLOYMENT.md` | Deployment guide / Hướng dẫn triển khai |
+| `CONFIGURATION.md` | Configuration guide / Hướng dẫn cấu hình |
+| `TESTING.md` | Testing guide / Hướng dẫn kiểm thử |
+| `TROUBLESHOOTING.md` | Troubleshooting / Khắc phục sự cố |
+| `WHATSAPP_SETUP.md` | WhatsApp setup / Cài đặt WhatsApp |
+| `AI_CHATBOT_GUIDE.md` | AI chatbot guide / Hướng dẫn chatbot AI |
+| `AUTOMATION_GUIDE.md` | Automation guide / Hướng dẫn tự động hóa |

-| Service Type | EN Filename | VI Filename |
-|-------------|------------|-------------|
-| WhatsApp | `WHATSAPP_SETUP.md` | `cai-dat-whatsapp.md` |
-| WhatsApp | `AI_CHATBOT_GUIDE.md` | `huong-dan-chatbot-ai.md` |
-| Facebook | `FACEBOOK_SETUP.md` | `cai-dat-facebook.md` |
-| Twitter/X | `TWITTER_SETUP.md` | `cai-dat-twitter.md` |
-| Zalo | `ZALO_SETUP.md` | `cai-dat-zalo.md` |
+**Naming Rules:**

-**Naming Rules for Vietnamese Files:**
+1. **UPPERCASE for main docs**: `README.md`, `ARCHITECTURE.md`, `API.md`
+2. **UPPERCASE_SNAKE_CASE for guides**: `WHATSAPP_SETUP.md`, `AI_CHATBOT_GUIDE.md`
+3. **Same filename in both folders**: Easy to find corresponding files
+4. **English only**: No encoding issues, better tool compatibility

-1. **Kebab-case**: All lowercase, words separated by hyphens (`-`)
-   - ✅ `kien-truc.md`, `huong-dan-chatbot-ai.md`
-   - ❌ `KIEN-TRUC.md`, `Kien_Truc.md`, `KienTruc.md`
-
-2. **Vietnamese without diacritics**: Use non-accented Vietnamese
-   - ✅ `kien-truc` (not `kiến-trúc`)
-   - ✅ `cau-hinh` (not `cấu-hình`)
-
-3. **Descriptive and clear**: Use full words, avoid abbreviations
-   - ✅ `huong-dan-chatbot-ai.md` (clear)
-   - ❌ `hd-chatbot.md` (abbreviated)
-
-4. **Technical terms**: Keep English for technical/API terms
-   - ✅ `api.md` (lowercase)
-   - ✅ `webhook.md`
+**Benefits:**
+- ✅ Easy to find corresponding files (same name in EN and VI)
+- ✅ Simple file management and linking
+- ✅ No encoding issues with special characters
+- ✅ Better compatibility with development tools

 ## Key Patterns / Mẫu Chính

@@ -145,9 +135,9 @@ docs/

 ## Quick Links

- 📖 [Architecture](docs/en/ARCHITECTURE.md) / [Kiến trúc](docs/vi/kien-truc.md)
- 🚀 [API Reference](docs/en/API.md) / [Tài liệu API](docs/vi/api.md)
- ⚙️ [Configuration](docs/en/README.md#configuration) / [Cấu hình](docs/vi/gioi-thieu.md#cấu-hình)
+- 📖 [Architecture](docs/en/ARCHITECTURE.md) / [Kiến trúc](docs/vi/ARCHITECTURE.md)
+- 🚀 [API Reference](docs/en/API.md) / [Tài liệu API](docs/vi/API.md)
+- ⚙️ [Configuration](docs/en/README.md#configuration) / [Cấu hình](docs/vi/README.md#configuration)

 ## Tech Stack

@@ -363,7 +353,7 @@ DATABASE_URL="postgresql://user:pass@localhost:5432/db"
 ### File Naming
 - Use kebab-case: `getting-started.md`
 - Be descriptive: `local-development.md` not `dev.md`
- Match EN and VI filenames (different conventions)
+- Same filenames in both EN and VI folders

 ### Heading Levels
 ```markdown