Pengembang sering menulis dokumentasi yang buruk, mengasumsikan pengguna memiliki bias dan pengetahuan yang sama. Untuk mengatasi ini, penulis membayar pengguna nyata €25 per jam untuk menguji README Activity Bot mereka dengan mengikuti petunjuk dengan keras sambil membagikan layar mereka. Hal ini mengungkapkan cacat kritis: tautan demo yang rusak, langkah pengubahan nama file yang membingungkan, istilah teknis yang tidak jelas, urutan bagian yang buruk, dan tujuan perangkat lunak yang tidak dijelaskan.
Penulis mengambil catatan tangan, memperbarui README setelah setiap sesi, dan menguji ulang dengan pengguna baru. Dalam beberapa sesi, mereka membayar €150 untuk umpan balik terbuka. Proses ini menunjukkan bahwa pengguna nyata mengungkapkan asumsi tersembunyi — seperti kebutuhan sudo, persyaratan reboot, dan aturan kutip — yang sering diabaikan pengembang.
Berbeda dengan LLMs, orang nyata membawa humor, perspektif unik, dan petunjuk emosional seperti frustrasi, yang menunjukkan di mana dokumentasi gagal. Penulis membandingkan ini dengan pengalaman mereka dalam penulisan teknis di GOV. UK, di mana tinjauan manusia mengubah prosa yang berlebihan menjadi dokumen yang jelas dan dapat digunakan.
Meskipun README belum sempurna, kini jelas lebih mudah diikuti. Pelajaran inti: pengembang harus menguji dokumentasi dengan orang nyata yang berpikir dengan keras, bahkan jika tidak dibayar, untuk menemukan titik buta dan meningkatkan kegunaan.
Sumber: Hacker News · Diringkas oleh HeadlinesBriefing