Bỏ qua

Hướng dẫn sử dụng bộ khung

1. Cấu trúc tổng thể

Docs Toolkit gồm 7 site MkDocs độc lập (mỗi loại tài liệu là 1 site riêng, có mkdocs.yml và điều hướng tab riêng) cộng với 1 trang chủ tĩnh làm cổng vào:

ID-007-docs-toolkit/
├── index.html              # trang chủ tĩnh (card chọn loại tài liệu)
├── stylesheets/extra.css   # CSS riêng cho trang chủ
├── prd/
│   ├── mkdocs.yml
│   └── docs/{_template.md, hrm.md, timesheet.md, index.md}
├── srs/
│   ├── mkdocs.yml
│   └── docs/{_template.md, timesheet.md, hrm/(17 chương), index.md}
├── testcase/{mkdocs.yml, docs/...}
├── hdsd/{mkdocs.yml, docs/...}
├── uat/{mkdocs.yml, docs/...}
├── release-note/{mkdocs.yml, docs/...}
└── huong-dan/{mkdocs.yml, docs/index.md}   # chính là trang bạn đang đọc

Mỗi loại tài liệu là 1 site tách biệt để thanh tab điều hướng phía trên chỉ hiện các mục con thuộc đúng loại tài liệu đang xem — không bị lẫn PRD/TestCase/HDSD... vào cùng một dải tab.

2. Cách dùng nhanh (áp dụng cho một dự án thật)

  1. Vào thư mục site của loại tài liệu cần dùng (vd: srs/docs/).
  2. Copy file _template.md thành file mới, đặt tên theo phân hệ (vd: payroll.md).
  3. Điền nội dung vào các mục có sẵn, giữ nguyên cấu trúc heading để dễ tra cứu và đồng bộ giữa các phân hệ.
  4. Xóa các dòng hướng dẫn/ghi chú (in nghiêng) trong template sau khi đã hiểu cách dùng — chỉ giữ lại nội dung thật.
  5. Thêm file mới vào mục nav trong mkdocs.yml của site đó để hiện lên tab điều hướng.

3. Chạy thử một site tại local

Yêu cầu Python 3 và pip.

pip install mkdocs-material
cd ID-007-docs-toolkit/srs      # hoặc prd/, testcase/, hdsd/, uat/, release-note/, huong-dan/
python -m mkdocs serve

Mở trình duyệt tại http://127.0.0.1:8000. Mỗi site chạy độc lập — muốn xem nhiều site cùng lúc, chạy mkdocs serve ở các cổng khác nhau, vd --dev-addr=127.0.0.1:8002.

4. Build ra site tĩnh (để deploy)

Build từng site (output mặc định vào thư mục site/ bên trong mỗi site):

cd ID-007-docs-toolkit/srs
mkdocs build

Lặp lại cho cả 7 site. Kết quả site/ của từng loại không commit lên git.

5. Quy tắc đặt tên file khi áp dụng cho dự án thật

Tên file = tên phân hệ, viết thường, không dấu, nối bằng gạch ngang (vd: hrm.md, timesheet.md, payroll.md). Không cần nhúng loại tài liệu hay số phiên bản vào tên file — vì đã nằm trong site riêng (testcase/docs/timesheet.md đã rõ là Test Case) và lịch sử phiên bản được quản lý ngay trong bảng Document Control ở đầu mỗi file.

Nếu phân hệ đủ lớn cần tách thành nhiều file con (như ví dụ srs/hrm/), dùng một thư mục con cùng tên thay vì một file — xem chi tiết ở trang SRS.

Vì mỗi loại tài liệu là 1 site riêng, link chéo (vd PRD liên kết sang SRS) dùng đường dẫn tuyệt đối theo prefix tên site, ví dụ /srs/hrm/, /testcase/timesheet/. Cách này hoạt động đúng khi 7 site được deploy cùng một domain, mỗi site nằm dưới path prefix trùng tên (/prd/, /srs/, /testcase/, /hdsd/, /uat/, /release-note/). Khi chạy mkdocs serve độc lập từng site để dev, các link tuyệt đối này sẽ không trỏ đúng — đó là điều cần chấp nhận, chỉ hoạt động đầy đủ sau khi deploy chung domain.

7. Mermaid, Tabs & style

Mỗi mkdocs.yml đã bật sẵn pymdownx.superfences (cho Mermaid) và pymdownx.tabbed (cho Tabs) — dùng trực tiếp trong file .md, không cần cấu hình thêm.

Toàn bộ 7 site dùng chung 2 file CSS (stylesheets/hrm-extra.css, stylesheets/hrm-flow.css, copy vào docs/stylesheets/ của từng site) để đồng bộ giao diện: font Zilla Slab, bảng kiểu Excel, khối uc-card/flow-* cho Use Case. Nếu cập nhật style, nhớ đồng bộ lại cả 7 bản copy.