pos-system/docs/vi/templates/index.md

# Hướng dẫn Sử dụng Templates Tài liệu

> **Mục đích**: Hướng dẫn sử dụng các templates tài liệu để tạo documentation nhất quán cho project

## Templates Có sẵn

### 1. Architecture Template - [`architecture.md`](./architecture.md)

**Sử dụng khi**: Tài liệu hóa kiến trúc hệ thống, thành phần, hoặc design decision

**Bao gồm**:
- Sơ đồ tổng quan (Mermaid diagrams)
- Mô tả thành phần chi tiết
- Quyết định thiết kế
- Database architecture
- Performance characteristics
- Security considerations
- Deployment strategy

**Ví dụ**: 
- Storage Service Architecture: [`storage-architecture.md`](../architecture/storage-architecture.md)
- IAM Architecture: [`iam-proposal.md`](../architecture/iam-proposal.md)
- System Design: [`system-design.md`](../architecture/system-design.md)

### 2. Guide Template - [`guide.md`](./guide.md)

**Sử dụng khi**: Tạo hướng dẫn từng bước (getting started, deployment, troubleshooting)

**Bao gồm**:
- Workflow diagram
- Prerequisites
- Hướng dẫn từng bước chi tiết
- Verification steps
- Common issues & troubleshooting
- FAQ section

**Ví dụ**: 
- Local Development: [`local-development.md`](../guides/local-development.md)
- Deployment to Kubernetes: [`deployment.md`](../guides/deployment.md)
- IAM Authentication Guide: [`iam-authentication.md`](../guides/iam-authentication.md)

### 3. Skill/Pattern Template - [`skill-pattern.md`](./skill-pattern.md)

**Sử dụng khi**: Tài liệu hóa coding patterns, best practices, hoặc kỹ thuật

**Bao gồm**:
- Pattern overview
- When to use / when not to use
- Implementation examples
- Class diagrams
- Best practices
- Common mistakes
- Testing examples

**Ví dụ**: 
- CQRS with MediatR: [`cqrs-mediatr.md`](../skills/cqrs-mediatr.md)
- Repository Pattern: [`repository-pattern.md`](../skills/repository-pattern.md)
- Redis Caching: [`redis-caching.md`](../skills/redis-caching.md)
- Domain-Driven Design: [`domain-driven-design.md`](../skills/domain-driven-design.md)

## Quick Start

### Bước 1: Chọn Template phù hợp

Xác định loại tài liệu bạn cần tạo:
- **Kiến trúc** → `architecture.md`
- **Hướng dẫn** → `guide.md`
- **Pattern/Skill** → `skill-pattern.md`

### Bước 2: Copy Template

```bash
# Ví dụ: Tạo architecture document mới
cp docs/vi/templates/architecture.md docs/vi/architecture/new-architecture-name.md

# Ví dụ: Tạo guide document mới
cp docs/vi/templates/guide.md docs/vi/guides/new-guide-name.md

# Ví dụ: Tạo skill document mới
cp docs/vi/templates/skill-pattern.md docs/vi/skills/new-skill-name.md
```

### Bước 3: Thay thế Placeholders

Thay thế các placeholder trong template:
- `[Tên Kiến trúc]` → Tên thực của document
- `[Tiêu đề]` → Tiêu đề sections
- `[Mô tả]` → Nội dung thực tế

### Bước 4: Tùy chỉnh Nội dung

- Điền vào tất cả sections
- Tạo Mermaid diagrams (xem [mermaid-guide.md](./mermaid-guide.md))
- Thêm code examples với comments song ngữ
- Cập nhật metadata (Last Updated, Authors)

### Bước 5: Review Checklist

- [ ] Tất cả placeholders đã được thay thế
- [ ] Mermaid diagrams hiển thị đúng
- [ ] Code examples có syntax highlighting
- [ ] Có đầy đủ nội dung tiếng Việt
- [ ] Links hoạt động chính xác
- [ ] Metadata được cập nhật

## Quy ước Viết Tài liệu

### Ngôn ngữ

**Tiếng Việt**: 
- Sử dụng 100% tiếng Việt cho tất cả nội dung
- Giữ thuật ngữ kỹ thuật bằng tiếng Anh khi cần (Docker, Kubernetes, etc.)
- Code examples vẫn giữ nguyên tiếng Anh

**Code Comments**:
```typescript
// Ví dụ code với comments tiếng Việt
export class Example {
  /**
   * Khởi tạo service với dependencies
   */
  constructor(private dependency: Dependency) {}
}
```

### Mermaid Diagrams

Tham khảo [Hướng dẫn Mermaid](./mermaid-guide.md) để biết:
- Các loại diagrams có sẵn
- Color scheme chuẩn
- Best practices
- Ví dụ cho mỗi loại diagram

**Color Palette**:
```
#4A90E2 - Xanh dương (Primary actions)
#F5A623 - Cam vàng (Data/Cache)
#9013FE - Tím (Processing)
#50E3C2 - Xanh lá (Success)
#E74C3C - Đỏ (Errors)
#F39C12 - Vàng cam (Warnings)
#7B68EE - Tím xanh (Info)
#95A5A6 - Xám (Neutral)
```

### File Organization

```
docs/vi/
├── templates/           # Templates (file này)
├── architecture/        # Architecture docs
├── guides/             # How-to guides
└── skills/             # Patterns & skills
```

## Thực hành Tốt nhất

### 1. Viết Ngắn gọn và Rõ ràng

- Ngắn gọn, súc tích
- Một ý chính mỗi paragraph
- Sử dụng bullet points cho lists

### 2. Ưu tiên Hình ảnh

- Thêm diagrams cho mọi concepts phức tạp
- Sử dụng code examples với output
- Screenshots khi cần (UI, browser)

### 3. Khả năng Bảo trì

- Link tới related documentation
- Cập nhật "Last Updated" date
- Ghi rõ version nếu có

### 4. Khả năng Truy cập

- Alt text cho images
- Descriptive link text (không dùng "click here")
- Headings có cấu trúc logic

## Mẹo Hữu ích

### Tạo Diagrams nhanh

```bash
# Sử dụng Mermaid Live Editor
# https://mermaid.live/
```

### Validate Markdown

```bash
# Cài đặt markdownlint
pnpm add -g markdownlint-cli

# Check markdown files
markdownlint docs/vi/**/*.md
```

### Link Format

```markdown
# Relative links (ưu tiên)
[Architecture](../architecture/system-design.md)

# Với line numbers (file links)
[Code Example](file:///path/to/file.ts#L10-L20)
```

## Khắc phục Sự cố

### Mermaid không hiển thị?

1. Kiểm tra syntax với [Mermaid Live Editor](https://mermaid.live/)
2. Đảm bảo code block có `mermaid` language tag
3. Không có ký tự đặc biệt chưa escape

---

**Tác giả**: VelikHo (hongochai10@icloud.com)