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

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
• IAM Architecture: iam-proposal.md
• System Design: system-design.md

2. Guide Template - 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
• Deployment to Kubernetes: deployment.md
• IAM Authentication Guide: iam-authentication.md

3. Skill/Pattern Template - 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
• Repository Pattern: repository-pattern.md
• Redis Caching: redis-caching.md
• Domain-Driven Design: 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

# 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)
• 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:

// 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 để 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

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

Validate Markdown

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

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

Link Format

# 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
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)