DOL Kid LMS - Learning Doc Rules

DOL Kid - Learning Doc Rules

Purpose

• Giữ cho các doc của KID Learning / LMS / Exercise ngắn, ổn định, và không trộn sai vai trò.
• Giúp AI và team viết thêm doc mà không tạo ra taxonomy rác hoặc flow giả.

Core Writing Rules

• Role before detail
  • Mỗi file phải trả lời rõ nó sở hữu câu hỏi gì trước khi đi vào chi tiết.
• One file, one level
  • Không trộn capability map, launcher, authoring logic, interaction catalog, và screen concept vào cùng một file.
• Current canon vs near-term expansion
  • Nếu một lane chưa có flow/detail canon, ghi rõ nó là near-term expansion hoặc TBD, không viết như thể đã active đầy đủ.
• Do not guess missing product logic
  • Phần nào chưa chốt thì giữ placeholder hoặc TBD.
• Wrapper is not a lane
  • story, theme, mini game, character, video/rive, fish/bubble/flower không tự động trở thành product lane.
• Shared capability stays shared
  • pronunciation, vocabulary notebook, hoặc các utility tương tự không nên bị viết thành practice type ngang hàng nếu vai trò thực tế là lớp hỗ trợ dùng chung.

KID Product Rules

• Offline-course companion
  • Mọi lane học của KID mặc định phải neo vào khóa offline, lesson objective, hoặc homework need.
• Course-first
  • Không viết doc theo hướng self-learning app độc lập nếu canon hiện tại vẫn là course-linked.
• Root placeholder before public site
  • Nếu current phase chưa build public DOL Kid site, không mô tả domain root như home sản phẩm đầy đủ; ưu tiên entry narrative cho KID LMS.
• Evaluation separate from reinforcement
  • Testing không trộn vai trò với Exercise hoặc guided learning.
• Submission separate from coaching
  • Assignment W/S là lane nộp bài; guided writing/speaking là lane luyện cùng học viên.
• Child-friendly, parent-readable
  • Ngôn ngữ và logic phải đủ đơn giản cho trẻ dùng, nhưng phụ huynh vẫn hiểu bài này đang để làm gì.
• Home tabs are intent buckets
  • Overview, Khóa học, Kho đề, Lịch học, Thành tích, Kỷ niệm là các bucket theo ý định sử dụng; không copy-paste cùng một loại content sang nhiều tab chỉ để “đủ nội dung”.
• Home stays lightweight
  • LMS Home không thay vai trò của Parent Dashboard, Course Detail, hay teacher reporting.
• Home summarizes, tabs specialize
  • summary tổng quát có thể nằm ở Home, nhưng stats chi tiết phải quay về đúng tab owner.
• One card, one question
  • Mỗi card/cluster trên LMS Home chỉ nên trả lời 1 câu hỏi chính; nếu một block bắt đầu làm nhiều việc, phải tách block hoặc chuyển nội dung về đúng tab owner.
• Allocation specs for dense surfaces
  • Khi một surface có nhiều tab hoặc nhiều organism dễ trùng payload như LMS Home, Course Detail, Kho đề, Exercise Home, nên có một Content Allocation canon ngắn để khóa must show / may show / must not show.
• Schedule tab is schedule-only
  • Lịch học không mang breakdown nội dung buổi học hoặc thống kê khóa học.
• Overview previews, not duplicates
  • Overview có thể preview Khóa học, Lịch học, Thành tích, nhưng không render lại nguyên bản full content của các tab đó.
• Overview to-do is contextual, not a backlog
  • Việc cần làm của Overview chỉ được surface các task ưu tiên theo bối cảnh hiện tại như lesson follow-up, assignment due, test due, hoặc item đang dở; không biến thành full task manager.
• Overview snapshots are condensed signals
  • Snapshot trong Overview chỉ được nhắc tín hiệu đáng chú ý nhất của tab owner; không copy full payload của Khóa học, Lịch học, Thành tích, Learning Stats, hoặc Kỷ niệm.
• Bank lane is not a course lane
  • Kho đề / Test Bank là library tự luyện theo level; không mô tả nó như homework lane hoặc tab con của Course Detail.
• Asset type is not discovery surface
  • Online Test là loại bài / asset type; Kho đề / Test Bank là nơi chứa và cho user chọn các asset đó để tự luyện.
• Learner stats is a secondary view
  • Learning Stats là view phụ của LMS Home, không phải top-level tab mới.
• Stats reflect, achievements recognize
  • Learning Stats dùng để nhìn lại tiến độ; Thành tích dùng để badge/certificate/vinh danh.
• Learner stats stays lightweight
  • Không đổ teacher reporting, class leaderboard, attendance sâu, hay operational analytics vào Learning Stats.

Exercise-specific Rules

• Pattern is ingredient, not product
  • Selection, Matching, Speaking, Logic game là nguyên liệu biên soạn bài.
• Exercise is an authored bundle
  • Một bài exercise là một question set có mở đầu, phần luyện chính, và kết thúc rõ.
• One primary learning target
  • Một bài không nên ôm nhiều mục tiêu ngang hàng.
• Dominant + support pattern
  • Ưu tiên 1 dominant pattern family và tối đa 1-2 support pattern family.
• Completion is bundle-level
  • Không coi một pattern riêng lẻ là xong bài nếu question set còn chưa kết thúc.

File-type Rules

• Capability Map
  • Dùng để chốt bức tranh sản phẩm và boundary giữa các lane.
• Overview
  • Dùng để chốt role, scope gate, core logic, non-goals.
• Launcher
  • Chỉ mô tả entry layer hiện hành; không đại diện cho toàn bộ capability map nếu chưa route-expand.
• Authoring Logic
  • Chỉ mô tả cách biên soạn bài từ nhiều question/pattern.
• Interaction Catalog
  • Chỉ chuẩn hóa pattern và naming, không thay vai trò của product model.
• Concept / Screen Doc
  • Chỉ dùng khi logic product đã tương đối rõ.

Update Discipline

• Khi thêm một capability mới:
  • chốt ở Capability Map trước.
• Chỉ cập nhật Practice Launcher khi capability đó thật sự là current entry type.
• Chỉ cập nhật Sitemap khi route/state của capability đó đã được quyết định.
• Khi thêm doc canon mới:
  • nối tối thiểu vào entry overview,
  • context router,
  • và benchmark nếu cần truy xuất ổn định.
• Nếu doc cũ đã lệch vai trò:
  • sửa ngắn gọn hoặc đổi note phạm vi,
  • không tạo thêm doc mới chỉ để vá sự mâu thuẫn cũ.

Non-goals

• Không biến guideline thành checklist quá dài.
• Không dùng file này để thay product canon.
• Không mô tả implementation, schema, hay runtime contract ở đây.

Change log

• 2026-03-24: Bổ sung rule one card, one question để khóa content allocation cho LMS Home và các lần build/concept sau.
• 2026-03-24: Bổ sung rule cho Learning Stats để khóa boundary giữa progress reflection, Thành tích, và Parent Dashboard.
• 2026-03-23: Bổ sung rule root placeholder before public site để tránh AI/doc drift sang public-home-first khi current phase vẫn ưu tiên KID LMS.
• 2026-03-19: Tạo bộ rule ngắn cho KID Learning docs để tách đúng capability map, launcher, authoring logic, interaction catalog, và shared capability.