Tài liệu sống cùng repo

Mèo con đã biết dựng và vẽ C4 đẹp. Nhưng trong công ty thật, một câu hỏi lớn còn đó: tài liệu sống ở đâu? Cảnh quen thuộc: sơ đồ nằm trong một slide cũ, tài liệu yêu cầu ở Confluence, code ở Git - và cả ba lệch nhau sau vài tháng.

• ▸Tài liệu tách rời code đổi chậm hơn code, nên mau lạc hậu.
• ▸Mỗi phòng ban giữ một bản "sự thật" riêng - CEO thấy một kiểu, dev thấy kiểu khác.
• ▸Khi tài liệu và code không khớp, người ta ngừng tin tài liệu - rồi ngừng đọc.

Bài Diagrams as code đã chữa được phần sơ đồ. Giờ ta mở rộng ý đó ra toàn bộ tài liệu.

Ý tưởng docs-as-code: đặt tài liệu ngay trong repo, viết bằng Markdown (và Mermaid cho sơ đồ), rồi để nó hưởng mọi thứ tốt của code.

• ▸Cùng repo với code: đổi code thì cập nhật tài liệu trong CÙNG một Pull Request.
• ▸Version theo Git: tài liệu có lịch sử, biết ai đổi gì, khi nào, vì sao.
• ▸Review qua PR: tài liệu được góp ý như code, không trôi nổi.
• ▸Một nguồn sự thật: mọi vai trò mở cùng một chỗ, không còn "bản nào mới nhất?".

Một cách tổ chức gọn gàng, đủ chỗ cho cả tài liệu kiến trúc lẫn nghiệp vụ:

repo/
├── README.md            # diem vao: ai doc gi bat dau tu dau
├── src/                 # ma nguon
└── docs/
    ├── architecture/    # so do C4 (Mermaid/Structurizr)
    │   ├── context.md
    │   ├── container.md
    │   └── component-api.md
    ├── ba/              # tai lieu Business Analysis
    │   ├── user-stories.md
    │   ├── acceptance-criteria.md
    │   └── glossary.md   # tu dien thuat ngu chung
    └── adr/             # Architecture Decision Records
        ├── 0001-chon-postgresql.md
        └── 0002-tach-service-thanh-toan.md

• ▸architecture/: sơ đồ C4 các mức, viết bằng Mermaid để render thẳng trên GitHub.
• ▸ba/: tài liệu nghiệp vụ - user story, tiêu chí chấp nhận, và glossary (từ điển thuật ngữ chung).
• ▸adr/: nhật ký quyết định, đánh số tăng dần, không xoá quyết định cũ.

Tài liệu hay thiếu nhất là lý do. Sáu tháng sau, không ai nhớ vì sao chọn PostgreSQL thay vì MongoDB. ADR (Architecture Decision Record) giải quyết đúng chuyện đó - mỗi quyết định một file ngắn:

# 1. Chon PostgreSQL lam co so du lieu chinh

## Trang thai
Da chap nhan (2026-06-12)

## Boi canh
He thong vi dien tu can giao dich nhat quan (ACID) va bao cao quan he.
Doi da quen SQL.

## Quyet dinh
Dung PostgreSQL cho du lieu chinh.

## He qua
- Loi: giao dich ACID, kieu du lieu phong phu, cong dong lon.
- Danh doi: can ke hoach sharding neu sau nay tai rat lon.

Đây là điều biến repo docs thành ngôn ngữ chung của cả công ty. Mỗi vai trò vào cùng một chỗ, đọc đúng tầng của mình:

Và vì Mermaid render thẳng trên GitHub, ngay cả người không lập trình cũng thấy được sơ đồ như thế này:

Giờ tài liệu đã có nhà đúng chỗ - cạnh code, version được, ai cũng đọc. Nhưng viết hết chúng bằng tay thì tốn công. Đây là lúc một trợ thủ bước vào.