Đọc REP/design doc của Nav2

Bài trước đã bàn cách đọc README/docs cơ bản của một package. Với dự án lớn có kiến trúc phức tạp như Nav2 (đã học xuyên suốt chuyên mục ROS2 Navigation), có một loại tài liệu khác quan trọng không kém khi cần hiểu sâu — design doc, giải thích lý do đằng sau các quyết định kiến trúc.

Khái niệm chính

Hai loại tài liệu phục vụ hai mục đích khác hẳn nhau:

• API doc / docs site (VD: docs.nav2.org) — liệt kê tham số nào có sẵn, giá trị mặc định, cú pháp gọi — trả lời "có gì, dùng thế nào"
• Design doc / REP — giải thích lý do kiến trúc được thiết kế như vậy, các đánh đổi đã cân nhắc khi quyết định — trả lời "vì sao"

Nguyên lý hoạt động

Khi chỉ cần cấu hình/sử dụng một tính năng có sẵn (VD: đổi tham số inflation_radius đã học ở bài Tuning Costmap), API doc là đủ — không cần hiểu vì sao Nav2 tách riêng local_costmap và global_costmap thành hai instance độc lập. Nhưng khi cần mở rộng/sửa đổi kiến trúc — viết một plugin costmap layer mới, hay hiểu vì sao planner_server và controller_server là hai node tách biệt thay vì gộp chung — API doc không trả lời được, cần đọc design doc hoặc REP liên quan để hiểu đúng ý định thiết kế gốc trước khi thêm code vào.

Tóm lại: Nhầm hai loại tài liệu này là lỗi phổ biến — tìm tham số cấu hình trong design doc sẽ không thấy (đó không phải mục đích của nó), và tìm lý do kiến trúc trong API doc cũng không thấy (chỉ liệt kê "có gì", không giải thích "vì sao"). Xác định đúng câu hỏi đang cần trả lời trước khi chọn loại tài liệu để đọc.

Kiến thức kỹ thuật

Thông số

Cần trả lời câu hỏi	Loại tài liệu	Ví dụ cụ thể
Tham số nào có, mặc định là gì	API doc / docs site	Bảng tham số plugin DWB/MPPI trên docs.nav2.org
Vì sao tách Planner/Controller thành 2 node	Design doc/REP liên quan tới kiến trúc Nav2	REP hoặc design proposal gốc khi Nav2 được thiết kế
Cách viết 1 plugin costmap layer mới	Design doc + source code của layer có sẵn làm mẫu	Đọc nav2_costmap_2d source, không chỉ API doc
Behavior Tree hoạt động ra sao ở tầng thấp	Design doc BT + thư viện BehaviorTree.CPP gốc	Không nằm trong API doc cấu hình XML thông thường

Ứng dụng thực tế

Khi cần tuỳ biến sâu Nav2 cho một AMR có yêu cầu đặc thù (VD: thêm một recovery behavior mới ngoài Spin/BackUp/Wait đã học ở bài Recovery Behaviors), quy trình đúng không phải chỉ đọc API doc tìm "cách bật recovery behavior mới" (không có, vì đây là việc thêm code, không phải cấu hình) — mà cần đọc design doc/source code của các recovery behavior có sẵn để hiểu đúng interface (base class, phương thức cần override) trước khi viết behavior mới tuân theo đúng kiến trúc đã thiết kế.

Ví dụ thực tế

Kịch bản: cần hiểu vì sao Nav2 dùng kiến trúc Behavior Tree (đã học
ở bài Behavior Tree) thay vì State Machine truyền thống, để quyết định
có nên viết thêm 1 Custom Behavior Tree Node mới hay không

Tìm trong API doc (docs.nav2.org, mục cấu hình BT XML):
→ chỉ thấy DANH SÁCH các node có sẵn (Sequence, Fallback, ComputePathToPose...)
→ KHÔNG giải thích vì sao chọn kiến trúc BT thay vì State Machine

Tìm trong design doc/tài liệu kiến trúc Nav2 (thường trong repo GitHub,
mục docs/design hoặc design proposal khi tính năng được đề xuất):
→ giải thích lý do: BT dễ ghép (compose) hành vi nhỏ thành hành vi
   lớn hơn mà không cần vẽ lại sơ đồ transition, dễ mở rộng hơn
   State Machine viết tay — đúng lý do đã học ở bài Behavior Tree

Kết luận: hiểu đúng lý do thiết kế giúp viết Custom Node mới tuân
theo đúng triết lý ban đầu (composable, tái sử dụng được), không
chỉ "chạy được" mà còn khớp đúng kiến trúc tổng thể

Lỗi thường gặp

• Tìm tham số cấu hình trong design doc — như đã nêu, hai loại tài liệu phục vụ hai mục đích khác nhau, tìm sai loại lãng phí thời gian.
• Viết code mở rộng mà không đọc design doc trước — dễ tạo ra giải pháp "chạy được" nhưng vi phạm triết lý kiến trúc gốc, khó bảo trì/tích hợp về sau khi dự án gốc cập nhật.
• Coi design doc là tài liệu bắt buộc phải đọc để dùng cơ bản — với đa số người dùng chỉ cần cấu hình/dùng tính năng có sẵn, API doc là đủ; design doc chỉ cần thiết khi thực sự cần mở rộng/hiểu sâu.
• Không tìm design doc ở đúng chỗ — với dự án lớn như Nav2, design doc thường nằm rải rác (issue GitHub thảo luận thiết kế, design proposal riêng, REP liên quan, đôi khi cả bài báo/paper của tác giả) — không phải luôn tập trung một chỗ như API doc.

Kết luận

API doc và design doc trả lời hai câu hỏi khác nhau — "có gì, dùng thế nào" và "vì sao thiết kế như vậy" — nhầm lẫn giữa hai loại khiến việc tra cứu không hiệu quả. Chỉ cần tìm design doc khi thực sự có ý định mở rộng/sửa đổi kiến trúc, không phải khi chỉ cần cấu hình tính năng có sẵn. Bài tiếp theo trong chuyên mục đi vào changelog và migration guide — tài liệu quan trọng khi nâng cấp phiên bản ROS2, nơi hành vi có thể thay đổi mà README chính chưa kịp cập nhật.