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

Documentation / Tài Liệu

EN: 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. VI: 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.

Overview / Tổng Quan

EN: 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.

VI: 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.

When to Use / Khi Nào Sử Dụng

EN: 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

VI: 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ữ

Key Concepts / Khái Niệm Chính

Documentation Structure / Cấu Trúc Tài Liệu

EN: 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

VI: 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

Bilingual Documentation Rules / Quy Tắc Tài Liệu Song Ngữ

EN: 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

VI: 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

Common Patterns / Các Pattern Thường Dùng

Service README Template / Template README Service

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

# Service Name / Tên Dịch Vụ

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

## Features / Tính Năng

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

## Prerequisites / Yêu Cầu

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

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

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

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

# Start service / Khởi động service
pnpm dev

Configuration / Cấu Hình

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

API Endpoints

See API Documentation

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

```markdown
# Service Name / Tên Dịch Vụ

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

## Features / Tính Năng

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

## Prerequisites / Yêu Cầu

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

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

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

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

# Start service / Khởi động service
pnpm dev

Configuration / Cấu Hình

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

API Endpoints

See API Documentation

### Guide Template / Template Hướng Dẫn

**EN**: 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

**VI**: 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

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

**EN**: 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

VI: 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

Best Practices / Thực Hành Tốt Nhất

Writing Style / Phong Cách Viết

EN:

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

Code Examples / Ví Dụ Code

EN: Always provide context and explanation:

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

```bash
pnpm install

Bad: No context

pnpm install

**VI**: 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

### Links / Liên Kết

**EN**:
- 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.`

## Examples from Project / Ví Dụ Từ Dự Án

### Good Documentation Examples / Ví Dụ Tài Liệu Tốt

**EN**:
- `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

### Documentation Locations Reference / Tham Chiếu Vị Trí Tài Liệu

**EN**:

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

## Quick Reference / Tham Khảo Nhanh

### File Naming / Đặt Tên File

**EN**:
- 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

### Heading Levels / Cấp Độ Tiêu Đề

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

Bilingual Patterns / 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
# EN: Install dependencies
# VI: Cài đặt dependencies
pnpm install

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

EN: 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

VI: 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

Related Skills / Skills Liên Quan

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

Resources / Tài Nguyên

EN:

• 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