I paid people to try and follow my README

Developers often write poor documentation, assuming users share their biases and knowledge. To overcome this, the author paid real users €25 per hour to test their Activity Bot README by following instructions aloud while sharing their screen. This revealed critical flaws: broken demo links, confusing file renaming steps, unclear technical terms, poor section ordering, and unexplained software purpose.

The author took handwritten notes, updated the README after each session, and retested with new users. Over several sessions, they paid out €150 for candid feedback. The process highlighted that real users expose hidden assumptions—like sudo needs, reboot requirements, and quoting rules—that developers overlook.

Unlike LLMs, real people bring humor, unique perspectives, and emotional cues like frustration, which signal where documentation fails. The author compares this to their GOV. UK technical writing experience, where human review turned flowery prose into clear, usable docs.

While the README isn’t perfect, it is now demonstrably easier to follow. The core lesson: developers must test documentation with real people who think aloud, even if unpaid, to uncover blind spots and improve usability.

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

ডেভেলপাররা اکثر সময় খারাপ নথিয়ানকরণ লিখে, মনে করে যে ব্যবহারকারীরা তাদের মতো পক্ষপাত এবং জ্ঞান ভাগ করে। এই সমস্যা দূর করতে, লেখকটি বাস্তব ব্যবহারকারীদের প্রতি ঘন্টা 25 ইউরো দিয়ে তাদের Activity Bot README-এর পরীক্ষা করিয়েছিল, যেখানে তারা নির্দেশাবলী উচ্চরে পড়ते हुए স্ক্রীন শেয়ার করত। এই প্রক্রিয়াটি গুরুত্বপূর্ণ ত্রুটিগুলো উন্মোচন করেছিল: ভাঙা ডেমো লিঙ্ক, বিভ্রান্তিকর ফাইল নাম পরিবর্তনের ধাপ, অস্পষ্ট প্রযুক্তিগত শব্দ, বিভাগের খराब ক্রম এবং সফটওয়্যারের উদ্দেশ্য ব্যাখ্যা না করা। লেখক হস্তলিখিত নোট নিল, প্রতিটি সেশনের পর README আপডেট করিল এবং নতুন ব্যবহারকারীদের সাথে পুনরায় পরীক্ষা করিল। বেশ কিছু সেশনের মাধ্যমে, mereka স্পষ্ট প্রতিক্রিয়া জন্য 150 ইউরো দিল। এই প্রক্রিয়াটি দেখিয়েছে যে বাস্তব ব্যবহারকারীরা গোপন ধারণাগুলো উন্মোচন করে — যেমন sudo এর প্রয়োজন, রিবুটের প্রয়োজন এবং উদ্ধৃতি নিয়ম — যা ডেভেলপাররা প্রায়শই উপেক্ষা করে। LLMs-এর বিপরীতে, বাস্তব মানুষ হাস্য, অনন্য দৃষ্টিভঙ্গি এবং দুঃখের মতো আবেগগত সংকেত আনে, যা নথিয়ানকরণের ব্যর্থতা নির্দেশ করে। লেখক তার GOV.UK প্রযুক্তিগত লিখার অভিজ্ঞের সাথে এই তুলনা করেন, যেখানে মানব পর্যালোচনা ফুলের মতো গদ্যকে स्पষ্ট, ব্যবহারযোগ্য নথিয়ানকে পরিণত করে। যদিও README এখনও পরিপূর্ণ নয়, এখন এটি স্পষ্টভাবে অনুসরণ করার জন্য সহজ। মূল শিক্ষা: ডেভেলপারদের নথিয়ানকরণের পরীক্ষা বাস্তব মানুষদের সাথে করা উচিত যারা ভ ausgelে চিন্তা করেন,即使未付费, যাতে aveugল বিন্দুগুলো খুঁজে পayout করা যায় এবং ব্যবহারযোগ্যতা উন্নত করা যায়।

Entwickler schreiben oft schlechte Dokumentation, weil sie annehmen, dass Nutzer ihre Vorurteile und Kenntnisse teilen. Um dies zu überwinden, bezahlte der Autor echte Nutzer 25 Euro pro Stunde dafür, den README ihres Activity Bot laut vorzulesen, während sie ihren Bildschirm teilten. Dadurch wurden kritische Mängel sichtbar: kapotte Demo-Links, verwirrende Schritte zum Umbenennen von Dateien, unklare technische Begriffe, schlechte Abschnittsreihenfolge und unerklärter Softwarezweck.

Der Autor machte handschriftliche Notizen, aktualisierte den README nach jeder Sitzung und testete anschließend mit neuen Nutzern. Über mehrere Sitzungen zahlten sie insgesamt 150 Euro für ehrliches Feedback. Dieser Prozess zeigte, dass echte Nutzer versteckte Annahmen aufdecken — wie den Bedarf an sudo, Neustartanforderungen und Zitierregeln — die Entwickler oft übersehen. Im Gegensatz zu LLMs bringen echte Menschen Humor, einzigartige Perspektiven und emotionale Signale wie Frustration mit, die darauf hinweisen, wo die Dokumentation versagt.

Der Autor vergleicht dies mit seiner Erfahrung in der technischen Schreibweise für GOV. UK, wo menschliche Überprüfung blumige Prosa in klare, nutzbare Dokumente verwandelte. Obwohl der README nicht perfekt ist, ist er jetzt demonstriert leichter zu folgen.

Die Kernbotschaft: Entwickler sollten Dokumentation mit echten Menschen testen, die laut nachdenken — auch unbezahlt — um blinde Flecken zu finden und die Benutzerfreundlichkeit zu verbessern.

Los desarrolladores suelen escribir documentación pobre, asumiendo que los usuarios comparten sus sesgos y conocimientos. Para superar esto, el autor pagó a usuarios reales 25 euros por hora para probar su README de Activity Bot siguiendo las instrucciones en voz alta mientras compartían su pantalla. Esto reveló fallos críticos: enlaces de demostración rotos, pasos confusos de renombrado de archivos, términos técnicos poco claros, mala ordenación de secciones y propósito del software sin explicar.

El autor tomó notas manuscritas, actualizó el README después de cada sesión y volvió a probar con nuevos usuarios. Tras varias sesiones, pagó 150 euros por retroalimentación franca. El proceso destacó que los usuarios reales exponen suposiciones ocultas —como la necesidad de sudo, requisitos de reinicio y reglas de citado— que los desarrolladores pasan por alto.

A diferencia de las LLMs, las personas reales aportan humor, perspectivas únicas y señales emocionales como la frustración, que indican dónde falla la documentación. El autor lo compara con su experiencia en redacción técnica de GOV. UK, donde la revisión humana convirtió un prosa florida en documentos claros y utilizables.

Aunque el README no es perfecto, ahora es demostrablemente más fácil de seguir. La lección principal: los desarrolladores deben probar la documentación con personas reales que piensen en voz alta, incluso si no están pagadas, para descubrir puntos ciegos y mejorar la usabilidad.

Les développeurs écrivent souvent une mauvaise documentation, en supposant que les utilisateurs partagent leurs biais et leurs connaissances. Pour surmonter cela, l'auteur a payé de vrais utilisateurs 25 euros de l'heure pour tester leur README d'Activity Bot en suivant les instructions à voix haute tout en partageant leur écran. Cela a révélé des défauts critiques : liens de démonstration cassés, étapes de renommage de fichiers confus, termes techniques peu clairs, mauvais ordre des sections et objectif du logiciel non expliqué.

L'auteur a pris des notes manuscrites, a mis à jour le README après chaque session et a retesté avec de nouveaux utilisateurs. Au cours de plusieurs sessions, ils ont déboursé 150 euros pour des retours francs. Ce processus a mis en évidence que les vrais utilisateurs exposent des hypothèses cachées — comme le besoin de sudo, les exigences de redémarrage et les règles de citation — que les développeurs négligent.

Contrairement aux LLMs, les vraies personnes apportent de l'humour, des perspectives uniques et des indices émotionnels comme la frustration, qui signalent où la documentation échoue. L'auteur compare cela à son expérience de rédaction technique sur GOV. UK, où la relecture humaine a transformé un prose fleurie en des documents clairs et utilisables.

Bien que le README ne soit pas parfait, il est désormais demonstrablement plus facile à suivre. La leçon fondamentale : les développeurs doivent tester la documentation avec de vraies personnes qui pensent à voix haute, même non rémunérées, pour découvrir les angles morts et améliorer l'utilisabilité.

डेवलपर अक्सर खराब दस्तावेज़ लिखते हैं, मानते हैं कि उपयोगकर्ता उनके समान पक्षपात और ज्ञान साझा करते हैं। इसे दूर करने के लिए, लेखक ने वास्तविक उपयोगकर्ताओं को प्रति घंटा 25 यूरो का भुगतान करके अपने Activity Bot README का परीक्षण करवाया, जिसमें वे निर्देशों को głos में पढ़ते हुए अपने स्क्रीन साझा करते थे। इससे महत्वपूर्ण दोष सामने आए: टूटे हुए डेमो लिंक, भ्रमित करने वाले फ़ाइल नाम बदलने के चरण, अस्पष्ट तकनीकी शब्द, खंडों का खराब क्रम और सॉफ़्टवेयर के उद्देश्य की स्पष्ट व्याख्या नहीं। लेखक ने हाथ से लिखित नोट लिए, प्रत्येक सत्र के बाद README अपडेट किया और नए उपयोगकर्ताओं के साथ फिर से परीक्षण किया। कई सत्रों में, उन्होंने ईमानदार प्रतिक्रिया के लिए 150 यूरो का भुगतान किया। इस प्रक्रिया ने उजागर किया कि वास्तविक उपयोगकर्ता छिपी हुई धारणाओं को उजागर करते हैं — जैसे sudo की आवश्यकता, रीबूट की आवश्यकता और उद्धरण नियम — जो डेवलपर अक्सर अनदेखा करते हैं। LLMs के विपरीत, वास्तविक लोग हास्य, अद्वितीय दृष्टिकोण और भावनात्मक संकेत जैसे निराशा लाते हैं, जो दस्तावेज़ीकरण की विफलता को इंगित करते हैं। लेखक इसकी तुलना अपने GOV.UK तकनीकी लेखन अनुभव से करते हैं, जहां मानव समीक्षा ने फूल भरी भाषा को स्पष्ट, उपयोगी दस्तावेज़ में बदल दिया। हालांकि README अभी भी पूर्ण नहीं है, लेकिन अब इसका पालन करना स्पष्ट रूप से आसान है। मुख्य सबक: डेवलपर को दस्तावेज़ीकरण का परीक्षण वास्तविक लोगों से करना चाहिए जो głos में सोचते हैं, भले ही अनभुगतान हों, ताकि अंधे बिंदुओं को खोजा जा सके और उपयोगिता में सुधार किया जा सके।

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.

開発者はしばしばユーザーが自分のバイアスや知識を共有していると仮定し、質の低いドキュメントを書く。これを克服するため、著者は実際のユーザーに時給25ユーロを支払い、Activity BotのREADMEを指示に従って声に出しながら画面を共有してテストさせた。これにより重大な欠陥が明らかになった：デモリンクが切れている、ファイル名の変更手順がわかりにくい、技術用語が不明確、セクションの順序が悪い、ソフトウェアの目的が説明されていない。著者は手書きのメモを取り、各セッション後にREADMEを更新し、新しいユーザーで再テストを行った。複数のセッションを通じて、率直なフィードバックに対して合計150ユーロを支払った。このプロセスは、実際のユーザーが開発者が見落としがちな前提条件―sudoの必要性、再起動の要件、引用ルール―を暴露することを示した。LLMsとは異なり、実際の人間はユーモア、独自の視点、イライラなどの感情的手がかりをもたらし、これがドキュメントがどこで失敗しているかを示す。著者はこれを自分のGOV.UKでの技術文書作成経験と比較し、そこで人間のレビューが花言葉のような散文を明確で使いやすいドキュメントに変えたことを指摘した。READMEはまだ完璧ではないが、今でははっきりと従いやすくなった。核心的な教訓：開発者はドキュメントを実際に声に出して考える人々（無報酬でも）でテストすべきであり、それによって盲点を発見し、使いやすさを向上させることができる。

Desenvolvedores frequentemente escrevem documentação ruim, supondo que os usuários compartilhem seus vieses e conhecimentos. Para superar isso, o autor pagou usuários reais €25 por hora para testar o README do Activity Bot seguindo as instruções em voz alta enquanto compartilhavam a tela. Isso revelou falhas críticas: links de demonstração quebrados, etapas confusas de renomeação de arquivos, termos técnicos pouco claros, má ordenação das seções e propósito do software não explicado.

O autor fez anotações manuscritas, atualizou o README após cada sessão e retestou com novos usuários. Em várias sessões, eles pagaram €150 por feedback franco. O processo destacou que usuários reais expõem suposições ocultas — como a necessidade de sudo, requisitos de reinicialização e regras de aspas — que os desenvolvedores ignoram.

Diferentemente de LLMs, pessoas reais trazem humor, perspectivas únicas e pistas emocionais como frustração, que indicam onde a documentação falha. O autor compara isso com sua experiência em redação técnica no GOV. UK, onde a revisão humana transformou prosa florida em documentos claros e utilizáveis.

Embora o README não seja perfeito, agora é demonstrativamente mais fácil de seguir. A lição principal: desenvolvedores devem testar documentação com pessoas reais que pensam em voz alta, mesmo que não sejam pagas, para descobrir pontos cegos e melhorar a usabilidade.

Разработчики часто пишут плохую документацию, предполагая, что пользователи разделяют их предубеждения и знания. Чтобы преодолеть это, автор заплатил реальным пользователям 25 евро в час за тестирование своего README Activity Bot, следуя инструкциям вслух, делясь экраном. Это выявило критические недостатки: сломанные ссылки на демо, запутанные шаги переименования файлов, непонятные технические термины, плохая структура разделов и необъясненное назначение программного обеспечения. Автор делал рукописные заметки, обновлял README после каждой сессии и повторно тестировал с новыми пользователями. За несколько сессий они выплатили 150 евро за откровенную обратную связь. Этот процесс показал, что реальные пользователи раскрывают скрытые предположения — например, необходимость sudo, требования перезагрузки и правила кавычек — которые разработчики упускают. В отличие от LLMs, реальные люди приносят юмор, уникальные точки зрения и эмоциональные сигналы, такие как разочарование, которые указывают на места, где документация терпит неудачу. Автор сравнивает это со своим опытом технического письма для GOV.UK, где человеческая проверка превратила цветную прозу в четкие и пригодные для использования документы. Хотя README пока не идеален, он теперь demonstrably легче для следования. Основной урок: разработчики должны тестировать документацию с реальными людьми, которые думают вслух, даже если это бесплатно, чтобы выявить слепые зоны и улучшить удобство использования.

开发者经常编写糟糕的文档，假设用户与他们有相同的偏见和知识。为了克服这一点，作者付费让真实用户每小时 25 欧元测试他们的 Activity Bot README，通过大声遵循说明并共享屏幕。这揭示了关键缺陷：损坏的演示链接、令人困惑的文件重命名步骤、不明确的技术术语、章节顺序不佳以及未解释的软件目的。作者做了手写笔记，在每次会话后更新 README，并用新用户重新测试。经过多次会话，他们为坦率反馈支付了 150 欧元。这一过程凸显了真实用户如何暴露隐藏的假设——比如 sudo 需求、重启要求和引用规则——这些是开发者容易忽视的。与 LLMs 不同，真实的人带来幽默、独特视角和情感线索，如挫败感，这些能指示文档失效的地方。作者将此与他们在 GOV.UK 的技术写作经验进行比较，在那里人工审查将花哨的散文转化为清晰可用的文档。虽然 README 仍不完美，但现在显然更易遵循。核心教训是：开发者必须让真实的人大声思考地测试文档，即使无偿，以发现盲点并提升可用性。