Nghệ thuật viết tài liệu kỹ thuật: Hãy viết cho một người duy nhất

Trong thế giới phát triển phần mềm và kỹ thuật, việc tạo tài liệu (documentation) hay viết blog kỹ thuật thường là một thách thức lớn. Nhiều người mắc phải bẫy cố gắng viết cho một đối tượng quá rộng lớn, hy vọng rằng ai đọc cũng có thể hiểu. Kết quả thường là những bài viết chung chung, sáo rỗng và không thực sự giúp ích cho ai cả.

Viết cho một người

Bẫy của việc viết cho "tất cả mọi người"

Khi bạn cố gắng làm hài lòng tất cả mọi người, bạn thường không làm hài lòng ai cả. Trong bối cảnh kỹ thuật, nếu bạn cố gắng giải thích một khái niệm phức tạp vừa đủ cho người mới bắt đầu (newbie), vừa đủ sâu sắc cho kỹ sư cấp cao (senior engineer), bạn sẽ rơi vào tình trạng "nước đôi".

Người mới sẽ thấy quá nhiều thuật ngữ khó hiểu, trong khi người giàu kinh nghiệm lại thấy bài viết dài dòng và lan man. Đây là lý do tại sao tư duy "viết cho một người" lại trở nên cực kỳ hiệu quả.

Định nghĩa "người đọc duy nhất" của bạn

Thay vì tưởng tượng một đám đông vô hình, hãy hình dung ra một người cụ thể. Họ có thể là một đồng nghiệp trong nhóm của bạn, một phiên bản của chính bạn trong quá khứ, hoặc một người bạn đang muốn chuyển sang làm lập trình.

Hãy tự hỏi:

• Họ đã biết những gì rồi?
• Họ đang gặp khó khăn ở đâu?
• Họ muốn đạt được kết quả gì sau khi đọc bài viết này?

Khi bạn có một chân dung cụ thể, bạn sẽ biết chính xác nên bỏ qua những kiến thức nào (vì người đó đã biết) và nên đi sâu vào chi tiết nào (vì người đó đang cần).

Lợi ích của sự cụ thể

Viết cho một người duy nhất mang lại sự tự tin. Bạn không cần lo lắng về việc liệu người khác có đánh giá cao hay không, vì bạn đang viết để giúp đỡ một người cụ thể vượt qua một trở ngại cụ thể.

Hơn nữa, sự cụ thể tạo ra sự kết nối. Những ví dụ thực tế, những ngôn ngữ đời thường và sự thấu hiểu nỗi đau của người đọc sẽ làm cho nội dung của bạn trở nên sống động. Độc giả khác, dù không phải là "người duy nhất" bạn nhắm tới, vẫn có thể cảm thấy bài viết có giá trị vì sự chân thành và chiều sâu của nó.

Áp dụng vào thực tế

Bạn có thể áp dụng nguyên tắc này vào nhiều khía cạnh trong công việc kỹ thuật:

• Tài liệu API: Đừng chỉ liệt kê các tham số. Hãy viết cho một lập trình viên front-end đang cần tích hợp tính năng này gấp.
• Commit message: Hãy viết cho đồng đội của bạn 6 tháng sau, khi họ đang cố gắng tìm hiểu tại sao đoạn code này bị lỗi.
• Bài viết blog: Hãy chia sẻ kinh nghiệm giải quyết một bug cụ thể mà bạn vừa gặp, như thể bạn đang nói chuyện với một người bạn đang gặp lỗi tương tự.

Tóm lại, đừng sợ việc nội dung của bạn quá hẹp. Trong kỷ nguyên thông tin bùng nổ, những nội dung chuyên sâu, giải quyết tốt một vấn đề cụ thể cho một nhóm người cụ thể luôn có giá trị hơn những bài viết chung chung cố gắng bao vây toàn bộ thế giới.