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
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
2. Guide Template - 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
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
# 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)
- 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:
// 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 để 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
# Sử dụng Mermaid Live Editor
# https://mermaid.live/
Validate Markdown
# Cài đặt markdownlint
pnpm add -g markdownlint-cli
# Check markdown files
markdownlint docs/vi/**/*.md
Link Format
# 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ị?
- Kiểm tra syntax với Mermaid Live Editor
- Đảm bảo code block có
mermaidlanguage tag - Không có ký tự đặc biệt chưa escape
Tác giả: VelikHo (hongochai10@icloud.com)