Mở đầu — vì sao bài này quan trọng
Nếu bạn từng làm BA trong một dự án kéo dài hơn một năm, chắc chắn bạn đã từng gặp cảnh này: tài liệu spec nằm trên Confluence, file Word nằm trong email, sơ đồ vẽ trên draw.io rồi export ra PNG dán vào slide, còn version mới nhất thì… không ai biết nằm ở đâu. Lập trình viên đọc spec đời cũ rồi code sai, QA test theo một bản khác, còn bạn — người viết tài liệu — phải đi giải thích bằng miệng trong từng cuộc họp. Tài liệu bị "mục" (rot) chỉ sau vài sprint.
Documentation as Code (thường gọi tắt là Docs as Code) là cách tiếp cận giải quyết tận gốc vấn đề này. Triết lý rất đơn giản: hãy đối xử với tài liệu y hệt như đối xử với mã nguồn. Tài liệu được viết bằng định dạng văn bản thuần (plain text), lưu trong Git repo, review qua Pull Request, và build/publish tự động qua CI/CD. Nghe có vẻ là chuyện của developer, nhưng đây chính là kỹ năng giúp Technical BA trở nên đáng tin cậy gấp nhiều lần trong mắt đội kỹ thuật.
Tại sao bài này quan trọng với bạn? Vì khi spec của bạn sống trong cùng repo với code, nó luôn đồng bộ với phiên bản phần mềm tương ứng, không bao giờ "lệch pha". Vì khi bạn biết mở một Pull Request để sửa tài liệu, bạn nói cùng ngôn ngữ với developer và họ tôn trọng đầu việc của bạn hơn. Và vì trong các tổ chức kỹ thuật trưởng thành — fintech, ngân hàng số, công ty SaaS — Docs as Code đang dần trở thành chuẩn mặc định. Một Technical BA không biết khái niệm này sẽ bị bỏ lại phía sau.
Khái niệm cốt lõi
Bốn nguyên tắc nền tảng
Docs as Code không phải một công cụ cụ thể, mà là một tập nguyên tắc. Hãy nhớ bốn điểm sau, vì mọi thứ còn lại chỉ là chi tiết triển khai.
1. Plain text là nguồn chân lý (source of truth). Tài liệu được viết bằng Markdown, AsciiDoc hoặc reStructuredText — những định dạng văn bản thuần mà con người đọc được và máy diff được. Không phải file .docx nhị phân, không phải database ẩn của Confluence. Lý do: chỉ plain text mới cho phép Git so sánh từng dòng thay đổi.
2. Versioned cùng code. Tài liệu nằm trong Git, lý tưởng nhất là cùng repo với mã nguồn mà nó mô tả (hoặc một repo docs riêng nhưng vẫn dùng Git). Mỗi commit code có thể đi kèm commit tài liệu tương ứng. Khi bạn checkout về phiên bản v2.3, bạn nhận đúng tài liệu của v2.3.
3. Review qua Pull Request. Mọi thay đổi tài liệu đi qua cùng quy trình review như code: tạo branch, mở Pull Request (PR), người khác review, comment, duyệt rồi merge. Tài liệu được kiểm soát chất lượng trước khi xuất bản, có dấu vết ai sửa gì và vì sao.
4. Build và publish tự động qua CI/CD. Khi PR được merge vào nhánh chính, một pipeline CI/CD tự động build tài liệu Markdown thành một website tĩnh đẹp đẽ và deploy lên hosting. Không ai phải copy-paste hay bấm "Export" thủ công.
Markdown — định dạng nguồn
Markdown là trái tim của Docs as Code. Đó là cú pháp đánh dấu văn bản cực nhẹ: # cho tiêu đề, đậm, - cho gạch đầu dòng, dấu backtick cho code. Ưu điểm với BA:
- Học trong 15 phút, không cần biết lập trình.
- File
.mdđọc được ngay cả khi chưa render, không bị khóa vào phần mềm nào. - Diff trong Git rất sạch — reviewer thấy đúng câu nào bạn thêm, xóa, sửa.
MkDocs và các static site generator
Markdown thô thì khó đọc trên diện rộng. Đây là lúc các static site generator (công cụ sinh website tĩnh) xuất hiện. Phổ biến nhất trong giới Docs as Code:
- MkDocs (đặc biệt theme Material for MkDocs): viết bằng Python, cấu hình bằng một file
mkdocs.yml, biến thư mục Markdown thành website tài liệu có thanh tìm kiếm, mục lục, dark mode. Đây là lựa chọn số một cho team mới bắt đầu vì cực dễ cài. - Docusaurus (của Meta): mạnh về versioning tài liệu theo nhiều phiên bản sản phẩm, hợp với SaaS có nhiều version API.
- Antora, Sphinx: nặng đô hơn, dùng trong tổ chức lớn.
mkdocs serve để xem trước, push lên Git". Đội DevOps lo phần build và deploy.Vòng đời một thay đổi tài liệu
Hãy hình dung luồng hoàn chỉnh: Bạn tạo branch docs/update-payment-spec. Bạn sửa file payment-api.md thêm một trường mới vào request. Bạn commit, push, mở Pull Request. Tech Lead review, comment "trường currency nên ghi rõ là ISO 4217". Bạn sửa, push tiếp. Anh ấy approve, merge. Ngay lập tức pipeline CI/CD chạy: build MkDocs, kiểm tra link gãy, rồi deploy website tài liệu mới. Trong vòng vài phút, cả công ty thấy phiên bản spec mới nhất tại địa chỉ nội bộ. Toàn bộ quá trình có log, có người duyệt, có thể rollback.
Tình huống thực tế
Tình huống 1 — Fintech Singapore chuẩn hóa tài liệu API
Một công ty fintech tại Singapore (gọi là PayNexus) có 40 microservice và khoảng 25 developer. Trước đây tài liệu API nằm rải rác: vài team viết trên Confluence, vài team để README trong code, vài team chẳng viết gì. Khi đối tác tích hợp hỏi "endpoint hoàn tiền nhận tham số gì?", BA phải đi hỏi từng team, mất trung bình 2 ngày mỗi câu hỏi.
BA trưởng đề xuất chuyển sang Docs as Code. Họ tạo một repo developer-docs, dùng Material for MkDocs, và đặt quy tắc: mọi spec API phải viết bằng Markdown trong repo này, sửa qua PR. Mỗi PR thay đổi spec bắt buộc có ít nhất một developer của service liên quan approve. Pipeline GitLab CI build và publish lên docs.paynexus.internal mỗi khi merge.
Sau 3 tháng: thời gian trả lời câu hỏi tích hợp giảm từ 2 ngày xuống dưới 2 giờ, vì tài liệu luôn cập nhật và tìm kiếm được. Quan trọng hơn, vì spec nằm cùng quy trình PR với code, developer không còn coi viết tài liệu là việc "ngoài lề" — nó nằm trong định nghĩa "Done" của mỗi tính năng.
Bài học: Docs as Code không chỉ là công cụ, mà là một thay đổi văn hóa. Khi tài liệu đi qua cùng cổng kiểm soát như code, nó được coi trọng ngang code.
Tình huống 2 — Ngân hàng số Việt Nam và bài toán "spec lệch version"
Một ngân hàng số tại TP.HCM (giả định tên Bản Việt Digital) gặp sự cố nghiêm trọng: đội tích hợp đối tác đọc spec API thanh toán trên Confluence, code theo đó, nhưng khi lên production thì lỗi liên tục. Điều tra ra nguyên nhân: spec trên Confluence là phiên bản dự kiến cho release tháng 12, trong khi production đang chạy bản tháng 9. Confluence không có khái niệm "version gắn với release", nên không ai phân biệt được.
BA kỹ thuật của dự án quyết định dời spec API vào chính repo của từng service, theo mô hình Docs as Code, dùng Docusaurus vì nó hỗ trợ versioning tài liệu rất tốt. Mỗi khi service release version mới, tài liệu được "đóng băng" thành một version tương ứng (v1.0, v1.1...). Đối tác giờ vào trang docs, chọn đúng version đang chạy production, đọc đúng spec.
Con số sau 2 quý: số sự cố tích hợp do "đọc nhầm version spec" giảm 90%. Bonus bất ngờ: vì spec nằm trong Git, mỗi khi developer sửa code API mà quên sửa tài liệu, reviewer thấy ngay trong PR là "code đổi mà file .md không đổi" và nhắc sửa luôn.
Bài học: Tài liệu versioned cùng code giải quyết tận gốc vấn đề "spec lệch phiên bản phần mềm" — vấn đề mà mọi nền tảng wiki truyền thống đều bất lực.
Tình huống 3 — BA viết tài liệu nhưng không biết Git
Một BA ở công ty SaaS logistics (giả định GiaoNhanh) rất giỏi nghiệp vụ nhưng sợ Git. Khi team chuyển sang Docs as Code, chị tiếp tục viết spec trên Google Docs rồi nhờ developer "copy giúp vào repo". Kết quả: developer trở thành nút thắt cổ chai, tài liệu luôn trễ một nhịp, và mỗi lần copy lại phát sinh lỗi định dạng. Tệ hơn, vì chị không tham gia PR, chị không thấy được các comment review, dẫn đến hiểu lầm về yêu cầu.
Tech Lead ngồi với chị một buổi 90 phút, dạy đúng 5 lệnh Git cơ bản và cách dùng giao diện web của GitLab để sửa file .md trực tiếp trên trình duyệt (không cần cài gì trên máy). Sau đó chị tự tạo branch, sửa Markdown ngay trên web, mở PR. Vai trò developer-trung-gian biến mất.
Bài học: Rào cản lớn nhất của Docs as Code với BA là tâm lý "Git là của developer". Thực tế bạn chỉ cần một nhóm nhỏ thao tác, và phần lớn có thể làm ngay trên giao diện web. Đừng để nỗi sợ công cụ ngăn bạn sở hữu tài liệu của mình.
Hướng dẫn từng bước
Đây là lộ trình thực dụng để bạn — một Technical BA — bắt đầu áp dụng Docs as Code, dù bạn chưa từng chạm Git.
Bước 1 — Nắm Markdown trong một buổi. Học cú pháp cơ bản: tiêu đề #, danh sách -, bảng, link, code block, in đậm/nghiêng. Dùng một trình soạn thảo có preview như VS Code, Typora, hay Obsidian để vừa gõ vừa thấy kết quả. Đây là kỹ năng nền, mất nửa ngày.
Bước 2 — Làm quen Git ở mức tối thiểu. Bạn cần hiểu 4 khái niệm: repo (kho chứa), branch (nhánh làm việc riêng), commit (lưu một mốc thay đổi), pull request (đề nghị gộp thay đổi). Bạn KHÔNG cần thành thạo command line — giao diện web của GitHub/GitLab cho phép tạo branch, sửa file, mở PR hoàn toàn bằng chuột.
Bước 3 — Thống nhất cấu trúc thư mục tài liệu. Cùng team định nghĩa nơi tài liệu sống: cùng repo code (gần code nhất, hợp với spec kỹ thuật) hay repo docs riêng (hợp với tài liệu nghiệp vụ liên service). Quy ước thư mục rõ ràng: /docs/api/, /docs/business-rules/, /docs/diagrams/.
Bước 4 — Dựng static site generator. Nhờ DevOps cài MkDocs với theme Material. Bạn chỉ cần biết: chỉnh file mkdocs.yml để thêm trang vào menu, chạy mkdocs serve để xem trước ở localhost:8000. Phần lớn việc cấu hình là một lần.
Bước 5 — Thiết lập quy trình review qua PR. Đặt quy tắc nhánh chính (main) được bảo vệ: không push trực tiếp, mọi thay đổi qua PR, cần ít nhất một approve. Với spec kỹ thuật, người approve nên là developer/Tech Lead của phần liên quan để đảm bảo tính chính xác.
Bước 6 — Tự động hóa build và publish bằng CI/CD. Nhờ DevOps tạo pipeline: khi merge vào main, tự build MkDocs và deploy lên hosting nội bộ (hoặc GitHub Pages). Thêm bước kiểm tra link gãy (link checker) và lint Markdown để bắt lỗi định dạng tự động.
Bước 7 — Đưa "cập nhật tài liệu" vào Definition of Done. Đây là bước quyết định thành bại. Quy ước: một tính năng chỉ "Done" khi tài liệu tương ứng đã được cập nhật trong cùng đợt thay đổi. Reviewer code cũng kiểm luôn tài liệu. Đây là cơ chế chống "doc rot" mạnh nhất.
Lỗi thường gặp & mẹo
Lỗi 1 — Bê nguyên Word/Confluence vào rồi gọi đó là Docs as Code. Nhiều team chỉ export PDF dán vào Git và tưởng đã xong. Sai. Bản chất là plain text diff được. File nhị phân trong Git không cho bạn review từng dòng, mất trọn giá trị. Mẹo: nếu nội dung không diff được theo dòng, nó chưa phải Docs as Code.
Lỗi 2 — Tài liệu và code ở hai thế giới tách rời. Nếu repo docs nằm riêng và không ai bắt buộc cập nhật song song, tài liệu vẫn "mục" như cũ, chỉ là mục bằng Markdown. Mẹo: gắn cập nhật tài liệu vào Definition of Done và để reviewer code nhắc.
Lỗi 3 — BA né tránh Git, đẩy hết cho developer. Như tình huống 3, điều này tạo nút thắt cổ chai và khiến bạn mất quyền sở hữu tài liệu. Mẹo: học 5 lệnh Git hoặc dùng giao diện web. Đầu tư 2 giờ, hưởng lợi cả sự nghiệp.
Lỗi 4 — Over-engineering ngay từ đầu. Team mới mà đã đòi Antora đa repo, đa version, custom plugin... rồi bỏ cuộc vì phức tạp. Mẹo: bắt đầu với MkDocs Material đơn giản nhất, một repo, một version. Mở rộng khi thật sự cần.
Lỗi 5 — Quên kiểm tra chất lượng tự động. Không có link checker, không lint, tài liệu đầy link gãy và lỗi cú pháp. Mẹo: thêm bước kiểm tra vào CI ngay từ đầu — rẻ và cứu bạn khỏi xấu hổ.
Mẹo vàng cho BA: Dùng Mermaid để vẽ sequence diagram và flowchart bằng text ngay trong Markdown. Sơ đồ của bạn sẽ versioned, diff được, và không bao giờ lệch khỏi mô tả văn bản đi kèm — điều mà file PNG export từ draw.io không bao giờ làm được.
Bài tập thực hành
- Viết một spec bằng Markdown. Chọn một API hoặc business rule bạn đang phụ trách, viết lại thành file
.mdvới tiêu đề, bảng tham số, và ít nhất một code block ví dụ request/response. Mở bằng VS Code để xem preview.
- Vẽ sơ đồ bằng Mermaid. Chuyển một sequence diagram bạn từng vẽ trên draw.io thành cú pháp Mermaid trong Markdown. So sánh cảm giác: sửa text dễ hay sửa hình dễ hơn khi yêu cầu thay đổi?
- Thực hành luồng PR trên web. Tạo một repo miễn phí trên GitHub, thêm file Markdown, rồi tạo branch mới, sửa file qua giao diện web, mở Pull Request, tự review và merge. Quan sát phần "Files changed" hiển thị diff thế nào.
- Thiết kế cấu trúc tài liệu. Phác thảo cây thư mục
/docscho một dự án bạn biết: đâu là api, business rules, diagrams, ADR. Giải thích vì sao bạn để spec kỹ thuật cùng repo code còn tài liệu nghiệp vụ liên service ở repo riêng.
- Soạn quy tắc Definition of Done. Viết một đoạn 5 dòng quy định "khi nào một tính năng được coi là hoàn thành về mặt tài liệu" để đề xuất cho team. Đây là deliverable thực sự bạn có thể mang vào công ty.
Tóm tắt
Documentation as Code là cách đối xử với tài liệu y như mã nguồn: viết bằng plain text (Markdown), versioned trong Git, review qua Pull Request, và build/publish tự động qua CI/CD. Bốn nguyên tắc nền tảng — plain text là nguồn chân lý, versioned cùng code, review qua PR, tự động hóa publish — giải quyết tận gốc hai nỗi đau kinh điển: tài liệu "mục" theo thời gian và spec lệch phiên bản phần mềm.
Công cụ trung tâm gồm Markdown làm định dạng nguồn, Mermaid cho sơ đồ-dưới-dạng-text, và static site generator như MkDocs (Material), Docusaurus để biến Markdown thành website tài liệu đẹp, tìm kiếm được. Các tình huống thực tế từ fintech Singapore, ngân hàng số Việt Nam và công ty logistics cho thấy giá trị không nằm ở công cụ, mà ở thay đổi văn hóa: khi tài liệu đi qua cùng cổng kiểm soát như code, nó được coi trọng ngang code, và "cập nhật tài liệu" trở thành một phần của Definition of Done.
Với bạn — Technical BA — đây là kỹ năng tạo khác biệt rõ rệt. Bạn không cần thành thạo lập trình; chỉ cần nắm Markdown, hiểu vài khái niệm Git, và dám sở hữu tài liệu của mình trong luồng làm việc của đội kỹ thuật. Hãy bắt đầu nhỏ với MkDocs một repo một version, gắn tài liệu vào Definition of Done, và mở rộng khi cần. Đó là con đường để spec của bạn luôn sống, luôn đúng, và luôn được tôn trọng.