Quy chuẩn doc

Khi đọc tài liệu kỹ thuật của dự án, thành viên mới thường gặp khó khăn do các từ chuyên ngành bị dịch-bia một cách ngô nghê, công thức toán bị méo mó hiển thị, và các biểu đồ quy trình bị lỗi cú pháp không thể kết xuất. Làm sao để viết một tài liệu khoa học mà bất kỳ ai đọc cũng có thể hiểu đúng bản chất, ghi nhớ lâu và dễ dàng tra cứu nhanh khi cần?

Bài viết này chuẩn hóa các quy tắc viết tài liệu của team: từ việc sử dụng thuật ngữ chính xác, định dạng văn bản chuyên nghiệp, đến cách viết công thức toán học và thiết kế sơ đồ trực quan.

1. Bảng thuật ngữ cục bộ

Thuật ngữ	Tên tiếng Anh	Dịch nghĩa & Giải thích
Markdown	Markdown Format	Ngôn ngữ đánh dấu văn bản gọn nhẹ.
LaTeX	LaTeX Math Block	Định dạng soạn thảo công thức toán học.
Mermaid	Mermaid Diagram	Công cụ vẽ sơ đồ bằng mã nguồn Markdown.

2. Các khái niệm cốt lõi

2.1 Nhất quán thuật ngữ chuyên ngành

• ⚙️ Cơ chế: Phân loại thuật ngữ thành ba nhóm: giữ nguyên từ khóa tiếng Anh đối với thuật ngữ kỹ thuật chuẩn (kèm giải nghĩa lần đầu), dịch tự nhiên đối với từ đời thường, và loại bỏ hoàn toàn các ẩn dụ rỗng hoặc dịch-bia.
• 🔍 Cách nhận diện: Giữ nguyên smoke test, walk-forward thay vì dịch thành "thang khói" hay "chân trời".
• 💡 Ý nghĩa: Đảm bảo tính chính xác khoa học của tài liệu và giúp người đọc dễ dàng tra cứu tài liệu chuyên ngành quốc tế.
• ⚠️ Bẫy: Cố gắng dịch nghĩa-đen toàn bộ các thuật ngữ chuyên ngành tiếng Anh sang tiếng Việt, gây ra sự tối nghĩa và khó hiểu.

2.2 Định dạng văn bản khoa học

• ⚙️ Cơ chế: Soạn thảo văn bản theo cấu trúc cây đánh số phân cấp (## 1, ### 1.1), in đậm danh từ đầu mỗi dòng danh sách, viết câu dài liền mạch trên một dòng để trình soạn thảo tự động wrap, và tuyệt đối không sử dụng đại từ mơ hồ (nó, cái này, cái đó).
• 🔍 Cách nhận diện: Cấu trúc markdown sạch sẽ, không có các dòng ngắt thủ công ở giữa câu, danh từ đầu bullet được in đậm rõ ràng.
• 💡 Ý nghĩa: Giúp người đọc lướt nhanh vẫn nắm được toàn bộ khung nội dung và cấu trúc tài liệu.
• ⚠️ Bẫy: Sử dụng các đại từ trung tính mơ hồ để trỏ ngược, gây nhập nhằng tham chiếu và giảm tính khoa học của tài liệu.

2.3 Công thức toán và Sơ đồ trực quan

• ⚙️ Cơ chế:
  • Công thức: Bọc công thức trong khối $$ hoặc $, định nghĩa biến số đầy đủ từ trái qua phải.
  • Sơ đồ: Mặc định dùng sơ đồ dọc (flowchart TD), nhãn tiếng Việt có dấu nằm trong dấu nháy kép "...", giới hạn dưới 12 nút.
• 🔍 Cách nhận diện: Các công thức toán hiển thị cân đối bằng LaTeX, sơ đồ Mermaid hiển thị đầy đủ không bị lỗi cú pháp.
• 💡 Ý nghĩa: Tránh lỗi biên dịch hiển thị và đảm bảo sơ đồ trực quan dễ đọc trên mọi thiết bị.
• ⚠️ Bẫy: Sử dụng ký tự đô-la đơn lẻ làm méo văn bản, hoặc đưa các ký tự đặc biệt ngoài nháy kép vào nhãn sơ đồ Mermaid làm hỏng hiển thị.

✅ Tự kiểm nhanh

1. Tại sao quy chuẩn yêu cầu giữ nguyên các thuật ngữ kỹ thuật tiếng Anh như smoke test hay walk-forward?

Đáp án

Để đảm bảo tính chính xác, nhất quán và thuận tiện cho việc tra cứu chéo với tài liệu chuyên ngành quốc tế. Việc cố dịch-bia các từ này sang tiếng Việt (như dịch thành "thang khói") sẽ làm sai lệch bản chất và gây khó hiểu cho người đọc.

2. Làm thế nào để viết công thức toán học và ký hiệu tiền tệ mà không làm hỏng hiển thị Markdown?

Đáp án

Viết công thức toán trong khối LaTeX sử dụng dấu đô-la bọc ngoài ($formula$). Đối với tiền tệ USD, viết rõ chữ "USD" hoặc escape ký tự đô-la để tránh việc trình biên dịch Markdown nhận nhầm là thẻ LaTeX.