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

Sơ Đồ Cấu Trúc Tài Liệu

Sơ đồ sau minh họa nơi đặt các loại tài liệu khác nhau:

graph TD
    Start[Documentation Need] --> TypeDecision{Documentation Type?}
    
    TypeDecision -->|Project-Level| ProjectDocs[Project-Level Documentation]
    TypeDecision -->|Service/Package| ServiceDocs[Service/Package Documentation]
    TypeDecision -->|Deployment| DeployDocs[Deployment Documentation]
    TypeDecision -->|Infrastructure| InfraDocs[Infrastructure Documentation]
    
    ProjectDocs --> ProjectLoc["docs/en/<br/>docs/vi/"]
    ProjectLoc --> ProjectSub{Content Type?}
    ProjectSub -->|Guides| GuidesLoc["guides/<br/>(getting-started.md,<br/>deployment.md)"]
    ProjectSub -->|Architecture| ArchLoc["architecture/<br/>(system-design.md)"]
    ProjectSub -->|API Specs| APILoc["api/openapi/<br/>(*.yaml)"]
    ProjectSub -->|Runbooks| RunbookLoc["runbooks/<br/>(incident-response.md)"]
    
    ServiceDocs --> ServiceLoc["services/[name]/README.md<br/>packages/[name]/README.md"]
    ServiceLoc --> ServiceFormat[Format: Side-by-side bilingual]
    
    DeployDocs --> DeployLoc["deployments/[env]/README.md"]
    DeployLoc --> DeployFormat[Format: Technical, operations-focused]
    
    InfraDocs --> InfraLoc["infra/[component]/README.md"]
    InfraLoc --> InfraFormat[Format: Side-by-side bilingual]
    
    style ProjectDocs fill:#e1f5ff
    style ServiceDocs fill:#fff4e1
    style DeployDocs fill:#ffe1f5
    style InfraDocs fill:#e1ffe1

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

Quy Trình Quyết Định Định Dạng Song Ngữ

Sử dụng cây quyết định sau để chọn định dạng song ngữ phù hợp:

flowchart TD
    Start[Creating Documentation] --> CheckLength{Content Length?}
    
    CheckLength -->|Short<br/>< 200 lines| CheckLocation{Document Location?}
    CheckLength -->|Long<br/>> 200 lines| SeparateFiles[Use Separate Files Format]
    
    CheckLocation -->|README files<br/>Service/Package docs<br/>Infrastructure docs| SideBySide[Use Side-by-side Format]
    CheckLocation -->|docs/guides/<br/>Short configuration docs| SideBySide
    
    CheckLength -->|Medium| CheckType{Content Type?}
    CheckType -->|API Documentation<br/>Technical Specifications| Sections[Use Sections Format]
    CheckType -->|Mixed Content| Sections
    
    SeparateFiles --> SeparateAction["Create docs/en/[path]/file.md<br/>Create docs/vi/[path]/file.md<br/>(Mirror structure)"]
    SideBySide --> SideBySideAction["Single file with<br/>EN / VI inline<br/>Example: 'Title / Tiêu Đề'"]
    Sections --> SectionsAction["Single file with<br/>--- separator<br/>EN section then VI section"]
    
    SeparateAction --> Done[Documentation Complete]
    SideBySideAction --> Done
    SectionsAction --> Done
    
    style SideBySide fill:#e1f5ff
    style SeparateFiles fill:#fff4e1
    style Sections fill:#ffe1f5
    style Done fill:#e1ffe1

Khi Nào Sử Dụng Từng Định Dạng

• Side-by-side: README files, hướng dẫn ngắn, tài liệu cấu hình
• Separate files: Hướng dẫn dài (>200 dòng), tài liệu kiến trúc, runbooks
• Sections: Tài liệu API, đặc tả kỹ thuậ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