duocthu/docs/documentation-policy.md

Chính sách và nguồn kiểm chứng tài liệu

Loại chính: Governance
Đối tượng: người viết và duyệt tài liệu

Nguồn sự thật

Khi thông tin mâu thuẫn, dùng thứ tự:

1. hành vi được test tự động xác nhận;
2. code và migration đang thực thi;
3. cấu hình deploy/workflow đang hoạt động;
4. tài liệu chuẩn trong docs/;
5. README cục bộ và docs-legacy/;
6. ghi chú, kế hoạch và slide.

Nguồn kiểm chứng theo chủ đề

Chủ đề	Nguồn chính
HTTP API	apps/ai-service/main.py, api/routes.py, api/dto.py
Runtime wiring	bootstrap.py, config.py
RAG/guardrail	rag/agent.py, rag/service.py, rag/answer.py
Retrieval	rag/routing.py, rag/sections.py, adapters/qdrant.py
Persistence	adapters/postgres.py, migrations/*.sql
Web/BFF	apps/web/app/api/chat/route.ts, shared types
Ingestion	ingestion/ingestion/cli.py, chunk và load modules
Infrastructure	infra/docker, production Compose, Caddy, Helm/ArgoCD
CI/CD	.github/workflows/*.yml
Hành vi	test suites và evals/production_manual_60.jsonl

Quy tắc cập nhật

• Không biến kế hoạch thành tính năng hoàn tất.
• Phân biệt “có code”, “được test”, “đã deploy” và “đang phục vụ traffic”.
• Mỗi thay đổi interface phải cập nhật file chuẩn liên quan trong cùng pull request.
• Lệnh trong tài liệu phải được chạy thử hoặc đánh dấu rõ phụ thuộc cloud/hạ tầng.
• Không ghi số test, corpus hoặc benchmark không có ngày/model/hash.
• Mỗi file giữ một công việc đọc chính dù có section hỗ trợ loại Diátaxis khác.
• Kiểm tra toàn bộ relative links sau khi đổi tên hoặc di chuyển.

Vòng đời

docs/ là nguồn tài liệu chuẩn. docs-legacy/ chỉ để tra lịch sử và raw notes; không được dùng để kết luận hành vi hiện tại nếu chưa đối chiếu code. Tài liệu hết hiệu lực phải được xoá hoặc ghi deprecated kèm link thay thế; không để hai file cùng tự nhận là canonical.