105 lines
4.1 KiB
Markdown
105 lines
4.1 KiB
Markdown
# 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.
|