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