Por Tammy Xu
Jordan Merrick tem plena consciência de como é difícil fazer as pessoas lerem a documentação. Como redator técnico para a plataforma de desenvolvimento de ferramentas Retool, seu trabalho é criar documentação para os usuários.
"Costumo brincar dizendo que os usuários nunca leem a documentação", disse Merrick. "Eles são muito impacientes, querem poder experimentar o produto o mais rápido possível, e a documentação é percebida como uma barreira para isso."
Dicas para uma documentação mais envolvente:
A documentação deve ser fácil de encontrar e ler
Armazenar a documentação próxima ao código-base é uma boa alternativa a pastas compartilhadas obscuras. Isso facilita encontrar a documentação e, como os desenvolvedores a veem com mais frequência, também é mais provável que a mantenham. Incluir funcionalidade de busca e uma estrutura clara que apresente o conteúdo e inclua visões gerais de alto nível permite aos usuários navegar rapidamente pelas informações relevantes.
Revisões de código? Experimente revisões de documentação.
Assim como nas revisões de código, é uma boa ideia trazer outros revisores para o processo de documentação — idealmente desde o início, mesmo enquanto o código está sendo escrito. "Não deixe uma única pessoa, ou apenas um subconjunto de pessoas, escrever", disse Jon Quigley. "Todos que estiveram envolvidos com o projeto deveriam fazer parte do seu desenvolvimento."
Não deixe a documentação ficar desatualizada
Os usuários rapidamente descartam a documentação desatualizada. As equipes de desenvolvimento devem ter um processo para manter e atualizar sua documentação. Na Deephaven Data Labs, os engenheiros executam testes noturnos tanto na documentação quanto no código. "Realmente percebemos que a documentação desatualizada leva à frustração. E isso leva os usuários a irem para outro lugar."
Nem todos os produtos precisam do mesmo nível de documentação
Andreas Nomikos, engenheiro de software na Connectly, acredita que é possível ter documentação em excesso. "Nas equipes de produto, geralmente a taxa de mudança no código-base é muito rápida. Investir muito tempo em documentação não gera um bom retorno sobre o investimento porque você pode estar construindo algo que muda em seis meses."
Uma boa documentação deve abordar o porquê
Algumas pessoas querem uma visão geral de alto nível, enquanto outros usuários são desenvolvedores que procuram guias de baixo nível. "Cada usuário chega a esse software com um contexto diferente e, muitas vezes, com um objetivo diferente." Incluir uma página de "primeiros passos" pode servir como um diretório que esclarece o propósito e aponta para recursos adicionais.
Torne a documentação mais interativa
"Desenvolvedores somos pessoas de ação, queremos programar e queremos fazer as coisas acontecerem. Por que eu deveria ir à documentação e ler tudo quando posso simplesmente programar e experimentar?" Documentação acoplada ao código que inclui tanto texto explicativo quanto referências ao código-base pode animar um documento de referência que de outra forma seria monótono.
Cultive uma cultura de documentação
"Se você não acertar a cultura, nada mais que você diga ou coloque no papel vai importar", disse Quigley. Os gerentes devem promover uma cultura de documentação reservando sempre tempo durante os ciclos de desenvolvimento para atualizar e manter a documentação existente — independentemente da situação.
©️ 2025 Todos os direitos reservados. Connectly Inc. Desenvolvido com ❤️, globalmente.