Tài liệu hóa công cụ: docstring, README cho người dùng cuối và hướng dẫn xử lý sự cố thường gặp

Công cụ tốt mà không ai biết cách dùng sẽ bị bỏ. Ba lớp tài liệu cần có: docstring cho lập trình viên, README ngắn cho người dùng, và danh sách lỗi thường gặp kèm cách xử lý.

Tài liệu hóa công cụ

Các bước thực hiện

1. Docstring. Mỗi hàm công khai mô tả tham số và giá trị trả về.
2. README người dùng. Cài đặt, cách chạy, ảnh chụp từng bước.
3. Sự cố thường gặp. Bảng triệu chứng - nguyên nhân - cách xử lý.
4. CHANGELOG. Ghi mỗi thay đổi theo phiên bản.
5. Cập nhật cùng code. Sửa code phải sửa tài liệu.

Mẫu README cho người dùng cuối

# NX Lab Tools - Bộ công cụ tự động hóa NX

Phiên bản: xem file VERSION. Liên hệ: it-cad@congty.vn (số nội bộ 123)

## Cài đặt (1 phút)
1. Chạy file \\may-chu\ky_thuat\nxlab-tools\cai_dat.bat bằng cách nhấp đúp.
2. Khởi động lại NX. Menu "NX Lab" xuất hiện trước menu Help.

## Cách dùng
| Nút               | Việc làm                                     | Cần mở sẵn        |
|-------------------|-----------------------------------------------|-------------------|
| Kiểm tra chi tiết | Kiểm thuộc tính, kích thước, báo đạt/không đạt | 1 part            |
| Xuất STEP         | Xuất part đang mở ra thư mục D:\NXLab_xuat    | 1 part đã lưu     |
| Đóng gói giao hàng| Gom STEP, PDF, BOM thành file ZIP              | Thư mục xuất     |

## Sự cố thường gặp
| Triệu chứng                          | Nguyên nhân thường gặp           | Cách xử lý                          |
|--------------------------------------|----------------------------------|--------------------------------------|
| Không thấy menu NX Lab               | Chưa khởi động lại NX            | Đóng hẳn NX rồi mở lại               |
| "Chưa có Work Part"                  | Chưa mở file                     | Mở part rồi bấm lại                  |
| "Không thấy file cấu hình STEP"      | Sai phiên bản NX                 | Báo IT, gửi file log (xem bên dưới)  |
| Xuất xong không có file              | Thư mục xuất không ghi được      | Kiểm tra quyền, chọn thư mục khác    |

## Gửi log khi cần hỗ trợ
Gửi file D:\NXLab_log\loi.log và ảnh chụp thông báo lỗi cho IT.

Giải thích code

• README viết cho người dùng cuối: ít thuật ngữ, có bảng nút bấm và bảng sự cố.
• Phần 'Gửi log khi cần hỗ trợ' tiết kiệm rất nhiều thời gian trao đổi qua lại.
• Docstring nên mô tả vì sao và định dạng tham số, không lặp lại tên hàm.

Lỗi thường gặp

• Tài liệu cũ hơn code gây hiểu lầm hơn là không có tài liệu; cập nhật khi sửa hành vi.
• Đừng đặt thông tin nhạy cảm (mật khẩu, địa chỉ máy chủ nội bộ) vào README chung.

Code mang tính tham khảo, viết cho NX 12 trở lên (Python journal). Tên menu và một số lớp có thể khác theo phiên bản NX; hãy chạy thử trên bản sao của chi tiết trước khi dùng cho dữ liệu thật.