Kiến thức Kỹ thuật
Viết tài liệu kỹ thuật rõ ràng: nguyên tắc và mẫu
SPKT Heritage ·
Viết cho người đọc, không phải cho người viết
Tài liệu kỹ thuật tồn tại để người khác làm được việc. Trước khi viết, trả lời hai câu: ai đọc, và sau khi đọc họ phải làm gì.
Nguyên tắc 1 — Xác định người đọc
- Người mới cần: bối cảnh, từng bước, cảnh báo.
- Người có kinh nghiệm cần: thông số, sơ đồ, điểm khác biệt.
- Viết cho cả hai trong một tài liệu thường dẫn tới dở cả hai.
Nguyên tắc 2 — Cấu trúc rõ
Mẫu gợi ý:
- Mục đích — tài liệu này giải quyết việc gì.
- Phạm vi — áp dụng cho cái gì, không áp dụng cho cái gì.
- Chuẩn bị — dụng cụ, quyền truy cập, điều kiện.
- Các bước — đánh số, mỗi bước một hành động.
- Kiểm tra — làm sao biết đã đúng.
- Xử lý lỗi — lỗi thường gặp và cách xử lý.
- Tham chiếu — tài liệu, người liên hệ.
Nguyên tắc 3 — Hình ảnh thay lời
Sơ đồ khối, ảnh chụp màn hình có đánh dấu, bảng thông số. Một hình tốt tiết kiệm cả đoạn văn. Mỗi hình cần chú thích và được nhắc trong nội dung.
Nguyên tắc 4 — Ngôn ngữ
- Câu ngắn, chủ động: “Ngắt nguồn trước khi tháo” thay vì “Nguồn cần được ngắt”.
- Một câu một ý.
- Thuật ngữ nhất quán; giải thích lần đầu.
- Cảnh báo an toàn đặt trước bước nguy hiểm, không sau.
Nguyên tắc 5 — Kiểm tra trước khi bàn giao
Checklist:
- Người không biết gì có làm theo được không?
- Mọi hình/bảng đều được nhắc trong văn bản?
- Có bước nào thiếu điều kiện tiên quyết không?
- Cảnh báo an toàn đã đủ chưa?
- Ngày, phiên bản, người viết đã ghi chưa?
Nguyên tắc 6 — Bảo trì
Tài liệu không bảo trì sẽ thành sai. Ghi ngày cập nhật; khi quy trình đổi, sửa tài liệu cùng lúc, đừng để sau.
Bạn có mẫu tài liệu kỹ thuật hữu ích? Chia sẻ với cộng đồng.
Cộng đồng độc lập – Không phải trang chính thức của HCM-UTE / SPKT. Di sản & kỷ niệm từ cựu sinh viên.
Đọc thêm: Tư duy khắc phục sự cố · Kỹ năng mềm kỹ sư · Xem cả chuyên mục Kiến thức kỹ thuật.
Kết nối cùng cộng đồng
Đọc thêm tại ute.vn · Bình luận tạiFanpage SV.SPKT ·Tham gia cộng đồng
Cộng đồng độc lập – Không phải trang chính thức của HCM-UTE / SPKT. Di sản & kỷ niệm từ cựu sinh viên.
Câu hỏi thường gặp
- Tài liệu kỹ thuật tốt cần gì trước tiên?
- Xác định rõ người đọc và việc họ cần làm sau khi đọc. Mọi phần khác phục vụ mục tiêu đó.
- Nên viết dài hay ngắn?
- Đủ để người đọc làm được việc, không hơn. Tài liệu ngắn mà đủ tốt hơn tài liệu dài khiến người đọc bỏ dở.
- Có nên dùng nhiều thuật ngữ tiếng Anh không?
- Dùng khi thuật ngữ đã phổ biến trong ngành, kèm giải thích ngắn lần đầu xuất hiện. Tránh dùng tiếng Anh chỉ để tỏ ra chuyên nghiệp.