Muốn viết technical writing tốt thì phải hạ thấp kỳ vọng [Bài dịch]

1. Viết là năng lực thiết yếu của kỹ sư

   • Viết kỹ thuật là kỹ năng thiết yếu với kỹ sư ở mọi cấp độ, từ commit message đến tài liệu hóa.
   • Sự khác biệt giữa viết tốt và viết chưa tốt ảnh hưởng lớn đến hiệu quả công việc và giao tiếp trong tổ chức.

2. Càng ngắn gọn, càng súc tích càng tốt

   • Độc giả không dành nhiều thời gian cho một bài viết.
   • Nếu có thể truyền đạt ý tưởng chỉ bằng một câu, hãy làm như vậy.
   • Việc chủ động lược bớt một số chi tiết đôi khi lại là một lợi thế.
   • Hãy đặt nội dung quan trọng ở phần đầu bài, ngay câu đầu tiên hoặc tiêu đề.

3. Đặt kỳ vọng một cách thực tế

   • Đừng kỳ vọng người đọc sẽ đọc kỹ và hiểu hoàn toàn một bài viết kỹ thuật.
   • Trong các tổ chức kỹ thuật, sự lẫn lộn và chênh lệch mức độ hiểu biết là điều bình thường, và không thể dùng viết lách để khiến mọi người ngang bằng nhau.
   • Hạ thấp kỳ vọng lại có thể giúp giao tiếp hiệu quả hơn.

4. Mục đích của bài viết là truyền đạt rõ trọng tâm

   • Mục tiêu ưu tiên hàng đầu là truyền đạt cho cả một nhóm rộng những điểm rất đơn giản như “việc thêm cấu hình là phức tạp”.
   • Quan trọng hơn việc dẫn dắt người đọc đến sự hiểu biết hoàn chỉnh về mặt kỹ thuật là cung cấp lượng ngữ cảnh tối thiểu để tạo sự tin cậy.

5. Những hiệu quả có thể kỳ vọng trong thực tế

   • Người nhận bài viết nhìn chung có ít kiến thức nền hơn người viết.
   • Với đối tượng rộng, có thể truyền đạt thông điệp đơn giản; với số rất ít người, có thể truyền đạt rõ những nội dung phức tạp.
   • Chỉ cần chỉ ra đúng phần cốt lõi cũng đủ tạo ra khác biệt lớn trong một tổ chức quy mô lớn.

6. Tư duy rõ ràng tạo ra bài viết rõ ràng

   • Những chủ đề chưa được hiểu đầy đủ thì rất khó nén gọn.
   • Hãy thừa nhận sự không chắc chắn và tập trung vào những phần bạn có thể giải thích rõ ràng.

7. Sai lầm thường gặp và điểm nên làm

   • Đừng quá ám ảnh với việc truyền tải quá nhiều chi tiết.
   • Hãy rút gọn dần nội dung muốn truyền đạt theo đơn vị một câu, một đoạn, một trang và đưa phần cốt lõi lên trước.
   • Ngay cả với những người gần như không có nền tảng kỹ thuật, việc truyền đạt được bối cảnh lớn tự nó đã có giá trị.

[yeobi222]

Điều khiến tôi băn khoăn nhất là nên thêm phần giải thích bổ sung như thế nào để người đọc có thể hiểu được
Nếu người ra quyết định là người ngoại đạo trong lĩnh vực đó, hoặc...

[girr311]

Không chỉ tài liệu kỹ thuật, mà điều này dường như cũng đúng với phần lớn các loại tài liệu khác.