# Template Usage Guide / Hướng dẫn Sử dụng Templates

## Overview / Tổng quan

**EN**: This guide explains how to use the documentation templates to maintain consistency across all documentation updates.

**VI**: Hướng dẫn này giải thích cách sử dụng các templates tài liệu để duy trì tính nhất quán trong tất cả các cập nhật tài liệu.

## Available Templates / Templates Có sẵn

| Template | Use For | File |
|----------|---------|------|
| **Architecture** | System design, component architecture | [`architecture-doc-template.md`](./architecture-doc-template.md) |
| **Guide** | Step-by-step howtos, tutorials | [`guide-doc-template.md`](./guide-doc-template.md) |
| **Skill/Pattern** | Design patterns, coding standards | [`skill-pattern-template.md`](./skill-pattern-template.md) |
| **Mermaid** | Diagram reference and examples | [`MERMAID_GUIDE.md`](./MERMAID_GUIDE.md) |

---

## Quick Start / Bắt đầu Nhanh

### 1. Choose the Right Template / Chọn Template Phù hợp

**Decision Tree / Cây Quyết định**:
```mermaid
flowchart TD
    Start{What are you<br/>documenting?} 
    Start -->|System design,<br/>components| Arch[Use Architecture<br/>Template]
    Start -->|How-to guide,<br/>setup steps| Guide[Use Guide<br/>Template]
    Start -->|Code pattern,<br/>best practice| Skill[Use Skill/Pattern<br/>Template]
    
    Arch --> Mermaid[Add Mermaid<br/>Diagrams]
    Guide --> Mermaid
    Skill --> Mermaid
    
    Mermaid --> Write[Write Bilingual<br/>Content]
    Write --> Review[Review & Test]
    
    style Start fill:#fff3cd
    style Mermaid fill:#e1f5ff
    style Write fill:#d4edda
    style Review fill:#f0e1ff
```

### 2. Copy Template / Sao chép Template

```bash
# EN: Copy appropriate template
# VI: Sao chép template phù hợp

# For Architecture docs
cp docs/templates/architecture-doc-template.md docs/en/architecture/your-doc.md
cp docs/templates/architecture-doc-template.md docs/vi/architecture/your-doc.md

# For Guides
cp docs/templates/guide-doc-template.md docs/en/guides/your-guide.md
cp docs/templates/guide-doc-template.md docs/vi/guides/your-guide.md

# For Skills
cp docs/templates/skill-pattern-template.md docs/en/skills/your-skill.md
cp docs/templates/skill-pattern-template.md docs/vi/skills/your-skill.md
```

### 3. Fill in Content / Điền Nội dung

Replace all placeholders:
- `[Architecture Name]` / `[Tên Kiến trúc]`
- `[Guide Title]` / `[Tiêu đề Hướng dẫn]`
- `[Pattern Name]` / `[Tên Pattern]`
- Code examples
- Mermaid diagrams

---

## Using Architecture Template / Sử dụng Architecture Template

### Sections to Complete / Sections Cần hoàn thành

#### 1. Overview Diagram
**EN**: Create a high-level diagram showing main components

**VI**: Tạo sơ đồ cấp cao cho thấy các thành phần chính

**Diagram Type**: Use `graph TD` or `C4Context`

**Example**:
```mermaid
graph TD
    A[Component A] --> B[Component B]
    B --> C[Component C]
```

#### 2. Architecture Description
**EN**: Explain purpose, goals, and design decisions

**VI**: Giải thích mục đích, mục tiêu và quyết định thiết kế

**Content to Include**:
- Purpose and goals / Mục đích và mục tiêu
- Key components / Thành phần chính
- Design decisions / Quyết định thiết kế
- Technology choices / Lựa chọn công nghệ
- Trade-offs / Đánh đổi

#### 3. Components Breakdown
**EN**: Detail each major component with:
- Description
- Key features
- Technologies used
- Code references (links to actual source)
- File location

**VI**: Chi tiết từng thành phần chính với:
- Mô tả
- Tính năng chính
- Công nghệ sử dụng
- Tham chiếu code (links tới source thực tế)
- Vị trí file

**Code Reference Format**:
```typescript
// EN: Example code showing implementation
// VI: Ví dụ code cho thấy cách triển khai
import { Component } from './component';
```

**File Link**: [`component.ts`](file:///absolute/path/to/component.ts)

#### 4. Data Flow Diagram
**Diagram Type**: Use `sequenceDiagram`

**Shows**: How data flows through the system

#### 5. Database Architecture (if applicable)
**Diagram Type**: Use `erDiagram`

**Shows**: Database schema and relationships

#### 6. Design Decisions
**Format**:
- **Context**: Why decision was needed
- **Decision**: What was decided
- **Consequences**: Impact (positive and negative)
- **Alternatives**: Other options considered

---

## Using Guide Template / Sử dụng Guide Template

### Sections to Complete / Sections Cần hoàn thành

#### 1. Workflow Diagram
**Diagram Type**: Use `flowchart LR` or `flowchart TD`

**Shows**: Overall workflow from start to finish

**Include**:
- Start/End nodes (rounded)
- Decision points (diamond)
- Action steps (rectangle)
- Error handling paths

#### 2. Prerequisites
**List**:
- Required software with versions
- Required knowledge
- Required access/credentials

**Include Quick Check**:
```bash
# Commands to verify prerequisites
node --version
docker --version
```

#### 3. Step-by-Step Instructions
**For Each Step**:
- Clear title
- Bilingual explanation
- Commands with comments
- Expected output
- Important notes
- File examples

**Format**:
```markdown
### Step 1: [Action]

**EN**: English explanation

**VI**: Giải thích tiếng Việt

\`\`\`bash
# EN: Command description
# VI: Mô tả lệnh
command-here
\`\`\`
```

#### 4. Verification
**Include**:
- Quick test commands
- Verification checklist
- Expected results

#### 5. Troubleshooting
**For Each Issue**:
- Symptoms (what you see)
- Solution (steps to fix)
- Bilingual for both

**Optional**: Add troubleshooting decision tree

---

## Using Skill/Pattern Template / Sử dụng Skill/Pattern Template

### Sections to Complete / Sections Cần hoàn thành

#### 1. Pattern Overview Diagram
**Diagram Type**: Use `graph LR` or `graph TD`

**Shows**: High-level pattern flow

#### 2. When to Use
**Include**:
- ✅ DO use for (scenarios)
- ❌ DON'T use for (anti-patterns)

#### 3. Implementation
**Provide**:
- Basic implementation (simple)
- Advanced implementation (with caching, error handling, etc.)
- Bilingual code comments

**Code Format**:
```typescript
/**
 * EN: Class description
 * VI: Mô tả class
 */
export class ExamplePattern {
  // EN: Implementation details
  // VI: Chi tiết triển khai
}
```

**Reference Actual Code**:
- Link to `_template` for basic patterns
- Link to `iam-service` for advanced patterns

**Example**:
```markdown
**Template**: [`feature.service.ts`](file:///Users/velikho/Desktop/WORKING/Base/services/_template/src/modules/feature/feature.service.ts)

**IAM**: [`rbac.service.ts`](file:///Users/velikho/Desktop/WORKING/Base/services/iam-service/src/modules/rbac/rbac.service.ts)
```

#### 4. Class Structure Diagram
**Diagram Type**: Use `classDiagram`

**Shows**: Class relationships, inheritance, dependencies

#### 5. Sequence Flow
**Diagram Type**: Use `sequenceDiagram`

**Shows**: Interaction between components

#### 6. Usage Examples
**Provide**:
- Example 1: Basic usage
- Example 2: Advanced usage
- Include setup, execution, and expected output

#### 7. Common Mistakes
**For Each Mistake**:
```markdown
#### Mistake 1: [Description]

\`\`\`typescript
// ❌ BAD: Incorrect implementation
bad code here
\`\`\`

\`\`\`typescript
// ✅ GOOD: Correct implementation
good code here
\`\`\`

**EN Why**: Explanation

**VI Tại sao**: Giải thích
```

#### 8. Unit Test Example
**Include**:
- Setup (before each)
- Test cases (happy path + error cases)
- Assertions

---

## Bilingual Content Guidelines / Hướng dẫn Nội dung Song ngữ

### Format Options / Tùy chọn Định dạng

#### Option 1: Side-by-side (for short content)
```markdown
> **EN**: Brief English description
> **VI**: Mô tả ngắn gọn tiếng Việt
```

#### Option 2: Separate sections (for detailed content)
```markdown
### EN: English Section

Detailed English content...

### VI: Phần Tiếng Việt

Nội dung chi tiết tiếng Việt...
```

#### Option 3: Inline (for code comments)
```typescript
// EN: English comment
// VI: Comment tiếng Việt
const example = 'value';
```

### Translation Consistency / Tính nhất quán Dịch thuật

**Common Technical Terms**:
| EN | VI |
|----|-----|
| Authentication | Xác thực |
| Authorization | Phân quyền |
| Deployment | Triển khai |
| Middleware | Middleware (giữ nguyên) |
| Repository | Repository (giữ nguyên) |
| Service | Service (giữ nguyên) |
| Controller | Controller (giữ nguyên) |
| Microservice | Microservice (giữ nguyên) |
| Cache | Cache (giữ nguyên) |
| Database | Database (giữ nguyên) |

**Note**: Some technical terms are kept in English for clarity and consistency with code.

---

## Adding Mermaid Diagrams / Thêm Sơ đồ Mermaid

### Step 1: Choose Diagram Type

Refer to [`MERMAID_GUIDE.md`](./MERMAID_GUIDE.md) for:
- Diagram type selection
- Syntax examples  
- Styling guidelines

### Step 2: Create Diagram

```markdown
\`\`\`mermaid
graph TD
    A[Start] --> B[Process]
    B --> C[End]
\`\`\`
```

### Step 3: Test Rendering

```bash
# Install mermaid-cli
npm install -g @mermaid-js/mermaid-cli

# Test render your doc
mmdc -i docs/en/your-doc.md -o test-output.svg

# Check for errors
echo $?  # 0 = success
```

### Step 4: Apply Consistent Styling

```mermaid
graph TD
    Start([Start]) --> Process[Process]
    Process --> End([End])
    
    style Start fill:#e1f5ff
    style End fill:#d4edda
    style Process fill:#f0e1ff
```

**Color Palette**:
- `#e1f5ff` - Blue (primary, start)
- `#d4edda` - Green (success, end)
- `#fff3cd` - Yellow (warning, decision)
- `#f8d7da` - Red (error)
- `#f0e1ff` - Purple (process)
- `#fff4e1` - Beige (data)

---

## Quality Checklist / Checklist Chất lượng

### Before Committing / Trước khi Commit

- [ ] **Content Complete**: All sections filled
- [ ] **Bilingual**: EN and VI content both complete
- [ ] **Mermaid Diagrams**: At least 2-3 diagrams
- [ ] **Diagrams Render**: Tested with mermaid-cli
- [ ] **Code Examples**: From actual source code
- [ ] **File Links**: All links valid (file:///)
- [ ] **Consistent Styling**: Colors and formatting consistent
- [ ] **No Placeholders**: All [brackets] replaced
- [ ] **Tested Commands**: All bash commands tested
- [ ] **Grammar Check**: Both EN and VI proofread
- [ ] **Cross-references**: Links to related docs work
- [ ] **Metadata**: Last updated date, author filled

### EN/VI Parity Check

```bash
# Compare line counts (should be similar)
wc -l docs/en/your-doc.md
wc -l docs/vi/your-doc.md

# Compare diagram counts
grep -c '```mermaid' docs/en/your-doc.md
grep -c '```mermaid' docs/vi/your-doc.md
```

---

## Examples / Ví dụ

### Good Example: Kubernetes Local Guide

**File**: [`docs/vi/guides/kubernetes-local.md`](../vi/guides/kubernetes-local.md)

**Why it's good**:
- ✅ Clear workflow diagram
- ✅ Step-by-step instructions
- ✅ Bilingual content
- ✅ Verification steps
- ✅ Troubleshooting section
- ✅ Tested commands

### Good Example: IAM Service README

**File**: [`services/iam-service/README.md`](../../services/iam-service/README.md)

**Why it's good**:
- ✅ Comprehensive architecture diagrams
- ✅ Clear API documentation
- ✅ Real code examples
- ✅ Well-organized sections
- ✅ Quick reference tables

---

## Getting Help / Nhận Trợ giúp

### Questions / Câu hỏi

1. **Which template to use?** → See decision tree above
2. **How to create diagrams?** → See `MERMAID_GUIDE.md`
3. **How to structure bilingual content?** → See "Bilingual Content Guidelines"
4. **Where to find code examples?** → Look in `_template` or `iam-service`

### Resources / Tài nguyên

- [Mermaid Guide](./MERMAID_GUIDE.md) - Diagram reference
- [Architecture Template](./architecture-doc-template.md) - Template file
- [Guide Template](./guide-doc-template.md) - Template file
- [Skill Template](./skill-pattern-template.md) - Template file

---

**Last Updated**: 2026-01-07  
**Maintained by**: VelikHo ([@hongochai10](https://github.com/hongochai10))