# 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:

1. Người mới không có tutorial ngắn dẫn qua một kết quả end-to-end.
2. Nhiều trang trộn rationale, lệnh vận hành và bảng tra cứu.
3. 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

1. Thêm tutorial theo một query có citation.
2. Thêm how-to riêng cho corpus, quality, deploy/rollback và tracing.
3. Thêm catalog để tìm tài liệu theo reader job và vai trò.
4. Thêm explanation ngắn cho mental model structured RAG.
5. Cập nhật `docs/README.md` làm cổng vào theo Diataxis.
6. 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.