DOL Kid UX Documentation Guidelines

DOL Kid - UX Documentation Guidelines

Purpose

• Chuẩn hóa cách viết tài liệu UX cho DOL Kid để team và AI có thể tái sử dụng nhất quán.
• Giữ tài liệu ngắn gọn, dễ đọc, không sa đà kỹ thuật.
• Ngăn AI trộn guest intro với guardian-managed post-login.

Reusable writing rules

1. Surface split rule

• Home & Discovery chỉ giữ guest intro / discovery / auth handoff.
• Parent Experience giữ post-login dashboard / progress / reporting / multi-child.
• Identity & Access giữ ownership / child context / continuity.
• Learning Experience giữ lane học thật của bé.

2. User-first rule

• Mỗi tài liệu phải trả lời rõ: user là ai, user cần gì, user làm gì tiếp theo.

3. Parent-primary audience rule

• Với DOL Kid, pre-login có thể nói với cả bé và phụ huynh.
• Nhưng decision logic, CTA chính, và trust framing phải ưu tiên phụ huynh.

4. One-core-goal rule

• Mỗi file chỉ có một mục tiêu chính; tránh nhồi nhiều mục tiêu ngang nhau.

5. Simple-language rule

• Viết câu ngắn, từ đơn giản, trực tiếp.
• Tránh thuật ngữ kỹ thuật khi không cần.

6. Action clarity rule

• Mỗi màn hoặc khối nội dung chỉ có 1 CTA chính.
• CTA dùng động từ rõ nghĩa: Xem lộ trình, Cho bé xem demo, Tạo tài khoản cho bé, Xem tiến độ.

7. Guest-to-dashboard handoff rule

• Home docs phải dừng ở mức sau login đi đâu.
• Không mô tả sâu dashboard của phụ huynh ngay trong home doc.
• Nếu cần nói về sau login, chỉ nêu boundary và trỏ sang Parent Experience.

8. Multi-child completeness rule

• Bất kỳ doc nào về parent dashboard phải cover tối thiểu:
  • 0 bé,
  • 1 bé,
  • nhiều bé.
• Không giả định mặc định chỉ có một child.

9. Learning progression rule

• Khi mô tả learning lane, đi từ nhiệm vụ gần nhất sang hoạt động tiếp theo.
• Không ép mọi doc KID phải kể lại toàn bộ tuyến lesson -> test -> certificate nếu file không sở hữu lane đó.

10. Login-gate rule

• Không ép login ở bước khám phá.
• Chỉ yêu cầu login khi cần lưu tiến độ hoặc mở nội dung full.
• Sau login phải quay lại đúng ngữ cảnh trước đó.

11. State coverage rule

• Tối thiểu phải mô tả: loading, empty, error, success.
• Mọi state phải có hành động tiếp theo, không dead-end.

12. No stale hub rule

• Không dùng lại khái niệm self-study hub cho post-login KID nếu doc đang nói về guardian-managed dashboard.
• Nếu gặp ngôn ngữ cũ kiểu logged-in learner home, phải kiểm tra lại ownership trước khi giữ.

Content hygiene rules

1. Keep / Update / Remove decision

• Keep: nội dung còn đúng và dùng lại được.
• Update: nội dung đúng hướng nhưng cần làm rõ hoặc đổi ngữ cảnh.
• Remove: nội dung lỗi thời, trùng lặp, hoặc làm rối flow.

2. No duplicate blocks

• Không lặp lại cùng một ý ở nhiều file nếu không có giá trị mới.
• Ưu tiên link chéo thay vì copy lại toàn bộ.

3. No stale placeholder

• Khi đã có nội dung dùng được, bỏ nhãn placeholder để tránh hiểu sai trạng thái tài liệu.

Iterative loop protocol

1. Xác định mục tiêu UX chính và phạm vi file.
2. Xác định file đang viết thuộc Home & Discovery, Parent Experience, Identity & Access, hay Learning Experience.
3. Viết bản nháp ngắn theo các rule ở trên.
4. Tự kiểm tra theo checklist DoD.
5. Cắt gọn nội dung thừa, làm rõ CTA và handoff.
6. Kiểm tra lại tính nhất quán giữa các file liên quan.
7. Chốt bản cuối và cập nhật changelog.

Definition of Done (DoD)

• File có mục tiêu rõ, phạm vi rõ.
• Có flow người dùng từ entry đến next step.
• Có login / handoff rule phù hợp với ngữ cảnh.
• Có state coverage cơ bản.
• Không lẫn guest intro với parent dashboard.
• Nếu là doc phụ huynh, đã cover 0/1/n children.
• Không có đoạn placeholder dư thừa.
• Không có nội dung kỹ thuật không cần thiết cho UX docs.

References

• ./HOME_KID_00_Overview.md
• ./HOME_KID_Home_Information_Architecture.md
• ./HOME_KID_Home_Navigation_Conversion_Flow.md
• ../Parent Experience/KID_Parent_Learning_Management_Dashboard.md
• ../Parent Experience/KID_Parent_Experience_00_Overview.md
• .agent/rules/rule-domain-split-guard.md

Change log

• 2026-03-08: Bổ sung rule tách guest intro khỏi parent-managed post-login.
• 2026-03-08: Thêm guideline multi-child completeness và no stale hub để AI không quay lại mô hình cũ.