Ngành công nghệ đang đối mặt với một vấn đề dai dẳng đã làm khổ các developer trong nhiều năm. Mặc dù tài liệu kỹ thuật được xếp hạng là một trong ba nguồn tài nguyên học tập hàng đầu trong khảo sát năm 2024 của Stack Overflow, chất lượng vẫn còn kém một cách đáng thất vọng. Khảo sát Open Source năm 2017 của GitHub đã xác định tài liệu không đầy đủ hoặc gây nhầm lẫn là điểm đau số một đối với các developer, và các cuộc thảo luận trong cộng đồng cho thấy tình hình ít có cải thiện kể từ đó.
Thống kê chính:
- Tài liệu kỹ thuật xếp hạng trong top 3 nguồn tài nguyên học tập (khảo sát Stack Overflow 2024)
- "Tài liệu không đầy đủ hoặc gây nhầm lẫn" là điểm đau số 1 (khảo sát GitHub 2017 Open Source Survey)
Vấn đề Thực sự không chỉ là Kỹ năng Viết
Trong khi nhiều người cho rằng tài liệu kém xuất phát từ việc các developer thiếu khả năng viết, cộng đồng tiết lộ một bức tranh phức tạp hơn. Vấn đề cốt lõi dường như là cái mà các chuyên gia gọi là vấn đề tư duy người mới bắt đầu - về cơ bản là sự thiếu đồng cảm. Các developer gặp khó khăn trong việc nhớ lại cảm giác trước khi họ hiểu một khái niệm, khiến việc hướng dẫn người khác qua cùng hành trình học tập đó trở nên gần như bất khả thi.
Các chuyên gia viết kỹ thuật nhấn mạnh rằng văn xuôi đẹp không có ý nghĩa gì nếu nội dung không phục vụ đối tượng mục tiêu. Thách thức lớn nhất không phải là tạo ra những câu văn thanh lịch, mà là phân tích ai sẽ đọc tài liệu và thiết kế chính xác những gì họ cần để đạt được mục tiêu của mình. Điều này đòi hỏi hiểu biết về quy trình làm việc của người dùng, dự đoán các khoảng trống kiến thức, và cấu trúc thông tin theo trình tự logic.
Ưu và nhược điểm của tài liệu LLM:
Ưu điểm:
- Tổ chức cấu trúc tốt hơn nhiều tài liệu do developer viết
- Định dạng nhất quán và tuân thủ template
- Phù hợp cho nội dung theo công thức như tài liệu thiết kế
Nhược điểm:
- Nội dung khó nhớ và ghi nhận hơn
- Thiếu cá tính và "cảm giác" hấp dẫn
- Có thể đúng về mặt kỹ thuật nhưng thiếu những giải thích trực quan
Các Tổ chức làm đúng
Một số công ty đã tìm ra cách giải quyết thông qua các chiến thuật tâm lý thông minh. Một cách tiếp cận là có các nhóm tài liệu chuyên dụng sẽ viết tài liệu cho những developer không tự cung cấp tài liệu của riêng họ. Tuy nhiên, các nhóm này cố tình viết từ góc nhìn của người ngoài, buộc các developer ban đầu phải dành nhiều thời gian hơn để xem xét và chỉnh sửa so với thời gian họ sẽ dành để viết tài liệu phù hợp. Điều này tạo ra các động lực đúng đắn trong khi đảm bảo chất lượng đầu ra.
Các Giải Pháp Tổ Chức:
- Thu thập phản hồi thường xuyên từ người dùng tài liệu
- Bổ sung các technical writer chuyên dụng để hỗ trợ các nhóm
- Chú ý đến các vấn đề liên quan đến tài liệu trên GitHub
- Sử dụng các nhóm tài liệu "tâm lý học ngược" để buộc developer tham gia
Cuộc tranh luận về Tài liệu LLM
Khi các công cụ trí tuệ nhân tạo trở nên tinh vi hơn, nhiều người hy vọng chúng sẽ giải quyết được những khó khăn về tài liệu. Một số kỹ sư báo cáo rằng tài liệu được tạo bởi LLM vượt trội đáng kể so với những nỗ lực viết kỹ thuật trước đây của họ, đặc biệt là đối với nội dung có cấu trúc như tài liệu thiết kế kỹ thuật mạng. Các công cụ này xuất sắc trong việc tuân theo các mẫu và duy trì định dạng nhất quán.
Tuy nhiên, một mô hình đáng lo ngại xuất hiện từ trải nghiệm của các developer với tài liệu được tạo bởi AI. Nhiều người thấy nội dung khó nhớ hơn và ít hấp dẫn hơn so với các lựa chọn thay thế được viết bởi con người. Việc tối ưu hóa toán học điều khiển LLM có thể tạo ra nội dung chính xác về mặt kỹ thuật nhưng thiếu hồn, không có tính cách và những giải thích trực quan khiến các khái niệm kỹ thuật dễ nhớ.
AI hoàn toàn thiếu phong cách và tôi có cảm giác rằng nhiều thứ mà mọi người thích từ việc viết kỹ thuật là cảm giác họ có được từ bài viết; cũng như hướng dẫn.
Giải pháp có thể liên quan đến việc coi tài liệu như một thách thức vừa kỹ thuật vừa sáng tạo. Các tổ chức cần những người viết kỹ thuật chuyên dụng, các vòng phản hồi thường xuyên với người dùng thực tế, và các developer nhận ra rằng việc giải thích các ý tưởng phức tạp đòi hỏi một bộ kỹ năng riêng. Trong khi LLM có thể xử lý định dạng và cấu trúc, yếu tố con người về sự hiểu biết và đồng cảm vẫn không thể thay thế được đối với giao tiếp kỹ thuật thực sự hiệu quả.
Tham khảo: Let's Talk About Writing in Tech