diff --git a/.agent/skills/documentation/SKILL.md b/.agent/skills/documentation/SKILL.md index 39aa5a2a..b2f0b7f2 100644 --- 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