Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Documentação Contínua: se não está documentado,...

Documentação Contínua: se não está documentado, seu projeto não existe

Apresentado na PythonBrasil[15] em Ribeirão Preto-SP.

Renne Rocha

October 27, 2019
Tweet

More Decks by Renne Rocha

Other Decks in Technology

Transcript

  1. 1

  2. Why good JavaScript libraries fail 1. Falta de documentação. Não

    importa quão maravilhosa seja sua biblioteca e quão inteligente é o seu design. Se você é o único que a entende, ela não serve para nada. Documentação não significa apenas referências de API geradas automaticamente, mas também exemplos bem escritos e tutoriais detalhados. Você precisa dos três para garantir que sua biblioteca seja facilmente adotada. Nicholos Zakas (https://humanwhocodes.com/) 4
  3. Documentação incompleta ou desatualizada é um problema generalizado, observado por

    93% dos participantes da pesquisa, além disso 60% dos contribuidores disseram que raramente ou nunca contribuem com documentação. GitHub Open Source Survey 2017 (https://opensourcesurvey.org/2017/) 5
  4. 6

  5. O problema é que qualquer código que você escreveu e

    que você não olhou nos últimos seis meses, vai parecer ter sido escrito por outra pessoa. Conway, Damian - Perl Best Practices 8
  6. Se as pessoas não sabem por que seu código existe,

    elas não o utilizarão. Se as pessoas não conseguem entender como instalar seu código, elas não o utilizarão. Se as pessoas não conseguem entender como usar o seu código, elas não o utilizarão. 10
  7. Mudanças na documentação são muito menos assustadoras que mudanças em

    código Pode ser um primeiro passo para conhecer o projeto e no futuro contribuir com alterações em código 12
  8. ...documentação é uma carta de amor que você escreve para

    você mesmo no futuro. Conway, Damian - Perl Best Practices 14
  9. 15

  10. 17

  11. Que problema seu projeto resolve Exemplo de código Instruções de

    Instalação Link para código e issues FAQ Como conseguir suporte Como contribuir Licença do projeto 21
  12. Documentation will never be part of engineering culture until it

    is integrated into the codebase and engineering workflow Riona MacNamara, Google (https://www.youtube.com/watch?v=EnB8GtPuauw) 23
  13. Benefícios Responsáveis por escrever se integrando melhor com o time

    de desenvolvimento Quem desenvolve geralmente fará o primeiro esboço da documentação (ou toda) Você pode bloquear a introdução de novas funcionalidades se não houver documentação (incentiva quem desenvolveu a documentar quando a funcionalidade ainda está "fresca" na cabeça) 26
  14. Criar cultura onde todos sentem que tem a propriedade e

    responsabilidade sobre a documentação 27