Tôi trả tiền để người khác thử làm theo file README của mình

Các lập trình viên viết tài liệu rất tệ. Chúng ta thường thích nói "RTFM" (hãy đọc hướng dẫn sử dụng đi) nhưng thường thì chẳng có cái "FM" nào để mà đọc cả. May lắm thì chúng ta có một mớ ghi chú nửa vời, vài mẹo đã lỗi thời và một đường dẫn tới diễn đàn hoang vắng đầy người hỏi đi hỏi lại cùng một câu hỏi. Đó không phải là cách đối xử với người dùng.

Tôi vẫn tin một cách ngây thơ rằng có cách làm tốt hơn. Như tôi đã từng viết, bạn nên ngồi xuống và thực sự kiểm thử file README của mình. Khởi động một máy ảo mới tinh, làm theo từng bước bạn đã viết và xem liệu nó có hợp lý không.

Nhưng thật khó để gạt bỏ thành kiến của chính mình. Đương nhiên bạn biết rằng một số lệnh cần sudo, đương nhiên khi bạn viết -foo thì ý bạn là --foo, và ai cũng biết rằng phải khởi động lại sau đó. Làm sao để thoát khỏi những thành kiến đó? Tôi đã trả tiền để thuê người!

Trả tiền cho người thật để kiểm thử tài liệu

Trong đơn xin tài trợ NLnet cho ActivityBot, tôi nói rằng mình muốn kiểm thử trải nghiệm cài đặt với người dùng thật và sẵn sàng trả họ 25 euro cho một giờ. Tôi đăng lời kêu gọi trên Mastodon, tập hợp được vài người và tổ chức một cuộc gọi video với họ.

Cách làm rất đơn giản. Tôi giải thích rằng mình đang tìm phản hồi về trải nghiệm chạy lần đầu, rằng tôi biết nó chưa hoàn hảo và thực sự muốn nhận những lời phê bình mang tính xây dựng. Tôi yêu cầu tình nguyện viên chia sẻ màn hình và — quan trọng nhất — nói thành tiếng. Hãy cho tôi biết họ đang làm gì, chỗ nào họ không hiểu, chỗ nào khiến họ bối rối, chỗ nào làm họ thích thú, chỗ nào khiến họ bực bội.

Tôi ghi chú bằng tay và dành vài giờ để nghe người ta chỉ ra những giả định sai lầm của mình.

Những phát hiện đáng chú ý

Trong số những điều tôi khám phá ra có:

• Đường dẫn tới công cụ demo bị sai.
• Một số người đọc README ngay trong terminal.
• "Đổi tên một file" thực sự nghĩa là gì?
• Làm sao để đổi tên một file ẩn?
• Công cụ demo nên có trên web hay chỉ chạy trên máy cục bộ của người dùng?
• Tại sao có đoạn văn bản bắt buộc phải đặt trong dấu ngoặc kép còn đoạn khác thì không?
• Những câu đùa của tôi chẳng buồn cười mà còn gây bối rối.
• Một số thuật ngữ kỹ thuật cần được giải thích.
• Thứ tự sắp xếp các phần gây khó hiểu.
• Tôi chưa thực sự giải thích phần mềm này sẽ làm gì.
• Cả một phần mà tôi thấy thú vị về mặt kỹ thuật lại hoàn toàn khó hiểu với mọi người.
• Không phải máy chủ web nào cũng dùng quyền hạn theo cùng một cách.

Và còn nhiều nữa!

Sau mỗi buổi, tôi cập nhật README dựa trên những gì người ta thấy khó khăn, rồi kiểm thử lại với người tiếp theo. Tổng cộng, tôi đã chi khoảng 150 euro để một nhóm người phê bình thẳng mặt mình. Này, còn rẻ hơn tiền trị liệu tâm lý, đúng không?

Tại sao không dùng AI mô phỏng người dùng?

Tôi biết sẽ có người nói "sao không nhờ một mô hình ngôn ngữ lớn mô phỏng nhiều nhóm người dùng khác nhau?" Câu trả lời rất đơn giản — tôi muốn nói chuyện với người thật. Con người thật tuyệt vời! Họ có thể làm bạn cười, bạn có thể thấy con mèo của họ khi nó đi ngang qua màn hình, họ mang đến một góc nhìn độc đáo cho vấn đề, và họ rất vui khi bạn tặng họ một phiếu quà 25 euro. Một số người còn sẵn sàng làm miễn phí chỉ để giúp bạn vui.

Khi tôi làm việc viết tài liệu kỹ thuật cho GOV.UK, mọi câu văn hoa mỹ của tôi đều được một người khác soi lại. Họ xé nát hết những câu chữ rườm rà và biến tài liệu thành thứ dễ đọc hơn.

Họ là những người phát hiện ra những lỗi mà không phần mềm kiểm tra chính tả nào bắt được. Họ có thể trò chuyện thực sự với tôi. Quan trọng hơn, tôi có thể nghe thấy sự bực bội trong giọng nói của họ — đó chính là thứ cho bạn biết một lỗi cần phải được sửa.

Bài học cho lập trình viên

Tôi không dám khẳng định README của ActivityBot giờ đã hoàn hảo — còn xa lắm — nhưng nó rõ ràng đã dễ làm theo hơn nhiều.

Các lập trình viên cần nói chuyện với người thật. Bạn không nhất thiết phải trả tiền nếu không đủ khả năng, nhưng hãy tìm vài người sẵn sàng nói thành tiếng trong khi họ cố làm theo hướng dẫn của bạn. Tôi đảm bảo rằng file README của bạn sẽ trở nên tốt hơn hẳn nhờ điều đó.

Nguồn tham khảo: shkspr.mobi