غالبًا ما يكتب المطورون توثيقًا ضعيفًا، مفترضين أن المستخدمين يشاركونهم التحيزات والمعرفة. لتجاوز هذا، دفع المؤلف مستخدمين حقيقيين 25 يورو في الساعة لاختبار README الخاص بـ Activity Bot باتباع التعليمات بصوت عالٍ أثناء مشاركة شاشتهم. كشف هذا عن عيوب حرجة: روابط عرض معطلة، خطوات إعادة تسمية ملفات مربكة، مصطلحات تقنية غير واضحة، ترتيب أقسام ضعيف، وغرض برمجي غير مفسَّر. أخذ المؤلف ملاحظات يدوية، وحدّث README بعد كل جلسة، وأعاد الاختبار مع مستخدمين جدد. على مدى عدة جلسات، دفعوا 150 يورو مقابل ملاحظات صريحة. أظهر هذا العملية أن المستخدمين الحقيقيين يكشفون عن افتراضات مخفية — مثل الحاجة إلى sudo، متطلبات إعادة التشغيل، وقواعد الاقتباس — التي يتجاهلها المطورون. على عكس LLMs، يجلب الناس الحقيقيون الفكاهة، وجهات نظر فريدة، وإشارات عاطفية مثل الإحباط، والتي تشير إلى أماكن فشل التوثيق. يقارن المؤلف هذا بتجربته في الكتابة التقنية لـ GOV.UK، حيث حولت المراجعة البشرية النثر الزهري إلى وثائق واضحة وقابلة للاستخدام. على الرغم من أن README ليس مثاليًا، فإنه الآن يُظهر بوضوح أنه أسهل في المتابعة. الدرس الأساسي: يجب على المطورين اختبار التوثيق مع أشخاص حقيقيين يفكرون بصوت عالٍ، حتى لو دون أجر، لاكتشاف النقاط العمياء وتحسين قابلية الاستخدام.
المصدر: Hacker News · لخّصه HeadlinesBriefing