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.
Fonte: Hacker News · Resumido por HeadlinesBriefing