pos-system/microservices/.agent/skills/documentation/SKILL.md

---
name: documentation
description: Documentation guidelines for GoodGo project. Use for README, guides, architecture docs, or API docs. Ensures bilingual EN/VI consistency.
metadata:
  author: Velik Ho
  version: "2.0"
---

# Documentation Writing Guidelines / Hướng Dẫn Viết Tài Liệu

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

Use this skill when:
- Creating README files for services/packages / Tạo README cho services/packages
- Writing user guides and tutorials / Viết hướng dẫn sử dụng
- Documenting system architecture / Viết tài liệu kiến trúc hệ thống
- Creating API documentation / Tạo tài liệu API
- Writing operational runbooks / Viết runbooks vận hành
- Maintaining bilingual documentation / Duy trì tài liệu song ngữ EN/VI

## Core Concepts / Khái Niệm Cốt Lõi

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

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

### Documentation Types & Locations / Loại & Vị Trí Tài Liệu

| Type | Location | Format |
|------|----------|--------|
| Project guides | `docs/en/` + `docs/vi/` | Separate files |
| Service README | `services/[name]/README.md` | Side-by-side bilingual |
| Package README | `packages/[name]/README.md` | Side-by-side bilingual |
| Deployment | `deployments/[env]/README.md` | Technical only |
| Infrastructure | `infra/[component]/README.md` | Side-by-side bilingual |
| API Specs | `docs/en/api/openapi/` | OpenAPI YAML |

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

**REQUIRED structure for all microservices:**

```
services/my-service-net/
├── README.md                   # Service overview with links to EN/VI docs
└── docs/
    ├── en/                     # English documentation
    │   ├── README.md           # English content
    │   ├── ARCHITECTURE.md     # English content
    │   ├── API.md              # English content (optional)
    │   └── [OTHER].md          # Service-specific docs
    └── vi/                     # Vietnamese documentation (mirror EN structure)
        ├── README.md           # Vietnamese content (same filename!)
        ├── ARCHITECTURE.md     # Vietnamese content (same filename!)
        ├── API.md              # Vietnamese content (same filename!)
        └── [OTHER].md          # Service-specific docs (same filename!)
```

**Key Rules:**
- `docs/en/` and `docs/vi/` MUST mirror each other (same files, **same filenames**)
- Each language folder is MONOLINGUAL (no bilingual mixing)
- **Filenames**: Use **same English filenames** in both EN and VI folders
- Service root `README.md` links to both EN/VI documentation
- Mermaid diagrams MUST use dark color palette (see [Mermaid Diagrams Skill](../mermaid-diagrams/SKILL.md))
- `ARCHITECTURE.md` and `README.md` are MANDATORY in both folders

### Filename Conventions / Quy Ước Đặt Tên File

**IMPORTANT**: Both `docs/en/` and `docs/vi/` use the **same English filenames**.

**Standard Filenames (used in both EN and VI folders):**

| Filename | Purpose / Mục đích |
|----------|-------------------|
| `README.md` | Service introduction, quick start / Giới thiệu dịch vụ, bắt đầu nhanh |
| `ARCHITECTURE.md` | Architecture documentation / Tài liệu kiến trúc |
| `API.md` | API reference / Tài liệu API |
| `DEPLOYMENT.md` | Deployment guide / Hướng dẫn triển khai |
| `CONFIGURATION.md` | Configuration guide / Hướng dẫn cấu hình |
| `TESTING.md` | Testing guide / Hướng dẫn kiểm thử |
| `TROUBLESHOOTING.md` | Troubleshooting / Khắc phục sự cố |
| `WHATSAPP_SETUP.md` | WhatsApp setup / Cài đặt WhatsApp |
| `AI_CHATBOT_GUIDE.md` | AI chatbot guide / Hướng dẫn chatbot AI |
| `AUTOMATION_GUIDE.md` | Automation guide / Hướng dẫn tự động hóa |

**Naming Rules:**

1. **UPPERCASE for main docs**: `README.md`, `ARCHITECTURE.md`, `API.md`
2. **UPPERCASE_SNAKE_CASE for guides**: `WHATSAPP_SETUP.md`, `AI_CHATBOT_GUIDE.md`
3. **Same filename in both folders**: Easy to find corresponding files
4. **English only**: No encoding issues, better tool compatibility

**Benefits:**
- ✅ Easy to find corresponding files (same name in EN and VI)
- ✅ Simple file management and linking
- ✅ No encoding issues with special characters
- ✅ Better compatibility with development tools

## Key Patterns / Mẫu Chính

### Bilingual Format Options / Định Dạng Song Ngữ

**Option 1: Side-by-side (for short content)**
```markdown
# Service Name / Tên Dịch Vụ

This is a description.
Đây là mô tả.
```

**Option 2: Separate files (for long content > 200 lines)**
```
docs/
├── en/guides/deployment.md
└── vi/guides/deployment.md
```

### Service README Template

**For service root `README.md` (bilingual with links to language-specific docs):**

```markdown
# Service Name

> **EN**: [English Documentation](docs/en/README.md)  
> **VI**: [Tài liệu Tiếng Việt](docs/vi/gioi-thieu.md)

## Quick Links

- 📖 [Architecture](docs/en/ARCHITECTURE.md) / [Kiến trúc](docs/vi/ARCHITECTURE.md)
- 🚀 [API Reference](docs/en/API.md) / [Tài liệu API](docs/vi/API.md)
- ⚙️ [Configuration](docs/en/README.md#configuration) / [Cấu hình](docs/vi/README.md#configuration)

## Tech Stack

- .NET 8 / Node.js 20
- PostgreSQL
- Redis
- RabbitMQ

## Development

```bash
dotnet build && dotnet run
# or
pnpm install && pnpm dev
```

See detailed documentation:
- **English**: [docs/en/](docs/en/)
- **Tiếng Việt**: [docs/vi/](docs/vi/)
```

**For `docs/en/README.md` (English only, detailed):**

```markdown
# Service Name

Brief description in English.

## Features
- Feature 1
- Feature 2

## Prerequisites
- .NET 8 / Node.js 20+
- PostgreSQL 15+

## Quick Start
```bash
dotnet run
```

## Configuration

| Variable | Description | Default |
|----------|-------------|---------|
| PORT | Server port | 5000 |
| DATABASE_URL | PostgreSQL connection | - |

## API Endpoints
See [API Documentation](API.md)
```

### Architecture Document Template (Microservices)

For microservices in `services/[name]/docs/en/ARCHITECTURE.md`:

```markdown
# Architecture Documentation

**Service**: [service-name]  
**Version**: 1.0  
**Last Updated**: [Date]

## System Overview

Brief description of the service purpose and capabilities.

### High-Level Architecture

\`\`\`mermaid
graph TB
    subgraph External
        Client[Client/User]
    end
    
    subgraph "GoodGo Platform"
        Gateway[Traefik Gateway]
        
        subgraph "[Service Name]"
            API[API Layer]
            APP[Application Layer]
            DOMAIN[Domain Layer]
            INFRA[Infrastructure Layer]
        end
        
        PG[(PostgreSQL)]
        REDIS[(Redis)]
        RABBIT[RabbitMQ]
    end
    
    Client --> Gateway
    Gateway --> API
    API --> APP
    APP --> DOMAIN
    APP --> INFRA
    INFRA --> PG
    INFRA --> REDIS
    INFRA --> RABBIT
    
    style Gateway fill:#3498DB,color:#ECF0F1,stroke:#2980B9,stroke-width:3px
    style API fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
    style DOMAIN fill:#E67E22,color:#ECF0F1,stroke:#D35400,stroke-width:2px
    style PG fill:#34495E,color:#ECF0F1,stroke:#2C3E50,stroke-width:2px
\`\`\`

## Clean Architecture Layers

### 1. API Layer
**Responsibility**: HTTP interface, controllers, background jobs

### 2. Application Layer
**Responsibility**: Use cases, CQRS commands/queries, handlers

### 3. Domain Layer
**Responsibility**: Business logic, entities, aggregates, domain events

### 4. Infrastructure Layer
**Responsibility**: Persistence, external services, integrations

## Request Flow

\`\`\`mermaid
sequenceDiagram
    participant Client
    participant API
    participant Handler
    participant Domain
    participant DB
    
    Client->>API: POST /endpoint
    API->>Handler: Command/Query
    Handler->>Domain: Business Logic
    Domain->>DB: Save/Retrieve
    DB-->>Domain: Result
    Domain-->>Handler: Result
    Handler-->>API: Response
    API-->>Client: 200 OK
    
    style API fill:#8E44AD,color:#ECF0F1
    style Handler fill:#3498DB,color:#ECF0F1
    style Domain fill:#E67E22,color:#ECF0F1
    style DB fill:#34495E,color:#ECF0F1
\`\`\`

## References
- [API Documentation](API.md)
- [Service README](README.md)
```

## Real-World Examples / Ví Dụ Thực Tế

These services demonstrate best practices for microservices documentation:

- **mkt-facebook-service-net** - Complete bilingual docs with EN/VI separation, Mermaid diagrams, API reference
- **mkt-x-service-net** - Clean language separation, comprehensive architecture docs
- **mkt-zalo-service-net** - Full integration guides, setup instructions
- **order-service-net** - Multi-vertical architecture documentation
- **catalog-service-net** - Standard CQRS/Clean Architecture patterns

## Common Mistakes / Lỗi Thường Gặp

### 1. Single Language Documentation

```markdown
# ❌ BAD: English only
## Configuration

# ✅ GOOD: Bilingual
## Configuration / Cấu Hình
```

### 2. Wrong Location

```markdown
# ❌ BAD: Detailed guide in service README
services/auth-service/README.md (500+ lines of deployment steps)

# ✅ GOOD: Detailed guide in docs/
docs/en/guides/deployment.md
```

### 3. Missing Code Examples

```markdown
# ❌ BAD: No example
Configure the DATABASE_URL variable.

# ✅ GOOD: With example
Configure the DATABASE_URL variable:
```bash
DATABASE_URL="postgresql://user:pass@localhost:5432/db"
```
```

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

1. **Clear and Concise**: Use simple language / Dùng ngôn ngữ đơn giản
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

### What Makes Good Documentation?

1. **Complete Language Separation**: EN and VI in separate directories
2. **Consistent Dark Mermaid Palette**: Following mermaid-diagrams skill
3. **Practical Examples**: Real code snippets, not placeholders
4. **Troubleshooting Sections**: Common issues and solutions
5. **Quick Start Guides**: Get running in < 5 minutes

## Quick Reference / Tham Chiếu Nhanh

### File Naming
- Use kebab-case: `getting-started.md`
- Be descriptive: `local-development.md` not `dev.md`
- Same filenames in both EN and VI folders

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

### Bilingual Patterns

| Pattern | Example |
|---------|---------|
| Inline | `Description / Mô tả` |
| After slash | `PORT=5000  # Server port / Cổng server` |
| Table header | `Description / Mô Tả` |

## Detailed References / Tài Liệu Tham Khảo Chi Tiết

For specialized documentation topics, see:

- [OpenAPI Specification Standards](references/OPENAPI.md) - OpenAPI templates and best practices
- [Versioning Documentation](references/VERSIONING.md) - Changelog format, migration guides
- [Diagrams & Visuals](references/DIAGRAMS.md) - Mermaid diagrams, screenshots, optimization
- [API Endpoint Tables](references/API_TABLES.md) - Standard table formats for API docs
- [Configuration Documentation](references/CONFIGURATION.md) - Environment variables, config files
- [Automation & Tools](references/AUTOMATION.md) - Link checking, linting, CI/CD integration

## Resources / Tài Nguyên

### Related Skills
- [Project Rules](../project-rules/SKILL.md) - Project structure and standards
- [Comment Code](../comment-code/SKILL.md) - Code commenting standards
- [API Design](../api-design/SKILL.md) - API documentation
- [Mermaid Diagrams](../mermaid-diagrams/SKILL.md) - Diagram patterns with dark color palette (MANDATORY for docs)
- [Skill Authoring](../skill-authoring/SKILL.md) - How to write skills

### Workflows
- [/docs-edit-vi-en](../../workflows/docs-edit-vi-en.md) - Workflow for updating microservices documentation

### External Resources
- [Keep a Changelog](https://keepachangelog.com/) - Changelog format standard
- [Semantic Versioning](https://semver.org/) - Version numbering scheme
- [OpenAPI Specification](https://swagger.io/specification/) - API documentation standard
- [Markdown Guide](https://www.markdownguide.org/) - Markdown syntax reference
- [GitHub Flavored Markdown](https://github.github.com/gfm/) - GitHub markdown extensions

### Tools
- [markdown-link-check](https://github.com/tcort/markdown-link-check) - Validate markdown links
- [markdownlint](https://github.com/DavidAnson/markdownlint) - Markdown linter
- [Redocly CLI](https://redocly.com/docs/cli/) - OpenAPI tools
- [Mermaid Live Editor](https://mermaid.live/) - Test Mermaid diagrams