483 lines
12 KiB
Markdown
483 lines
12 KiB
Markdown
# Template Usage Guide / Hướng dẫn Sử dụng Templates
|
|
|
|
## Overview / Tổng quan
|
|
|
|
**EN**: This guide explains how to use the documentation templates to maintain consistency across all documentation updates.
|
|
|
|
**VI**: Hướng dẫn này giải thích cách sử dụng các templates tài liệu để duy trì tính nhất quán trong tất cả các cập nhật tài liệu.
|
|
|
|
## Available Templates / Templates Có sẵn
|
|
|
|
| Template | Use For | File |
|
|
|----------|---------|------|
|
|
| **Architecture** | System design, component architecture | [`architecture-doc-template.md`](./architecture-doc-template.md) |
|
|
| **Guide** | Step-by-step howtos, tutorials | [`guide-doc-template.md`](./guide-doc-template.md) |
|
|
| **Skill/Pattern** | Design patterns, coding standards | [`skill-pattern-template.md`](./skill-pattern-template.md) |
|
|
| **Mermaid** | Diagram reference and examples | [`MERMAID_GUIDE.md`](./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**:
|
|
```mermaid
|
|
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
|
|
|
|
```bash
|
|
# 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**:
|
|
```mermaid
|
|
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**:
|
|
```typescript
|
|
// 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`](file:///absolute/path/to/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**:
|
|
```bash
|
|
# 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**:
|
|
```markdown
|
|
### 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**:
|
|
```typescript
|
|
/**
|
|
* 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**:
|
|
```markdown
|
|
**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**:
|
|
```markdown
|
|
#### 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)
|
|
```markdown
|
|
> **EN**: Brief English description
|
|
> **VI**: Mô tả ngắn gọn tiếng Việt
|
|
```
|
|
|
|
#### Option 2: Separate sections (for detailed content)
|
|
```markdown
|
|
### 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)
|
|
```typescript
|
|
// 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`](./MERMAID_GUIDE.md) for:
|
|
- Diagram type selection
|
|
- Syntax examples
|
|
- Styling guidelines
|
|
|
|
### Step 2: Create Diagram
|
|
|
|
```markdown
|
|
\`\`\`mermaid
|
|
graph TD
|
|
A[Start] --> B[Process]
|
|
B --> C[End]
|
|
\`\`\`
|
|
```
|
|
|
|
### Step 3: Test Rendering
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```mermaid
|
|
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
|
|
|
|
```bash
|
|
# 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`](../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`](../../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
|
|
|
|
1. **Which template to use?** → See decision tree above
|
|
2. **How to create diagrams?** → See `MERMAID_GUIDE.md`
|
|
3. **How to structure bilingual content?** → See "Bilingual Content Guidelines"
|
|
4. **Where to find code examples?** → Look in `_template` or `iam-service`
|
|
|
|
### Resources / Tài nguyên
|
|
|
|
- [Mermaid Guide](./MERMAID_GUIDE.md) - Diagram reference
|
|
- [Architecture Template](./architecture-doc-template.md) - Template file
|
|
- [Guide Template](./guide-doc-template.md) - Template file
|
|
- [Skill Template](./skill-pattern-template.md) - Template file
|
|
|
|
---
|
|
|
|
**Last Updated**: 2026-01-07
|
|
**Maintained by**: VelikHo ([@hongochai10](https://github.com/hongochai10))
|