Domains - Docs Content Placement Map

Domains1.427 words7 min read

active

Purpose

Chốt vị trí phù hợp cho từng nhóm tài liệu trong docs/** theo nội dung thực tế.
Giúp team và AI biết đâu là canonical, đâu là support, và đâu là artifact.

Placement Classes

canonical
- nơi nên đọc và cập nhật trước khi viết mới.
support
- tài liệu hỗ trợ routing, kế hoạch, template, hoặc vận hành.
artifact
- output máy sinh hoặc metadata, không phải nơi viết narrative sản phẩm.

Repo-level Placement

Current location	Content meaning	Canonical home	Class	Current rule
`docs/Domains/**`	Narrative theo domain và workspace	`docs/Domains/**`	`canonical`	Domain-first entry cho `DOL English`, `DOL Academy`, `DOL Kid`.
`docs/Shared/**`	Tài sản dùng chung toàn hệ	`docs/Shared/**`	`canonical`	Chỉ dùng cho cross-domain canon hoặc shared workspace.
`docs/README.md`	Hướng dẫn layout và placement ở cấp repo	`docs/README.md`	`support`	Entry onboarding cho cấu trúc tài liệu, không phải narrative sản phẩm.
`docs/Domains/DOL English/UX Design/**`	Current UX logic, owner docs, feature masters, và surface/page behavior của DOL English	`docs/Domains/DOL English/UX Design/**`	`canonical`	Với DOL English, đây là lane chính để đọc và cập nhật UX logic.
`docs/Domains/DOL English/Product Discovery/**`	Change log, decision trail, workshop flow, state, và extraction supporting cho DOL English	`docs/Domains/DOL English/Product Discovery/**`	`support`	Không phải owner lane của `current UX logic`; dùng để giữ lịch sử, rationale, và sync-back supporting.
`docs/Domains/DOL English/Feature Package/**`	Feature framing và capability packaging supporting cho DOL English	`docs/Domains/DOL English/Feature Package/**`	`support`	Không phải lane chính để build/update `current UX logic`; chỉ dùng khi cần framing hoặc packaging supporting.
`docs/Shared/Shared Capabilities/Ecosystem Experience/**`	UX north-star của cả ecosystem	`docs/Shared/Shared Capabilities/Ecosystem Experience/**`	`canonical`	Ecosystem-level canon nằm hoàn toàn ở shared capability này.
`docs/Shared/Design System/**`	Design system canon, guideline, và audit hiện trạng	`docs/Shared/Design System/**`	`canonical`	Shared canon; không clone full design system theo domain.
`docs/Shared/Knowledge Base/**`	Knowledge content đã biên tập và imported mirror	`docs/Shared/Knowledge Base/**`	`canonical`	Nội dung knowledge sống trực tiếp trong workspace này.
`docs/Shared/Operations/**`	Runbook và workflow vận hành repo	`docs/Shared/Operations/**`	`canonical`	Runbook chi tiết sống trực tiếp trong workspace này.
`docs/Command/**`	Glossary, principles, templates, tài liệu nền dùng lại	`docs/Command/**`	`support`	Repo-wide reference layer, không thuộc riêng domain nào.
`docs/context/**`	Router cards cho AI/tools	`docs/context/**`	`support`	Không chứa product narrative; chỉ điều hướng.
`docs/plans/**`	Working plans và migration plans	`docs/plans/**`	`support`	Dùng cho implementation planning, không phải canon sản phẩm.
`docs/tmp/**`	Runtime artifacts, reports, generated outputs	`docs/tmp/**`	`artifact`	Không dùng làm canonical context.
`docs/.wiki/**`	Metadata cho wiki ingestion	`docs/.wiki/**`	`artifact`	Machine-managed.
`docs/heading-id-map.json`	Heading registry cho tooling/wiki	`docs/heading-id-map.json`	`artifact`	Machine-managed.

Current Folder Decisions

Top-level folder	Decision now	Why
`docs/Domains`	`keep as canonical`	Đây là trục chính cho narrative sản phẩm theo domain và workspace.
`docs/Shared`	`keep as canonical`	Đây là trục chính cho tài sản cross-domain và workspace dùng chung.
`docs/Command`	`keep as support lane`	Đây là repo-wide principles/templates/glossary, không phải domain narrative và cũng không phải shared capability.
`docs/context`	`keep as support lane`	Router cho AI/tools, không nên trộn với narrative docs.
`docs/plans`	`keep as support lane`	Working plans có vai trò riêng, không phải canon sản phẩm.
`docs/tmp`	`keep as artifact lane`	Runtime artifacts, không phải narrative.
`docs/.wiki`	`keep as artifact lane`	Metadata phục vụ wiki/tooling, không phải content cho người đọc.

Retired Root Folders

docs/UX Design/** -> đã retire; ecosystem UX canon nằm tại docs/Shared/Shared Capabilities/Ecosystem Experience/**.
docs/Product Discovery/** -> đã nhập vào docs/Domains/DOL English/Product Discovery/**.
docs/Feature Package/** -> đã nhập vào docs/Domains/DOL English/Feature Package/**.
docs/Knowledge base/** -> đã nhập vào docs/Shared/Knowledge Base/**.
docs/Operations/** -> đã nhập vào docs/Shared/Operations/**.
docs/Design System Doc/** -> đã nhập vào docs/Shared/Design System/**.

Content Audit Signals

docs/Domains/DOL English/UX Design/**
- chứa workspace entry, surface overview, feature master, page/flow docs;
- kết luận: đây là home chuẩn của current UX logic cho DOL English.
docs/Domains/DOL English/Product Discovery/**
- chứa events, decisions, state, views, ux extraction, contracts;
- kết luận: đây là discovery/support lane của English; không phải owner lane chính của current UX logic.
docs/Domains/DOL English/Feature Package/**
- chứa feature narrative dạng FEATURE_* và overview gom capability/feature lớn;
- kết luận: đây là feature-framing support lane; chỉ dùng khi cần packaging/framing supporting cho UX lane chính.
docs/Shared/Knowledge Base/**
- chứa NB_* human-authored notes và Imported/ machine-managed mirror outputs;
- kết luận: đây là knowledge workspace chính, còn SHR_KB_Workspace_Entry.md là entry overview cùng workspace.
docs/Shared/Operations/**
- chứa runbook vận hành thật như IdeaFlowHandoff và Knowledge workflows;
- kết luận: đây là operations workspace chính, không phải lane tạm.
docs/Shared/Design System/**
- chứa guideline, report, và audit docs;
- kết luận: đây là shared design system workspace chính.
docs/Shared/Shared Capabilities/Ecosystem Experience/**
- chứa north-star toàn hệ và rule ở tầng ecosystem;
- kết luận: đây là home chuẩn cho ecosystem UX canon.

Nested Pattern Rules

Trong docs/Domains/<domain>/UX Design/**:
- surface overview là canon để bắt đầu.
- các folder area nằm bên dưới là tổ chức nội bộ của workspace UX hiện tại.
Trong docs/Shared/Shared Capabilities/**:
- capability overview là canon để bắt đầu.
- các folder như AI Tutor Platform, Smart Search Platform, Engagement Platform nếu còn tồn tại thì được coi là legacy subtree nằm trong đúng workspace shared, chỉ mở khi overview liên quan trỏ tới.
Với Product Discovery, Feature Package, Design System, Knowledge Base, và Operations:
- workspace overview là entry,
- body docs sống trực tiếp trong workspace đó,
- không cần giữ thêm một lane body song song ở root.

Placement Rules by Content Type

Nếu tài liệu trả lời câu hỏi domain này đang hoạt động thế nào:
- đặt ở docs/Domains/<domain>/<workspace>/**.
Nếu tài liệu trả lời câu hỏi nhiều domain dùng chung rule gì:
- đặt ở docs/Shared/Shared Capabilities/**.
Nếu tài liệu là design system canon hoặc audit token/component:
- đặt ở docs/Shared/Design System/**.
Nếu tài liệu là tri thức học thuật/sản phẩm dùng chung:
- đặt ở docs/Shared/Knowledge Base/**.
Nếu tài liệu là runbook hoặc workflow vận hành:
- đặt ở docs/Shared/Operations/**.
Nếu tài liệu chỉ dùng để route AI, ghi plan, hoặc giữ artifact:
- không đặt vào domain/shared canon.

Do Not Do

Không đặt narrative chính của domain trong docs/Shared/**.
Không tạo lại các root folders cũ như docs/Product Discovery/**, docs/Feature Package/**, docs/Knowledge base/**, docs/Operations/**, docs/Design System Doc/**, hoặc docs/UX Design/**.
Không tạo thêm một cây Domains hoặc Shared song song ở nơi khác chỉ để mirror nội dung đã có.
Không cố gộp docs/Command/**, docs/context/**, docs/plans/**, .wiki, hoặc docs/tmp/** vào domain/shared chỉ vì muốn nhìn cây folder “đồng nhất”; chúng có vai trò khác.

Current High-priority Canonical Entry Points

Change log

2026-03-07: Tạo placement map cấp repo để khóa rõ canonical, support, và artifact cho toàn bộ docs/**.
2026-03-07: Cập nhật placement map sau khi body folders đã được chuyển vào docs/Domains/** và docs/Shared/**.
2026-03-07: Retire root docs/UX Design/** sau khi ecosystem UX canon được đưa hẳn sang shared capabilities.