206 lines
5.0 KiB
Markdown
206 lines
5.0 KiB
Markdown
# Hướng dẫn Sử dụng Templates Tài liệu
|
|
|
|
> **Mục đích**: Hướng dẫn sử dụng các templates tài liệu để tạo documentation nhất quán cho project
|
|
|
|
## Templates Có sẵn
|
|
|
|
### 1. Architecture Template - [`architecture.md`](./architecture.md)
|
|
|
|
**Sử dụng khi**: Tài liệu hóa kiến trúc hệ thống, thành phần, hoặc design decision
|
|
|
|
**Bao gồm**:
|
|
- Sơ đồ tổng quan (Mermaid diagrams)
|
|
- Mô tả thành phần chi tiết
|
|
- Quyết định thiết kế
|
|
- Database architecture
|
|
- Performance characteristics
|
|
- Security considerations
|
|
- Deployment strategy
|
|
|
|
**Ví dụ**: [`system-design.md`](../architecture/system-design.md)
|
|
|
|
### 2. Guide Template - [`guide.md`](./guide.md)
|
|
|
|
**Sử dụng khi**: Tạo hướng dẫn từng bước (getting started, deployment, troubleshooting)
|
|
|
|
**Bao gồm**:
|
|
- Workflow diagram
|
|
- Prerequisites
|
|
- Hướng dẫn từng bước chi tiết
|
|
- Verification steps
|
|
- Common issues & troubleshooting
|
|
- FAQ section
|
|
|
|
**Ví dụ**: Hướng dẫn deployment, local development
|
|
|
|
### 3. Skill/Pattern Template - [`skill-pattern.md`](./skill-pattern.md)
|
|
|
|
**Sử dụng khi**: Tài liệu hóa coding patterns, best practices, hoặc kỹ thuật
|
|
|
|
**Bao gồm**:
|
|
- Pattern overview
|
|
- When to use / when not to use
|
|
- Implementation examples
|
|
- Class diagrams
|
|
- Best practices
|
|
- Common mistakes
|
|
- Testing examples
|
|
|
|
**Ví dụ**: Repository pattern, RBAC pattern
|
|
|
|
## Quick Start
|
|
|
|
### Bước 1: Chọn Template phù hợp
|
|
|
|
Xác định loại tài liệu bạn cần tạo:
|
|
- **Kiến trúc** → `architecture.md`
|
|
- **Hướng dẫn** → `guide.md`
|
|
- **Pattern/Skill** → `skill-pattern.md`
|
|
|
|
### Bước 2: Copy Template
|
|
|
|
```bash
|
|
# Ví dụ: Tạo architecture document mới
|
|
cp docs/vi/templates/architecture.md docs/vi/architecture/ten-kien-truc-moi.md
|
|
```
|
|
|
|
### Bước 3: Thay thế Placeholders
|
|
|
|
Thay thế các placeholder trong template:
|
|
- `[Tên Kiến trúc]` → Tên thực của document
|
|
- `[Tiêu đề]` → Tiêu đề sections
|
|
- `[Mô tả]` → Nội dung thực tế
|
|
|
|
### Bước 4: Tùy chỉnh Nội dung
|
|
|
|
- Điền vào tất cả sections
|
|
- Tạo Mermaid diagrams (xem [mermaid-guide.md](./mermaid-guide.md))
|
|
- Thêm code examples với comments song ngữ
|
|
- Cập nhật metadata (Last Updated, Authors)
|
|
|
|
### Bước 5: Review Checklist
|
|
|
|
- [ ] Tất cả placeholders đã được thay thế
|
|
- [ ] Mermaid diagrams hiển thị đúng
|
|
- [ ] Code examples có syntax highlighting
|
|
- [ ] Có đầy đủ nội dung tiếng Việt
|
|
- [ ] Links hoạt động chính xác
|
|
- [ ] Metadata được cập nhật
|
|
|
|
## Quy ước Viết Tài liệu
|
|
|
|
### Ngôn ngữ
|
|
|
|
**Tiếng Việt**:
|
|
- Sử dụng 100% tiếng Việt cho tất cả nội dung
|
|
- Giữ thuật ngữ kỹ thuật bằng tiếng Anh khi cần (Docker, Kubernetes, etc.)
|
|
- Code examples vẫn giữ nguyên tiếng Anh
|
|
|
|
**Code Comments**:
|
|
```typescript
|
|
// Ví dụ code với comments tiếng Việt
|
|
export class Example {
|
|
/**
|
|
* Khởi tạo service với dependencies
|
|
*/
|
|
constructor(private dependency: Dependency) {}
|
|
}
|
|
```
|
|
|
|
### Mermaid Diagrams
|
|
|
|
Tham khảo [Hướng dẫn Mermaid](./mermaid-guide.md) để biết:
|
|
- Các loại diagrams có sẵn
|
|
- Color scheme chuẩn
|
|
- Best practices
|
|
- Ví dụ cho mỗi loại diagram
|
|
|
|
**Color Palette**:
|
|
```
|
|
#4A90E2 - Xanh dương (Primary actions)
|
|
#F5A623 - Cam vàng (Data/Cache)
|
|
#9013FE - Tím (Processing)
|
|
#50E3C2 - Xanh lá (Success)
|
|
#E74C3C - Đỏ (Errors)
|
|
#F39C12 - Vàng cam (Warnings)
|
|
#7B68EE - Tím xanh (Info)
|
|
#95A5A6 - Xám (Neutral)
|
|
```
|
|
|
|
### File Organization
|
|
|
|
```
|
|
docs/vi/
|
|
├── templates/ # Templates (file này)
|
|
├── architecture/ # Architecture docs
|
|
├── guides/ # How-to guides
|
|
└── skills/ # Patterns & skills
|
|
```
|
|
|
|
## Thực hành Tốt nhất
|
|
|
|
### 1. Viết Ngắn gọn và Rõ ràng
|
|
|
|
- Ngắn gọn, súc tích
|
|
- Một ý chính mỗi paragraph
|
|
- Sử dụng bullet points cho lists
|
|
|
|
### 2. Ưu tiên Hình ảnh
|
|
|
|
- Thêm diagrams cho mọi concepts phức tạp
|
|
- Sử dụng code examples với output
|
|
- Screenshots khi cần (UI, browser)
|
|
|
|
### 3. Khả năng Bảo trì
|
|
|
|
- Link tới related documentation
|
|
- Cập nhật "Last Updated" date
|
|
- Ghi rõ version nếu có
|
|
|
|
### 4. Khả năng Truy cập
|
|
|
|
- Alt text cho images
|
|
- Descriptive link text (không dùng "click here")
|
|
- Headings có cấu trúc logic
|
|
|
|
## Mẹo Hữu ích
|
|
|
|
### Tạo Diagrams nhanh
|
|
|
|
```bash
|
|
# Sử dụng Mermaid Live Editor
|
|
# https://mermaid.live/
|
|
```
|
|
|
|
### Validate Markdown
|
|
|
|
```bash
|
|
# Cài đặt markdownlint
|
|
pnpm add -g markdownlint-cli
|
|
|
|
# Check markdown files
|
|
markdownlint docs/vi/**/*.md
|
|
```
|
|
|
|
### Link Format
|
|
|
|
```markdown
|
|
# Relative links (ưu tiên)
|
|
[Architecture](../architecture/system-design.md)
|
|
|
|
# Với line numbers (file links)
|
|
[Code Example](file:///path/to/file.ts#L10-L20)
|
|
```
|
|
|
|
## Khắc phục Sự cố
|
|
|
|
### Mermaid không hiển thị?
|
|
|
|
1. Kiểm tra syntax với [Mermaid Live Editor](https://mermaid.live/)
|
|
2. Đảm bảo code block có `mermaid` language tag
|
|
3. Không có ký tự đặc biệt chưa escape
|
|
|
|
---
|
|
|
|
**Tác giả**: VelikHo (hongochai10@icloud.com)
|