Chuyển dịch sang Documentation as Code
Quý trước, nhóm của tôi đã loại bỏ “nghĩa địa” hơn 50 tệp Google Docs rải rác và các trang Confluence lỗi thời. Chúng tôi đã chuyển toàn bộ kiến thức nội bộ trực tiếp vào các kho lưu trữ Git bằng Markdown. Sau sáu tháng sống trong hệ sinh thái này, thời gian làm quen (onboarding) cho các lập trình viên mới đã giảm từ năm ngày xuống còn hai ngày. Tài liệu không còn là một công việc nhàm chán sau mỗi sprint nữa. Nó chính là code.
Viết tài liệu sạch sẽ, dễ đọc là điểm khác biệt thầm lặng giữa một lập trình viên và một kỹ sư cấp cao (senior engineer). Markdown giúp bạn duy trì trạng thái tập trung (flow state) ngay trong IDE trong khi vẫn giữ cho tài liệu được quản lý phiên bản (version-controlled) cùng với logic của mình. Bạn sẽ có được kết quả chuyên nghiệp, được định dạng đẹp mắt mà không cần chạm vào chuột hay các thanh công cụ định dạng phức tạp.
Bắt đầu nhanh (Quy tắc 80/20)
Bạn có thể làm chủ 90% cú pháp thường dùng hàng ngày chỉ trong khoảng năm phút. Markdown dựa trên các ký tự văn bản thuần túy để đánh dấu định dạng cấu hình. Điều này đảm bảo các tệp của bạn luôn có thể đọc được một cách hoàn hảo ngay cả khi xem trong terminal cơ bản hoặc trình chỉnh sửa văn bản thô.
Tiêu đề và Định dạng văn bản
Cấu trúc tài liệu của bạn bằng ký hiệu thăng (#). Hãy coi chúng như các cấp độ trong một dàn ý, tương tự như cấu trúc trong cơ sở dữ liệu. Sử dụng một dấu thăng cho tiêu đề H1 và tăng dần cho các phần con lồng nhau.
# Dự án Alpha (H1)
## Hướng dẫn cài đặt (H2)
### Thiết lập cơ sở dữ liệu (H3)Để nhấn mạnh, hãy sử dụng dấu sao. Mặc dù dấu gạch dưới cũng có tác dụng tương tự, nhưng dấu sao dễ nhận thấy hơn trong các tệp văn bản thô. Sử dụng hai dấu sao cho chữ đậm và một dấu cho chữ nghiêng.
*In nghiêng để nhấn mạnh nhẹ nhàng*
**In đậm cho các thuật ngữ chính hoặc cảnh báo**
~~Gạch ngang cho các tính năng không còn sử dụng (deprecated)~~Danh sách và Liên kết
Các gạch đầu dòng sử dụng dấu gạch ngang đơn giản, trong khi danh sách đánh số sử dụng các chữ số. Đối với liên kết, hãy sử dụng cấu trúc [Văn bản](URL). Nó ngắn gọn và giúp các URL dài không làm lộn xộn các đoạn văn của bạn.
- Tính năng A
- Tính năng B
- Nhiệm vụ con 1
1. Chạy lệnh `npm install`
2. Cấu hình tệp `.env`
[Tham chiếu API](https://api.example.com)Khối mã (Code Blocks)
Đây là yếu tố cốt lõi của việc viết tài liệu kỹ thuật. Sử dụng dấu phẩy ngược đơn cho các từ khóa nội dòng. Đối với các đoạn mã đầy đủ, hãy sử dụng ba dấu phẩy ngược và luôn chỉ định ngôn ngữ. Điều này sẽ kích hoạt tính năng làm nổi bật cú pháp (syntax highlighting), giúp đồng đội của bạn phân tích mã dễ dàng hơn nhiều.
```python
def calculate_uptime(days):
# Trả về kết quả dưới dạng chuỗi "X giờ"
return f"{days * 24} giờ"
```Đi sâu vào: Dữ liệu có cấu trúc
Một khi bạn đã vượt qua những ghi chú cơ bản, bạn sẽ cần tổ chức các dữ liệu phức tạp. Tôi thấy rằng bảng và danh sách công việc là những cách hiệu quả nhất để quản lý các yêu cầu dự án trong tệp README.md.
Bảng cho ánh xạ API
Bảng có thể trông hơi lộn xộn trong văn bản thô, nhưng chúng sẽ hiển thị thành các lưới chuyên nghiệp, sạch sẽ khi mô tả các API. Sử dụng dấu gạch đứng (|) cho các cột và dấu gạch ngang (-) để phân cách tiêu đề.
| Endpoint | Phương thức | Giới hạn |
| :--- | :---: | ---: |
| /users | GET | 100/phút |
| /orders | POST | 50/phút |
| /health | GET | Không giới hạn |Các dấu hai chấm trong hàng phân cách có chức năng định dạng. Đặt chúng ở bên trái (:---) để căn lề trái, cả hai bên (:---:) để căn giữa và bên phải (---:) để căn lề phải.
Trích dẫn và Theo dõi công việc
Sử dụng dấu lớn hơn để làm nổi bật các cảnh báo quan trọng hoặc các lưu ý. Để theo dõi tiến độ sprint, GitHub và GitLab hỗ trợ các danh sách công việc tương tác.
> **Cảnh báo:** Không bao giờ commit tệp `.env` của bạn lên các kho lưu trữ công khai.
- [x] Đã khởi tạo Repo
- [ ] Cấu hình pipeline CI/CD
- [ ] Viết Unit TestsSử dụng nâng cao: Biểu đồ và Logic
Tài liệu hiện đại thường yêu cầu nhiều hơn là chỉ văn bản. Các nhóm hiệu suất cao hiện đang sử dụng các tính năng mở rộng của Markdown để nhúng logic và toán học trực tiếp vào tài liệu của họ.
Biểu đồ Mermaid
Ngừng tải lên các tệp PNG của sơ đồ quy trình. Chúng không thể cập nhật và dễ bị hỏng. Thay vào đó, hãy sử dụng Mermaid để viết mã cho biểu đồ của bạn. Đây là một bước tiến lớn cho các buổi đánh giá kiến trúc của chúng tôi vì nó cho phép chúng tôi theo dõi các thay đổi trong thiết kế hệ thống bằng lệnh git diff.
```mermaid
graph LR;
A[Dịch vụ Auth] --> B{Đã cấp quyền?};
B --> |Có| C[Trang Dashboard];
B --> |Không| D[Trang Đăng nhập];
```Lệnh này tạo ra một sơ đồ quy trình trực tiếp. Nếu logic thay đổi, bạn chỉ cần chỉnh sửa văn bản chứ không phải một tệp hình ảnh.
Biểu thức toán học
Đối với khoa học dữ liệu hoặc các chỉ số hiệu suất, hãy sử dụng cú pháp LaTeX. Bao quanh các công thức căn giữa bằng hai dấu đô la để có khả năng hiển thị tối đa.
$$
O(n \log n)
$$
Công thức tính giá trị trung bình là: $\frac{1}{n} \sum_{i=1}^{n} x_i$Mẹo thực tế cho tài liệu thực tế
Sau sáu tháng sử dụng hàng ngày, tôi đã đúc kết được một vài thói quen giúp phân biệt tài liệu nghiệp dư với các tài nguyên kỹ thuật chuyên nghiệp.
1. Đảm bảo tính nhất quán với Linter
Markdown có thể trở nên lộn xộn nếu không có các quy tắc ràng buộc. Tôi khuyên dùng tiện ích mở rộng markdownlint cho VS Code. Nó giúp phát hiện các lỗi nhỏ, như thiếu dấu cách sau dấu thăng tiêu đề, điều có thể làm hỏng việc hiển thị trên một số nền tảng như Bitbucket.
2. Quy tắc tài nguyên cục bộ
Đừng bao giờ liên kết đến các máy chủ lưu trữ hình ảnh bên ngoài. Nếu trang web đó ngừng hoạt động, tài liệu của bạn cũng sẽ mất hình ảnh. Hãy luôn tạo một thư mục /docs/assets trong repo của bạn và sử dụng đường dẫn tương đối. Điều này đảm bảo hình ảnh của bạn tồn tại lâu như mã nguồn của bạn vậy.
3. Ngưỡng “3 bước” cho README
Đây là quy tắc của tôi: nếu việc thiết lập tốn nhiều hơn ba bước, nó phải được lập tài liệu. Một tệp README chuyên nghiệp phải luôn bao gồm mô tả dự án rõ ràng, các điều kiện tiên trước, các bước cài đặt và ví dụ sử dụng. Các phần ngắn gọn, súc tích sẽ tốt hơn là một khối văn bản dày đặc.
4. Xem trước khi Push
Tránh các thông báo commit kiểu “fix formatting”. Sử dụng tổ hợp phím Ctrl+Shift+V trong VS Code để xem bản xem trước trực tiếp. Điều này giúp bạn phát hiện các bảng bị lỗi hoặc các khối mã bị lệch trước khi chúng được đưa lên nhánh chính.
Markdown không chỉ là một công cụ định dạng; nó là một cách để đảm bảo kiến thức kỹ thuật của bạn tồn tại lâu hơn thời gian bạn tham gia vào một dự án. Khi bạn viết tài liệu chuyên nghiệp, bạn không chỉ giúp ích cho nhóm hiện tại của mình. Bạn đang cứu chính mình trong tương lai khỏi hàng giờ bối rối khi quay lại xem code sau vài tháng.
