Chuẩn tiêu đề tài liệu Markdown — Lakehouse

Thông tin tài liệu

• Sprint: 01 - Xây Dựng Nền Tảng Hạ Tầng
• Ngày tạo: 25 tháng 6, 2025
• Phiên bản: 1.0
• Trạng thái: Đã phê duyệt
• Chủ sở hữu: Đội Tài Liệu Lakehouse

Tóm tắt: Tiêu chuẩn header và format cho tất cả tài liệu markdown trong dự án Lakehouse, đảm bảo tính nhất quán và dễ dàng theo dõi.

Mục đích tài liệu

Tài liệu này định nghĩa tiêu chuẩn header cho tất cả file markdown trong dự án Lakehouse nhằm:

• Thống nhất format: Đảm bảo tất cả tài liệu có format nhất quán
• Dễ theo dõi: Biết được tài liệu thuộc sprint nào, version nào
• Quản lý ownership: Rõ ràng ai chịu trách nhiệm về tài liệu
• Hỗ trợ đào tạo: Nội dung tiếng Việt giúp đào tạo dễ dàng hơn

Cấu trúc header chuẩn

Template bắt buộc

# [Icon] [Tên Tài Liệu Tiếng Việt]
 
---
**Thông tin tài liệu**
- **Sprint**: [Số Sprint] - [Tên Sprint]  
- **Ngày tạo**: [DD tháng MM, YYYY]  
- **Phiên bản**: [X.Y]  
- **Trạng thái**: [Emoji + Trạng thái]  
- **Chủ sở hữu**: [Tên Team/Người chịu trách nhiệm]  
 
**Tóm tắt**: [Mô tả ngắn gọn mục đích và nội dung chính của tài liệu]
 
---
 
## [Nội dung chính]

Giải thích các trường

Danh sách icon theo loại tài liệu

Tài liệu kế hoạch

• Kế hoạch tổng thể: Master plan, roadmap
• Lịch trình: Timeline, milestone
• Báo cáo tiến độ: Progress report, status
• Checklist: Task list, deliverable tracking

Tài liệu kỹ thuật

• Kiến trúc: Architecture, design
• Cấu hình: Configuration, setup
• Hướng dẫn: Tutorial, how-to
• API: API documentation

Tài liệu quản lý

• Team: Team structure, roles
• Quy trình: Process, workflow
• Mục tiêu: Objectives, goals
• Metrics: KPI, measurement

Tài liệu đào tạo

• Đào tạo: Training material
• Tài liệu tham khảo: Reference, guide
• Best practices: Tips, recommendations
• Troubleshooting: Problem solving

Trạng thái tài liệu

Nguyên tắc viết nội dung

Sử dụng tiếng Việt

• Mục đích: Hỗ trợ đào tạo và chuyển giao kiến thức
• Nguyên tắc: Sử dụng tiếng Việt cho:
  • Tiêu đề chính và phụ
  • Mô tả, giải thích khái niệm
  • Hướng dẫn thực hiện
  • Comments trong code

Giữ lại tiếng Anh

• Thuật ngữ kỹ thuật: Docker, Kubernetes, API
• Tên công cụ: Spark, Kafka, Trino
• Code và command: Shell scripts, configuration
• Tên biến và function: Trong code examples

Cấu trúc nội dung

1. Header chuẩn (bắt buộc)
2. Mục đích tài liệu (khuyến khích)
3. Nội dung chính với heading rõ ràng
4. Kết luận / Next steps (nếu có)

Ví dụ thực tế

Ví dụ 1: Tài liệu kế hoạch

# Kế Hoạch Sprint 02
 
---
**Thông tin tài liệu**
- **Sprint**: 02 - Customer Data Engineering  
- **Ngày tạo**: 2 tháng 7, 2025  
- **Phiên bản**: 1.0  
- **Trạng thái**: Đang soạn thảo  
- **Chủ sở hữu**: Scrum Master Team  
 
**Tóm tắt**: Kế hoạch chi tiết cho Sprint 02 tập trung vào phát triển data engineering pipeline cho Customer Domain với sample data và basic analytics.
 
---

Ví dụ 2: Tài liệu kỹ thuật

# Kiến Trúc Data Pipeline
 
---
**Thông tin tài liệu**
- **Sprint**: 01 - Xây Dựng Nền Tảng Hạ Tầng  
- **Ngày tạo**: 25 tháng 6, 2025  
- **Phiên bản**: 2.1  
- **Trạng thái**: Đã phê duyệt  
- **Chủ sở hữu**: Đội Kiến Trúc Dữ Liệu  
 
**Tóm tắt**: Thiết kế kiến trúc data pipeline với Kafka, Spark và Trino cho xử lý dữ liệu real-time và batch processing trong Lakehouse.
 
---

Quy trình cập nhật header

Khi nào cập nhật

1. Thay đổi nội dung: Tăng phiên bản Minor (1.0 → 1.1)
2. Thay đổi lớn: Tăng phiên bản Major (1.x → 2.0)
3. Thay đổi trạng thái: Cập nhật emoji trạng thái
4. Chuyển Sprint: Cập nhật Sprint number nếu cần

Ai có trách nhiệm

• Tác giả: Cập nhật khi sửa đổi nội dung
• Team Lead: Review và phê duyệt trạng thái
• Scrum Master: Đảm bảo tuân thủ chuẩn

Checklist tuân thủ

Trước khi commit tài liệu markdown, kiểm tra:

• Header có đầy đủ các trường bắt buộc
• Icon phù hợp với loại tài liệu
• Sprint number chính xác
• Phiên bản được cập nhật
• Trạng thái phù hợp
• Tóm tắt rõ ràng và ngắn gọn
• Nội dung chính sử dụng tiếng Việt
• Thuật ngữ kỹ thuật giữ nguyên tiếng Anh
• Cấu trúc heading logic và rõ ràng

Lợi ích khi tuân thủ

Cho team

• Tracking dễ dàng: Biết tài liệu thuộc sprint nào
• Version control: Theo dõi thay đổi qua version
• Ownership rõ ràng: Biết liên hệ ai khi có vấn đề

Cho training

• Nội dung tiếng Việt: Dễ hiểu cho team Việt Nam
• Cấu trúc thống nhất: Học viên quen thuộc với format
• Thông tin đầy đủ: Context về tài liệu rõ ràng

Cho dự án

• Quản lý chất lượng: Đảm bảo tất cả tài liệu có chuẩn
• Audit trail: Theo dõi ai làm gì, khi nào
• Maintenance: Dễ dàng maintain và update

Lưu ý: Tài liệu này sẽ được cập nhật theo feedback từ team và experience thực tế trong quá trình triển khai dự án.