admin/pos-system

Fork 0

Files

Ho Ngoc Hai 76d75c753b Migrate

2026-05-23 18:37:02 +07:00

13 KiB

Raw Blame History

name, description, metadata

name

description

metadata

documentation

Documentation guidelines for GoodGo project. Use for README, guides, architecture docs, or API docs. Ensures bilingual EN/VI consistency.

author	version
Velik Ho	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)
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:

UPPERCASE for main docs: README.md, ARCHITECTURE.md, API.md
UPPERCASE_SNAKE_CASE for guides: WHATSAPP_SETUP.md, AI_CHATBOT_GUIDE.md
Same filename in both folders: Easy to find corresponding files
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)

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

# 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/
Tiếng Việt: 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


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

# ❌ BAD: English only
## Configuration

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

2. Wrong Location

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

# ❌ 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 - OpenAPI templates and best practices
Versioning Documentation - Changelog format, migration guides
Diagrams & Visuals - Mermaid diagrams, screenshots, optimization
API Endpoint Tables - Standard table formats for API docs
Configuration Documentation - Environment variables, config files
Automation & Tools - Link checking, linting, CI/CD integration

Resources / Tài Nguyên

Project Rules - Project structure and standards
Comment Code - Code commenting standards
API Design - API documentation
Mermaid Diagrams - Diagram patterns with dark color palette (MANDATORY for docs)
Skill Authoring - How to write skills

Workflows

/docs-edit-vi-en - Workflow for updating microservices documentation

External Resources

Keep a Changelog - Changelog format standard
Semantic Versioning - Version numbering scheme
OpenAPI Specification - API documentation standard
Markdown Guide - Markdown syntax reference
GitHub Flavored Markdown - GitHub markdown extensions

Tools

markdown-link-check - Validate markdown links
markdownlint - Markdown linter
Redocly CLI - OpenAPI tools
Mermaid Live Editor - Test Mermaid diagrams

13 KiB Raw Blame History