Paguei pessoas para tentar seguir meu README

Artigo original ↗ Discussão no Hacker News ↗

Pagar pessoas para seguir o README de um projeto como se fosse um roteiro expõe quantas suposições, omissões e distrações entram na documentação para desenvolvedores. Comentadores argumentam que READMEs devem dizer claramente o que o software faz, listar pré-requisitos e fornecer um caminho mínimo e ponta a ponta para a configuração, com muitos criticando o excesso de emojis, piadas internas e “slop” gerado por IA que obscurecem informações essenciais. Vários apontam que esse tipo de teste com usuários reais espelha práticas de usabilidade de UX e complementa verificações automatizadas ou revisões baseadas em LLM, que ainda não conseguem julgar clareza, tédio ou confusão como humanos.

Reação geral a “pagar pessoas para seguir meu README”

  • Muitos veem isso como testes de usabilidade padrão aplicados à documentação técnica.
  • Vários elogiam a ideia e dizem que práticas internas semelhantes (integrar novos contratados via README, registros de fricção) detectam muitos problemas rapidamente.
  • Alguns argumentam que muitas vezes você mesmo consegue identificar a maioria dos problemas simplesmente seguindo rigorosamente suas próprias instruções em uma máquina limpa.

Nível de detalhe e pré-requisitos

  • Há um forte sentimento de que READMEs frequentemente omitem etapas críticas “zero” (por exemplo, instalar php-fpm, runtimes ou ferramentas).
  • O consenso é que uma seção clara de “Pré-requisitos” é fundamental, mesmo que você não explique como instalar cada dependência.
  • Há debate sobre até onde voltar: alguns querem comandos desde git clone em diante; outros observam que não dá para listar todo sistema operacional/gerenciador de pacotes.

Estilo: concisão, estrutura e o que o software faz

  • Reclamação frequente: READMEs que nunca dizem claramente o que o projeto faz, apenas como instalá-lo ou listam buzzwords.
  • Muitos preferem READMEs curtos e orientados a tarefas, que sirvam como ponto de entrada para documentação mais rica, em vez de longos “romances” ou FAQs.
  • Frameworks como Diataxis e a divisão entre tutorial e referência são vistos como úteis para estruturar a documentação.

Tom: emojis, piadas e personalidade

  • O uso excessivo de emojis é amplamente rejeitado; muitos associam READMEs cheios de emojis a conteúdo gerado por LLM ou à infantilidade.
  • Humor leve é aceitável para alguns, desde que não obscureça o significado; outros argumentam que piadas e referências culturais são confusas e não valem o risco.
  • Várias pessoas observam que o que é engraçado para o autor muitas vezes não funciona para os leitores.

Humanos vs. IA/agentes em testes de documentação

  • Vários sugerem que LLMs e agentes são bons para:
    • Seguir instruções passo a passo em sandboxes.
    • Destacar etapas ausentes e inconsistências.
  • Mas os humanos são vistos como essenciais para:
    • Julgar o tédio, a clareza e a UX geral.
    • Expor suposições, linguagem confusa e lacunas culturais/de conhecimento.

Fricção de instalação e automação

  • Muitos lamentam projetos que não “funcionam de primeira”, mesmo com READMEs.
  • Conteinerização (Docker) e ferramentas de ambiente (Nix, direnv) são elogiadas por configurações reproduzíveis e de baixa fricção.
  • Alguns argumentam que software verdadeiramente polido deveria automatizar a configuração em vez de depender fortemente de READMEs manuais.