Documentation Conventions

Quy ước cho toàn bộ tài liệu Nemo12. Mọi tài liệu mới (do người hay AI viết) phải tuân theo file này.

1. Một nguồn duy nhất

• Chỉ có một canonical documentation source: thư mục docs/.
• Không tạo bản copy "cho AI" hay "cho human" riêng. Cùng một file phục vụ cả hai.
• Tài liệu đầu vào (bạn gửi thêm) được ghi nhận vào intake.md với ID SRC-xxx, sau đó nội dung được canonical hóa vào PRD/SDD tương ứng. Bản gốc không lưu lại thành file riêng để tránh hai nguồn sự thật.

2. Loại tài liệu và ID scheme

Prefix	Loại	Vị trí	Ví dụ
SRC-xxx	Source — tài liệu đầu vào được tiếp nhận	ghi trong intake.md	SRC-001
REQ-<nhóm>-xx	Requirement — yêu cầu đánh số	định nghĩa trong PRD	REQ-PLT-01
PRD-xxx	Product Requirements Document	product/	PRD-001
SDD-xxx	System Design Document	architecture/	SDD-001
QG-xxx	Quality Gate	quality/quality-gates.md	QG-003
ADR-xxx	Architecture Decision Record	architecture/decisions/ (khi cần)	ADR-001

Nhóm requirement hiện có: BRD (brand/ecosystem), LRN (learner), PAR (parent), MEN (mentor), SCH (schools), PLT (platform/tech), INT (learner intelligence), KNW (knowledge & quality), CUR (curriculum & storage).

3. Frontmatter schema (bắt buộc)

Mỗi document bắt đầu bằng YAML frontmatter:

---
id: sdd-002                      # ID duy nhất, lowercase
type: prd | sdd | quality | convention | index | adr
title: Learner Intelligence System
owner: platform                  # team/người chịu trách nhiệm
status: draft | active | deprecated
version: 0.1
last_reviewed: 2026-08-13        # ngày review gần nhất (absolute date)
sources: [SRC-003]               # tài liệu đầu vào mà file này canonical hóa
satisfies: [REQ-INT-01, REQ-INT-02]  # requirements mà file này thiết kế/đáp ứng
verified_by: [QG-005]            # quality gates kiểm chứng
ai_readable: true
---

Trường sources, satisfies, verified_by là xương sống của traceability — tooling và AI đọc từ đây; traceability.md là view tổng hợp cho con người.

4. Lifecycle

draft → active → deprecated

• draft: đang viết hoặc chờ tài liệu đầu vào bổ sung; chưa dùng làm căn cứ implement.
• active: đã review, là căn cứ cho implement.
• deprecated: giữ lại cho lịch sử, ghi rõ file thay thế.

Khi sửa nội dung đáng kể: tăng version, cập nhật last_reviewed.

5. Quy ước viết

• Tiếng Việt cho phần diễn giải, giữ nguyên thuật ngữ kỹ thuật tiếng Anh (learner model, evidence, workflow…).
• Diagram dùng Mermaid trong code fence (VitePress render được, AI đọc được, Git diff được). ASCII tree dùng cho cấu trúc thư mục.
• User story theo format: As a [Nemo/Marlin/Dolphin/...], I want [goal], so that [benefit] — kèm ID và acceptance criteria.
• Mỗi bảng requirement trong PRD có cột: ID, mô tả, priority (MUST/SHOULD/COULD), nguồn (SRC-xxx).
• Ngày tháng luôn viết tuyệt đối (2026-08-13), không viết "tuần trước".

6. Quy trình tiếp nhận tài liệu mới

Khi có tài liệu đầu vào mới:

1. Ghi một dòng vào intake.md: cấp SRC-xxx, ngày nhận, tóm tắt.
2. Xác định nội dung thuộc PRD nào / SDD nào — cập nhật file hiện có hoặc tạo file mới theo ID scheme.
3. Thêm/ cập nhật REQ-xxx trong PRD nếu tài liệu chứa yêu cầu mới.
4. Cập nhật frontmatter (sources, satisfies) của các file bị ảnh hưởng.
5. Cập nhật traceability.md — đánh dấu trạng thái SDD và Quality Gate.

7. Render

Docs được render bằng VitePress (sẽ nằm ở apps/docs/ trong monorepo, theo SDD-001). Cho tới khi scaffold, tài liệu vẫn đọc tốt dưới dạng plain Markdown trên Git — đây là yêu cầu thiết kế, không phải tình trạng tạm.