pos-system/docs/vi/skills/documentation.md

Tài Liệu

Guidelines for writing technical documentation in the GoodGo project. Use when creating or updating README files, guides, architecture docs, or API documentation. Ensures bilingual (EN/VI) consistency and proper structure.

Hướng dẫn viết tài liệu kỹ thuật trong dự án GoodGo. Sử dụng khi tạo hoặc cập nhật file README, hướng dẫn, tài liệu kiến trúc hoặc tài liệu API. Đảm bảo tính nhất quán song ngữ (EN/VI) và cấu trúc phù hợp.

Tổng Quan

The Documentation skill provides comprehensive guidelines for writing, structuring, and maintaining technical documentation in the GoodGo Microservices Platform. It covers documentation structure, bilingual formatting, templates, writing style, and best practices for maintaining documentation quality.

Skill Documentation cung cấp hướng dẫn toàn diện để viết, cấu trúc và duy trì tài liệu kỹ thuật trong GoodGo Microservices Platform. Nó bao gồm cấu trúc tài liệu, định dạng song ngữ, template, phong cách viết và thực hành tốt nhất để duy trì chất lượng tài liệu.

Khi Nào Sử Dụng

Use this skill when:

• Creating new documentation files
• Updating existing documentation
• Writing README files for services or packages
• Creating guides or tutorials
• Documenting API endpoints
• Writing architecture documentation
• Creating deployment documentation
• Writing runbooks or operational guides
• Ensuring bilingual consistency

Sử dụng skill này khi:

• Tạo file tài liệu mới
• Cập nhật tài liệu hiện có
• Viết file README cho services hoặc packages
• Tạo hướng dẫn hoặc tutorial
• Tài liệu hóa API endpoints
• Viết tài liệu kiến trúc
• Tạo tài liệu triển khai
• Viết runbook hoặc hướng dẫn vận hành
• Đảm bảo tính nhất quán song ngữ

Khái Niệm Chính

Cấu Trúc Tài Liệu

The project follows a structured documentation hierarchy:

docs/
├── en/                          # English documentation
│   ├── guides/                  # How-to guides
│   ├── architecture/            # System design docs
│   ├── api/                     # API documentation
│   ├── onboarding/              # New developer guides
│   ├── runbooks/                # Operational guides
│   └── skills/                  # Skill documentation
├── vi/                          # Vietnamese documentation (mirror structure)
└── README.md                    # Documentation index

Dự án tuân theo hệ thống phân cấp tài liệu có cấu trúc:

docs/
├── en/                          # Tài liệu tiếng Anh
│   ├── guides/                  # Hướng dẫn cách làm
│   ├── architecture/            # Tài liệu thiết kế hệ thống
│   ├── api/                     # Tài liệu API
│   ├── onboarding/              # Hướng dẫn cho developer mới
│   ├── runbooks/                # Hướng dẫn vận hành
│   └── skills/                  # Tài liệu skills
├── vi/                          # Tài liệu tiếng Việt (cấu trúc tương tự)
└── README.md                    # Mục lục tài liệu

Quy Tắc Tài Liệu Song Ngữ

The project maintains bilingual documentation (English and Vietnamese). Three formats are used:

1. Side-by-side: Short content with EN and VI on the same line
2. Separate files: Long content in separate EN and VI files
3. Sections: Mixed content with separate EN and VI sections

Dự án duy trì tài liệu song ngữ (Tiếng Anh và Tiếng Việt). Ba định dạng được sử dụng:

1. Side-by-side: Nội dung ngắn với EN và VI trên cùng một dòng
2. Separate files: Nội dung dài trong các file EN và VI riêng biệt
3. Sections: Nội dung hỗn hợp với các phần EN và VI riêng biệt

Các Pattern Thường Dùng

Template README Service

Example structure from services/iam-service/README.md:

# Tên Dịch Vụ

Brief description in English
> Mô tả ngắn gọn bằng tiếng Việt

## Tính Năng

- Feature 1 / Tính năng 1
- Feature 2 / Tính năng 2

## Yêu Cầu

- Node.js 20+
- PostgreSQL (Neon)
- Redis

## Bắt Đầu Nhanh

```bash
# Cài đặt dependencies
pnpm install

# Thiết lập môi trường
cp .env.example .env

# Khởi động service
pnpm dev

Cấu Hình

Variable	Description / Mô Tả	Default	Required
PORT	Server port / Cổng server	5000	No

API Endpoints

See API Documentation

Ví dụ cấu trúc từ `services/iam-service/README.md`:

```markdown
# Tên Dịch Vụ

Brief description in English
> Mô tả ngắn gọn bằng tiếng Việt

## Tính Năng

- Feature 1 / Tính năng 1
- Feature 2 / Tính năng 2

## Yêu Cầu

- Node.js 20+
- PostgreSQL (Neon)
- Redis

## Bắt Đầu Nhanh

```bash
# Cài đặt dependencies
pnpm install

# Thiết lập môi trường
cp .env.example .env

# Khởi động service
pnpm dev

Cấu Hình

Variable	Description / Mô Tả	Default	Required
PORT	Server port / Cổng server	5000	No

API Endpoints

See API Documentation

### Template Hướng Dẫn

Example from `docs/en/guides/getting-started.md`:

```markdown
# Getting Started

## Prerequisites

- Node.js >= 20.0.0
- PNPM >= 8.0.0
- Docker & Docker Compose
- Git
- Neon account (https://neon.tech) - for database

## Initial Setup

1. **Clone the repository**
   ```bash
   git clone <repository-url>
   cd Base

2. Setup Neon Database

   # Run setup script
   ./scripts/db/setup-neon.sh
   

   See Neon Setup Guide for details.

3. Initialize the project

   ./scripts/setup/init-project.sh
   

Next Steps

• Read Development Guide
• Check API Documentation
• Review Architecture Overview

Ví dụ từ `docs/vi/guides/getting-started.md`:

```markdown
# Bắt Đầu

## Yêu Cầu

- Node.js >= 20.0.0
- PNPM >= 8.0.0
- Docker & Docker Compose
- Git
- Tài khoản Neon (https://neon.tech) - cho database

## Thiết Lập Ban Đầu

1. **Clone repository**
   ```bash
   git clone <repository-url>
   cd Base

2. Thiết lập Neon Database

   # Chạy script setup
   ./scripts/db/setup-neon.sh
   

   Xem Hướng Dẫn Thiết Lập Neon để biết chi tiết.

3. Khởi tạo dự án

   ./scripts/setup/init-project.sh
   

Bước Tiếp Theo

• Đọc Hướng Dẫn Phát Triển
• Xem Tài Liệu API
• Xem lại Tổng Quan Kiến Trúc

### Template Tài Liệu Kiến Trúc

Example from `docs/en/architecture/system-design.md`:

```markdown
# System Design

## Overview

GoodGo Microservices Platform is built using a microservices architecture pattern with the following principles:

- **Service Independence**: Each service has its own database and can be deployed independently
- **API Gateway**: Traefik handles routing, load balancing, and cross-cutting concerns
- **Shared Libraries**: Common functionality is extracted into shared packages
- **Infrastructure as Code**: All infrastructure configurations are versioned
- **Observability**: Full monitoring, logging, and tracing capabilities

## Architecture Diagram

┌─────────────┐ ┌─────────────┐ │ Web App │ │ Mobile App │ │ (Next.js) │ │ (React Native) └──────┬──────┘ └──────┬──────┘ │ │ └──────────┬────────┘ │ ┌────────▼────────┐ │ Traefik │ │ (API Gateway) │ └────────┬─────────┘

## Components

### Frontend Layer
- **Web App**: Next.js application with App Router
- **Mobile App**: React Native application

### API Gateway
- **Traefik**: Reverse proxy, load balancer, SSL termination

Ví dụ từ docs/vi/architecture/system-design.md:

# Thiết Kế Hệ Thống

## Tổng Quan

GoodGo Microservices Platform được xây dựng bằng mẫu kiến trúc microservices với các nguyên tắc sau:

- **Độc Lập Dịch Vụ**: Mỗi service có database riêng và có thể triển khai độc lập
- **API Gateway**: Traefik xử lý routing, load balancing và các mối quan tâm chéo
- **Thư Viện Dùng Chung**: Chức năng chung được trích xuất thành packages dùng chung
- **Infrastructure as Code**: Tất cả cấu hình infrastructure được version
- **Observability**: Khả năng giám sát, logging và tracing đầy đủ

## Sơ Đồ Kiến Trúc

┌─────────────┐ ┌─────────────┐ │ Web App │ │ Mobile App │ │ (Next.js) │ │ (React Native) └──────┬──────┘ └──────┬──────┘ │ │ └──────────┬────────┘ │ ┌────────▼────────┐ │ Traefik │ │ (API Gateway) │ └────────┬─────────┘

## Thành Phần

### Lớp Frontend
- **Web App**: Ứng dụng Next.js với App Router
- **Mobile App**: Ứng dụng React Native

### API Gateway
- **Traefik**: Reverse proxy, load balancer, SSL termination

Thực Hành Tốt Nhất

Phong Cách Viết

1. Clear and Concise: Use simple language, avoid jargon
2. Action-Oriented: Start with verbs (Install, Configure, Deploy)
3. Structured: Use headings, lists, and tables
4. Examples: Provide code examples and commands
5. Visual: Use diagrams where helpful

VI:

1. Rõ Ràng và Súc Tích: Sử dụng ngôn ngữ đơn giản, tránh thuật ngữ
2. Hướng Hành Động: Bắt đầu bằng động từ (Cài đặt, Cấu hình, Triển khai)
3. Có Cấu Trúc: Sử dụng tiêu đề, danh sách và bảng
4. Ví Dụ: Cung cấp ví dụ code và lệnh
5. Trực Quan: Sử dụng sơ đồ khi hữu ích

Ví Dụ Code

Always provide context and explanation:

# Good: With context and explanation
Install dependencies using pnpm:

```bash
pnpm install

Bad: No context

pnpm install

Luôn cung cấp ngữ cảnh và giải thích:

```markdown
# Tốt: Có ngữ cảnh và giải thích
Cài đặt dependencies sử dụng pnpm:

```bash
pnpm install

Không tốt: Không có ngữ cảnh

pnpm install

### Liên Kết

- Use relative links for internal docs
- Use descriptive link text (not "click here")
- Example: `See the [Deployment Guide](../guides/deployment.md) for details.`

**VI**:
- Sử dụng liên kết tương đối cho tài liệu nội bộ
- Sử dụng văn bản liên kết mô tả (không phải "click here")
- Ví dụ: `Xem [Hướng Dẫn Triển Khai](../guides/deployment.md) để biết chi tiết.`

## Ví Dụ Từ Dự Án

### Ví Dụ Tài Liệu Tốt

- `docs/en/guides/getting-started.md` - Clear step-by-step guide
- `services/iam-service/README.md` - Comprehensive service README
- `docs/en/architecture/system-design.md` - Architecture documentation
- `docs/README.md` - Documentation index

**VI**:
- `docs/vi/guides/getting-started.md` - Hướng dẫn từng bước rõ ràng
- `services/iam-service/README.md` - README service toàn diện
- `docs/vi/architecture/system-design.md` - Tài liệu kiến trúc
- `docs/README.md` - Mục lục tài liệu

### Tham Chiếu Vị Trí Tài Liệu


| Content Type | Location | Format |
|--------------|----------|--------|
| Getting Started | `docs/en/guides/getting-started.md` | Separate files |
| Service Setup | `services/[name]/README.md` | Side-by-side |
| Deployment | `docs/en/guides/deployment.md` | Separate files |
| Architecture | `docs/en/architecture/` | Separate files |
| API Specs | `docs/en/api/openapi/` | OpenAPI YAML |
| Runbooks | `docs/en/runbooks/` | Separate files |
| Infrastructure | `infra/[component]/README.md` | Side-by-side |

**VI**:

| Loại Nội Dung | Vị Trí | Định Dạng |
|--------------|--------|----------|
| Bắt Đầu | `docs/vi/guides/getting-started.md` | File riêng biệt |
| Thiết Lập Service | `services/[name]/README.md` | Side-by-side |
| Triển Khai | `docs/vi/guides/deployment.md` | File riêng biệt |
| Kiến Trúc | `docs/vi/architecture/` | File riêng biệt |
| Spec API | `docs/vi/api/openapi/` | OpenAPI YAML |
| Runbooks | `docs/vi/runbooks/` | File riêng biệt |
| Infrastructure | `infra/[component]/README.md` | Side-by-side |

## Tham Khảo Nhanh

### Đặt Tên File

- Use kebab-case: `getting-started.md`
- Be descriptive: `local-development.md` not `dev.md`
- Match EN and VI filenames

**VI**:
- Sử dụng kebab-case: `getting-started.md`
- Mô tả rõ ràng: `local-development.md` không phải `dev.md`
- Khớp tên file EN và VI

### Cấp Độ Tiêu Đề

```markdown
# H1: Document Title (only one per file)
## H2: Major Sections
### H3: Subsections
#### H4: Details (use sparingly)

Mẫu Song Ngữ

# Pattern 1: Inline
Description / Mô tả

# Pattern 2: After slash
PORT=5000  # Server port / Cổng server

# Pattern 3: Table
| Variable | Description / Mô Tả |

# Pattern 4: Code comments
Install dependencies
# VI: Cài đặt dependencies
pnpm install

Danh Sách Kiểm Tra Tài Liệu

Before publishing documentation:

• Determine correct location (docs/ vs service README)
• Choose bilingual format (side-by-side vs separate)
• Review existing docs for consistency
• Use clear, concise language
• Include code examples
• Add diagrams where helpful
• Provide troubleshooting section
• Link to related documentation
• Test all commands and code examples
• Check all links work
• Ensure bilingual consistency
• Update documentation index

Trước khi xuất bản tài liệu:

• Xác định vị trí đúng (docs/ vs service README)
• Chọn định dạng song ngữ (side-by-side vs separate)
• Xem lại tài liệu hiện có để đảm bảo tính nhất quán
• Sử dụng ngôn ngữ rõ ràng, súc tích
• Bao gồm ví dụ code
• Thêm sơ đồ khi hữu ích
• Cung cấp phần xử lý sự cố
• Liên kết đến tài liệu liên quan
• Kiểm tra tất cả lệnh và ví dụ code
• Kiểm tra tất cả liên kết hoạt động
• Đảm bảo tính nhất quán song ngữ
• Cập nhật mục lục tài liệu

Skills Liên Quan

• Project Rules - Project structure and standards
• API Design - API documentation patterns
• Comment Code - Code commenting guidelines

Tài Nguyên

• Markdown Guide
• Mermaid Diagrams
• Documentation Best Practices

VI:

• Hướng Dẫn Markdown
• Sơ Đồ Mermaid
• Thực Hành Tốt Nhất Tài Liệu