Audit kiến trúc tài liệu theo Diataxis

Phân loại

Loại tài liệu: Explanation kèm inventory.

Reader job: hiểu bộ tài liệu được tổ chức thế nào và nên đọc gì cho từng mục tiêu.

Giả định: code và cấu hình runtime là nguồn sự thật; tài liệu không được dùng để chứng minh một hành vi nếu code đã thay đổi.

Chẩn đoán

Bộ tài liệu hiện tại mạnh về Explanation và Reference. Các trang 00–29 mô tả gần như toàn bộ kiến trúc, ingestion, RAG, API, vận hành và giới hạn. Tuy nhiên ba vấn đề làm người đọc khó sử dụng:

Người mới không có tutorial ngắn dẫn qua một kết quả end-to-end.
Nhiều trang trộn rationale, lệnh vận hành và bảng tra cứu.
Tên file đánh số theo thành phần, chưa thể hiện reader job; người đọc phải biết kiến trúc trước khi biết nên mở trang nào.

Kiến trúc mục tiêu

Reader job	Nhóm	Lời hứa
Học qua thực hành	`tutorials/`	Đi theo một đường an toàn để hiểu một lượt RAG
Hoàn thành công việc	`how-to/`	Thực hiện setup, kiểm thử, ingestion, deploy hoặc điều tra
Tra cứu chính xác	Các trang reference hiện hành	Tìm endpoint, config, schema, reason code và giới hạn
Hiểu thiết kế	Các trang explanation hiện hành	Hiểu kiến trúc, trade-off và guardrail

Không di chuyển hàng loạt các file 00–29, vì chúng đã có nhiều backlink từ code, ADR và runbook. Lớp Diataxis mới bổ sung điều hướng và các reader job còn thiếu; việc tách vật lý chỉ nên làm khi có redirect/link checker trong CI.

Phân loại bộ tài liệu hiện hành

Tutorial

tutorials/first-grounded-query.md

How-to

how-to/rebuild-and-publish-corpus.md
how-to/run-tests-and-evals.md
how-to/deploy-and-rollback.md
how-to/trace-a-request.md
23-local-development.md
24-production-operations.md
25-troubleshooting.md

Reference

01-repository-structure.md
06-document-model-and-chunking.md
07-indexing-and-storage.md
12-api-architecture.md
14-data-stores.md
15-configuration.md
17-observability.md
18-testing.md
26-known-limitations.md
29-glossary.md
reference/documentation-catalog.md

Explanation

00-project-overview.md
02-system-architecture.md
03-data-flow.md
04-ingestion-pipeline.md đến 11-generation-and-grounding.md
13-frontend-architecture.md
16-security.md
19-rag-evaluation.md
20-deployment.md đến 22-ci-cd.md
27-technical-debt.md, 28-roadmap-from-code.md
explanation/why-structured-rag.md
pipeline-tu-pdf-den-chatbot-production.md

Một số trang có nội dung phụ thuộc loại khác. Ví dụ 24-production-operations.md là how-to chính nhưng chứa bảng incident reference; pipeline-tu-pdf... là explanation chính nhưng có lệnh tái hiện. Chúng được giữ vì đang phục vụ handoff kỹ thuật; các how-to mới trích riêng đường thao tác để người vận hành không phải đọc toàn bộ narrative.

Các thay đổi được áp dụng

Thêm tutorial theo một query có citation.
Thêm how-to riêng cho corpus, quality, deploy/rollback và tracing.
Thêm catalog để tìm tài liệu theo reader job và vai trò.
Thêm explanation ngắn cho mental model structured RAG.
Cập nhật docs/README.md làm cổng vào theo Diataxis.
Sửa các claim drift được xác minh trực tiếp từ code/workflow hiện tại.

Checklist duy trì

Mỗi trang mới có một reader job chính.
How-to có prerequisites, verification và recovery.
Reference ghi rõ default, limit và source-of-truth.
Explanation không giả làm hướng dẫn thao tác.
Số liệu có ngày hoặc artifact nguồn.
Link tương đối được kiểm tra trước commit.
Khi code và docs mâu thuẫn, sửa docs; không dùng docs cũ để phủ định code.

4.1 KiB Raw Blame History Unescape Escape