Docs đang thành API cho agent

Docs đang thành API cho agent

Blume không chỉ là framework docs mới. Nó là tín hiệu rằng tài liệu đang chuyển từ trang để người đọc sang bề mặt vận hành cho AI agent.

Có một kiểu đau rất quen trong team kỹ thuật: release xong tính năng, demo chạy ngon, rồi tới lúc viết docs thì cả phòng im như vừa bị gọi lên bảng kiểm tra miệng.

Dev bảo: “Để em bổ sung sau.”
PM bảo: “Có cần chi tiết vậy không?”
Agent thì đọc README cũ từ ba tháng trước rồi tự tin scaffold sai API.

Và thế là mình ngồi nhìn một framework docs tên Blume xuất hiện với lời hứa khá gọn: thả Markdown vào một folder, ra một site docs production-ready. Nhưng điểm đáng bàn không phải là “ồ, thêm một static site generator nữa”. Tín hiệu thị trường nằm ở chỗ khác: docs đang được thiết kế như dữ liệu vận hành cho AI, không chỉ là trang web cho con người đọc.

Nói thẳng ra thì: nếu team bạn vẫn xem tài liệu như bài tập về nhà nộp cuối sprint, agent của bạn sẽ học từ vở ghi lem nhem.

Sơ đồ minh họa cho bài Docs đang thành API cho agent

Sơ đồ tóm tắt ý chính của bài viết.

Tín hiệu lạ: Markdown bỗng được đối xử nghiêm túc trở lại

Mấy năm trước, Markdown thường bị xem là lớp nội dung đơn giản: viết README, changelog, vài trang hướng dẫn. Phần “xịn” nằm ở app, API, model, orchestration.

Nhưng nhìn các release gần đây sẽ thấy một đường dây khá rõ:

Ở đây, Markdown không còn là “file chữ cho tiện”. Nó đang thành định dạng trung gian giữa người viết, trang docs, search index, agent, và các tool tự động.

Với builder, đây là thay đổi incentive. Trước kia docs tốt giúp support đỡ mệt. Bây giờ docs tốt còn giúp agent code đúng hơn, RAG ít lạc hơn, onboarding nhanh hơn, và automation bớt đoán mò.

Bóc lớp Blume: không phải zero-config là không có kiến trúc

Blume tự định vị là zero-config documentation framework. Zero-config nghĩa là bạn có thể chạy được mà chưa cần viết cấu hình ban đầu. Nhưng builder thì đừng nghe chữ “zero” rồi nghĩ nó không có tradeoff.

Cách Blume hoạt động khá thú vị:

  1. CLI đọc blume.config.ts nếu có.
  2. Nó scan folder Markdown/MDX thành một content graph, tức cấu trúc quan hệ giữa các trang nội dung.
  3. Nó sinh một project Astro ẩn trong thư mục .blume/.
  4. Astro render trang qua một catch-all route, dùng component, generated data và override của bạn.
  5. Khi chạy lại, .blume/ được regenerate, nhưng chỉ rewrite file đã thay đổi để hot reload nhanh hơn.

Điểm mình thích ở đây không phải “ẩn Astro cho đỡ phiền”. Điểm hay là Blume chọn mô hình progressive control: ban đầu bạn chỉ thả nội dung vào; khi cần kiểm soát sâu hơn, bạn có thể blume eject để biến runtime thành app Astro riêng.

Đây giống một giáo án tốt: buổi đầu không bắt học viên đọc toàn bộ sách giáo khoa, nhưng nếu học lên cao vẫn có đường mở sách ra xem ruột bên trong.

Với team Việt Nam quy mô nhỏ, đây là một lựa chọn thực dụng. Bạn không muốn mất hai tuần dựng docs app, nhưng cũng không muốn bị khóa trong một hộp đen khi docs bắt đầu dính vào auth, versioning, custom components, hay pipeline search nội bộ.

Ai hưởng lợi, ai bị ép đổi cách làm?

Release kiểu Blume làm lợi cho ba nhóm.

Một là team product nhỏ nhưng release nhanh.
Nếu docs bắt đầu từ Markdown folder, dev có thể viết gần code hơn. Không cần một app boilerplate riêng chỉ để render tài liệu. Build ra static HTML cũng hợp với hosting đơn giản, cache dễ, ít runtime phải canh.

Hai là team đang xây AI assistant nội bộ.
Agent cần tài liệu có cấu trúc ổn định. Nếu docs site sinh ra navigation, search index, metadata, và content graph, bạn có nhiều điểm móc để đưa vào RAG. RAG là retrieval-augmented generation, hiểu ngắn là cho model tra tài liệu trước khi trả lời.

Ba là đội platform muốn chuẩn hóa mà không làm mọi người sợ.
Một folder Markdown dễ bán nội bộ hơn một framework nặng. Nếu mỗi repo đều có cách viết docs tương tự, automation về sau mới có đất chạy.

Ngược lại, ai bị ép đổi? Chính là những team đang để docs sống rải rác: một ít trong Notion, một ít trong README, một ít trong Slack, một ít trong trí nhớ của anh senior đang nghỉ phép.

Ví dụ cụ thể: giả sử team bạn có một SDK thanh toán. Docs hiện có README.md, vài trang Notion, và một file Postman export. Khi agent được giao viết integration sample, nó không biết endpoint nào mới nhất, field nào deprecated, lỗi nào retry được. Nếu gom API guide, changelog, migration note thành Markdown/MDX có cấu trúc, build ra docs site và index local, bạn đã biến tài liệu thành một “bảng điểm” rõ ràng hơn cho cả người lẫn máy: phần nào có, phần nào thiếu, phần nào stale.

Framework chọn docs stack: 4 câu hỏi trước khi nhảy vào tool

Đây là phần mình muốn bạn mang về. Đừng hỏi “Blume có hot không?”. Hỏi bốn câu này trước.

1. Docs của bạn phục vụ người đọc hay agent nữa?

Nếu chỉ cần handbook cho người dùng cuối, bạn ưu tiên UX đọc, search, theme, tốc độ tải.

Nếu docs còn được agent đọc, hãy ưu tiên cấu trúc ổn định: frontmatter, heading rõ, link nội bộ sạch, versioning, và output dễ index. Frontmatter là phần metadata ở đầu file Markdown, thường dùng để ghi title, description, tags.

2. Bạn cần static output hay runtime app?

Static HTML là trang được build sẵn, dễ deploy và ít rủi ro vận hành. Với docs public, đây thường là lựa chọn khỏe.

Runtime app phù hợp khi bạn cần logic động: permission theo user, search riêng theo workspace, analytics tùy biến sâu, hoặc nội dung sinh theo tài khoản.

Blume nghiêng về static-first, nhưng có đường eject sang Astro khi cần nhiều quyền kiểm soát hơn. Đây là điểm đáng để ghi vào quyết định kiến trúc.

3. Search của bạn chỉ để người bấm, hay để pipeline dùng?

Local search index là chỉ mục tìm kiếm build cùng site, chạy tại phía client hoặc static asset. Nó tốt cho docs vừa và nhỏ.

Nhưng nếu bạn muốn đưa docs vào RAG production, bạn sẽ cần pipeline riêng: chunking, embedding, ranking, eval câu trả lời, stale document detection. Blume giúp chuẩn hóa đầu vào, không thay thế toàn bộ lớp retrieval.

Chỗ này nhiều team hay nhầm: có search box không có nghĩa là có knowledge layer tốt cho agent.

4. Ai sẽ chịu trách nhiệm khi docs sai?

Tool chỉ làm docs dễ xuất bản hơn. Nó không tự đảm bảo nội dung đúng.

Nếu release note không được cập nhật, nếu migration guide thiếu case lỗi, nếu example code không chạy trong CI, agent vẫn học sai. Với docs AI-ready, bạn nên coi mỗi trang quan trọng như một test case nhẹ: có owner, có ngày cập nhật, có ví dụ chạy được.

Điều đáng giữ: docs như interface chính thức

Blume đáng để để ý vì nó đi cùng một hướng với Astryx và LiteParse: tài liệu đang trở thành một dạng interface.

Ba mảnh này nói cùng một chuyện: AI workflow tốt bắt đầu từ artifact sạch. Artifact là sản phẩm trung gian mà hệ thống dùng lại được: Markdown, schema, index, component metadata, command output.

Ngay cả Antidoom, dù ở tầng model, cũng cùng tinh thần “sửa đúng điểm nghẽn”. Doom loop là lỗi model lặp một đoạn cho tới khi hết context window; Antidoom nhắm vào token bắt đầu vòng lặp thay vì thay toàn bộ cách sampling. Bài học cho docs stack cũng vậy: đừng thay cả hệ thống chỉ vì docs lộn xộn. Hãy tìm điểm nghẽn: format, ownership, index, hay workflow review.

Điều nên bỏ qua: ảo tưởng AI-ready tự động

Cụm AI-ready rất dễ làm team chủ quan. Một docs framework có thể sinh site đẹp, nhưng không biến nội dung mơ hồ thành tri thức đáng tin.

Nếu bạn thử Blume trong một buổi chiều, mình sẽ làm gọn như sau:

# trong một repo thử nghiệm
mkdir docs
printf "# Getting Started\n\n## Install\n\nTODO\n" > docs/index.md
npx blume dev

Sau đó kiểm tra bốn thứ:

Nếu câu trả lời là “có” cho phần lớn, Blume đáng nằm trong shortlist. Nếu docs của bạn cần permission phức tạp, multi-tenant, hoặc search gắn chặt dữ liệu runtime, hãy coi Blume là lớp publishing, không phải toàn bộ platform.

Sau bài này, điều mình muốn bạn nghĩ khác là: đừng chọn docs tool vì nó dựng site nhanh; hãy chọn vì nó biến tài liệu thành interface ổn định cho cả người và agent.

Docs không còn là bài nộp cuối kỳ. Nó là đề cương môn học mà agent sẽ học thuộc — viết cẩu thả thì đừng ngạc nhiên khi nó trả bài sai.

---
Bụi Wire — nghiện đọc release notes lúc 2 giờ sáng

Nguồn tham khảo