Template	Use For	File
Architecture	System design, component architecture	`architecture-doc-template.md`
Guide	Step-by-step howtos, tutorials	`guide-doc-template.md`
Skill/Pattern	Design patterns, coding standards	`skill-pattern-template.md`
Mermaid	Diagram reference and examples	`MERMAID_GUIDE.md`

Quick Start / Bắt đầu Nhanh

1. Choose the Right Template / Chọn Template Phù hợp

Decision Tree / Cây Quyết định:

flowchart TD
    Start{What are you<br/>documenting?} 
    Start -->|System design,<br/>components| Arch[Use Architecture<br/>Template]
    Start -->|How-to guide,<br/>setup steps| Guide[Use Guide<br/>Template]
    Start -->|Code pattern,<br/>best practice| Skill[Use Skill/Pattern<br/>Template]
    
    Arch --> Mermaid[Add Mermaid<br/>Diagrams]
    Guide --> Mermaid
    Skill --> Mermaid
    
    Mermaid --> Write[Write Bilingual<br/>Content]
    Write --> Review[Review & Test]
    
    style Start fill:#fff3cd
    style Mermaid fill:#e1f5ff
    style Write fill:#d4edda
    style Review fill:#f0e1ff

2. Copy Template / Sao chép Template

# EN: Copy appropriate template
# VI: Sao chép template phù hợp

# For Architecture docs
cp docs/templates/architecture-doc-template.md docs/en/architecture/your-doc.md
cp docs/templates/architecture-doc-template.md docs/vi/architecture/your-doc.md

# For Guides
cp docs/templates/guide-doc-template.md docs/en/guides/your-guide.md
cp docs/templates/guide-doc-template.md docs/vi/guides/your-guide.md

# For Skills
cp docs/templates/skill-pattern-template.md docs/en/skills/your-skill.md
cp docs/templates/skill-pattern-template.md docs/vi/skills/your-skill.md

3. Fill in Content / Điền Nội dung

Replace all placeholders:

[Architecture Name] / [Tên Kiến trúc]
[Guide Title] / [Tiêu đề Hướng dẫn]
[Pattern Name] / [Tên Pattern]
Code examples
Mermaid diagrams

Using Architecture Template / Sử dụng Architecture Template

Sections to Complete / Sections Cần hoàn thành

1. Overview Diagram

EN: Create a high-level diagram showing main components

VI: Tạo sơ đồ cấp cao cho thấy các thành phần chính

Diagram Type: Use graph TD or C4Context

Example:

graph TD
    A[Component A] --> B[Component B]
    B --> C[Component C]

2. Architecture Description

EN: Explain purpose, goals, and design decisions

VI: Giải thích mục đích, mục tiêu và quyết định thiết kế

Content to Include:

Purpose and goals / Mục đích và mục tiêu
Key components / Thành phần chính
Design decisions / Quyết định thiết kế
Technology choices / Lựa chọn công nghệ
Trade-offs / Đánh đổi

3. Components Breakdown

EN: Detail each major component with:

Description
Key features
Technologies used
Code references (links to actual source)
File location

VI: Chi tiết từng thành phần chính với:

Mô tả
Tính năng chính
Công nghệ sử dụng
Tham chiếu code (links tới source thực tế)
Vị trí file

Code Reference Format:

// EN: Example code showing implementation
// VI: Ví dụ code cho thấy cách triển khai
import { Component } from './component';

File Link: component.ts

4. Data Flow Diagram

Diagram Type: Use sequenceDiagram

Shows: How data flows through the system

5. Database Architecture (if applicable)

Diagram Type: Use erDiagram

Shows: Database schema and relationships

6. Design Decisions

Format:

Context: Why decision was needed
Decision: What was decided
Consequences: Impact (positive and negative)
Alternatives: Other options considered

Using Guide Template / Sử dụng Guide Template

Sections to Complete / Sections Cần hoàn thành

1. Workflow Diagram

Diagram Type: Use flowchart LR or flowchart TD

Shows: Overall workflow from start to finish

Include:

Start/End nodes (rounded)
Decision points (diamond)
Action steps (rectangle)
Error handling paths

2. Prerequisites

List:

Required software with versions
Required knowledge
Required access/credentials

Include Quick Check:

# Commands to verify prerequisites
node --version
docker --version

3. Step-by-Step Instructions

For Each Step:

Clear title
Bilingual explanation
Commands with comments
Expected output
Important notes
File examples

Format:

### Step 1: [Action]

**EN**: English explanation

**VI**: Giải thích tiếng Việt

\`\`\`bash
# EN: Command description
# VI: Mô tả lệnh
command-here
\`\`\`

4. Verification

Include:

Quick test commands
Verification checklist
Expected results

5. Troubleshooting

For Each Issue:

Symptoms (what you see)
Solution (steps to fix)
Bilingual for both

Optional: Add troubleshooting decision tree

Using Skill/Pattern Template / Sử dụng Skill/Pattern Template

Sections to Complete / Sections Cần hoàn thành

1. Pattern Overview Diagram

Diagram Type: Use graph LR or graph TD

Shows: High-level pattern flow

2. When to Use

Include:

✅ DO use for (scenarios)
❌ DON'T use for (anti-patterns)

3. Implementation

Provide:

Basic implementation (simple)
Advanced implementation (with caching, error handling, etc.)
Bilingual code comments

Code Format:

/**
 * EN: Class description
 * VI: Mô tả class
 */
export class ExamplePattern {
  // EN: Implementation details
  // VI: Chi tiết triển khai
}

Reference Actual Code:

Link to _template for basic patterns
Link to iam-service for advanced patterns

Example:

**Template**: [`feature.service.ts`](file:///Users/velikho/Desktop/WORKING/Base/services/_template/src/modules/feature/feature.service.ts)

**IAM**: [`rbac.service.ts`](file:///Users/velikho/Desktop/WORKING/Base/services/iam-service/src/modules/rbac/rbac.service.ts)

4. Class Structure Diagram

Diagram Type: Use classDiagram

Shows: Class relationships, inheritance, dependencies

5. Sequence Flow

Diagram Type: Use sequenceDiagram

Shows: Interaction between components

6. Usage Examples

Provide:

Example 1: Basic usage
Example 2: Advanced usage
Include setup, execution, and expected output

7. Common Mistakes

For Each Mistake:

#### Mistake 1: [Description]

\`\`\`typescript
// ❌ BAD: Incorrect implementation
bad code here
\`\`\`

\`\`\`typescript
// ✅ GOOD: Correct implementation
good code here
\`\`\`

**EN Why**: Explanation

**VI Tại sao**: Giải thích

8. Unit Test Example

Include:

Setup (before each)
Test cases (happy path + error cases)
Assertions

Bilingual Content Guidelines / Hướng dẫn Nội dung Song ngữ

Format Options / Tùy chọn Định dạng

Option 1: Side-by-side (for short content)

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

Option 2: Separate sections (for detailed content)

### EN: English Section

Detailed English content...

### VI: Phần Tiếng Việt

Nội dung chi tiết tiếng Việt...

Option 3: Inline (for code comments)

// EN: English comment
// VI: Comment tiếng Việt
const example = 'value';

Translation Consistency / Tính nhất quán Dịch thuật

Common Technical Terms:

EN	VI
Authentication	Xác thực
Authorization	Phân quyền
Deployment	Triển khai
Middleware	Middleware (giữ nguyên)
Repository	Repository (giữ nguyên)
Service	Service (giữ nguyên)
Controller	Controller (giữ nguyên)
Microservice	Microservice (giữ nguyên)
Cache	Cache (giữ nguyên)
Database	Database (giữ nguyên)

Note: Some technical terms are kept in English for clarity and consistency with code.

Adding Mermaid Diagrams / Thêm Sơ đồ Mermaid

Step 1: Choose Diagram Type

Refer to MERMAID_GUIDE.md for:

Diagram type selection
Syntax examples
Styling guidelines

Step 2: Create Diagram

\`\`\`mermaid
graph TD
    A[Start] --> B[Process]
    B --> C[End]
\`\`\`

Step 3: Test Rendering

# Install mermaid-cli
npm install -g @mermaid-js/mermaid-cli

# Test render your doc
mmdc -i docs/en/your-doc.md -o test-output.svg

# Check for errors
echo $?  # 0 = success

Step 4: Apply Consistent Styling

graph TD
    Start([Start]) --> Process[Process]
    Process --> End([End])
    
    style Start fill:#e1f5ff
    style End fill:#d4edda
    style Process fill:#f0e1ff

Color Palette:

#e1f5ff - Blue (primary, start)
#d4edda - Green (success, end)
#fff3cd - Yellow (warning, decision)
#f8d7da - Red (error)
#f0e1ff - Purple (process)
#fff4e1 - Beige (data)

Quality Checklist / Checklist Chất lượng

Before Committing / Trước khi Commit

Content Complete: All sections filled
Bilingual: EN and VI content both complete
Mermaid Diagrams: At least 2-3 diagrams
Diagrams Render: Tested with mermaid-cli
Code Examples: From actual source code
File Links: All links valid (file:///)
Consistent Styling: Colors and formatting consistent
No Placeholders: All [brackets] replaced
Tested Commands: All bash commands tested
Grammar Check: Both EN and VI proofread
Cross-references: Links to related docs work
Metadata: Last updated date, author filled

EN/VI Parity Check

# Compare line counts (should be similar)
wc -l docs/en/your-doc.md
wc -l docs/vi/your-doc.md

# Compare diagram counts
grep -c '```mermaid' docs/en/your-doc.md
grep -c '```mermaid' docs/vi/your-doc.md

Examples / Ví dụ

Good Example: Kubernetes Local Guide

File: docs/vi/guides/kubernetes-local.md

Why it's good:

✅ Clear workflow diagram
✅ Step-by-step instructions
✅ Bilingual content
✅ Verification steps
✅ Troubleshooting section
✅ Tested commands

Good Example: IAM Service README

File: services/iam-service/README.md

Why it's good:

✅ Comprehensive architecture diagrams
✅ Clear API documentation
✅ Real code examples
✅ Well-organized sections
✅ Quick reference tables

Getting Help / Nhận Trợ giúp

Questions / Câu hỏi

Which template to use? → See decision tree above
How to create diagrams? → See MERMAID_GUIDE.md
How to structure bilingual content? → See "Bilingual Content Guidelines"
Where to find code examples? → Look in _template or iam-service

Resources / Tài nguyên

Mermaid Guide - Diagram reference
Architecture Template - Template file
Guide Template - Template file
Skill Template - Template file

Last Updated: 2026-01-07
Maintained by: VelikHo (@hongochai10)