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

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

Transcript

2. Documentação Contínua: se não está documentado, seu projeto não existe 2
3. Renne Rocha Python Developer @Scrapinghub Grupy-Campinas | Grupy-Jundiaí Laboratório Hacker de Campinas @rennerocha (Telegram, GitHub, etc...) renne@rennerocha.com 3
4. 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
5. 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
7. Você estará usando o seu código em 6 meses 7
8. 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
9. Você quer que as pessoas utilizem o seu código 9
10. 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
11. Você quer que as pessoas contribuam 11
12. 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
13. Você quer que seu código seja melhor 13
14. ...documentação é uma carta de amor que você escreve para você mesmo no futuro. Conway, Damian - Perl Best Practices 14
16. Usuários Desenvolvedores 16
18. Usuários não querem documentação, usuários querem respostas! 18
19. Normalmente o README é o primeiro contato da pessoa com o seu projeto. 19
20. Readme Driven Development http://bit.ly/readme-driven-development Original: http://tom.preston-werner.com/2010/08/23/readme-driven-development.html 20
21. 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
22. Docs-As-Code 22
23. 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
24. Documentar utilizando as mesmas ferramentas usadas para fazer o código 24
25. Issue Trackers Controle de Versão (Git) Texto-plano (Markdown, reStructuredText, Asciidoc) Revisão de Código Testes Automatizados 25
26. 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
27. Criar cultura onde todos sentem que tem a propriedade e responsabilidade sobre a documentação 27
28. Onde hospedar? 28
29. https://readthedocs.org/ 29
30. https://pages.github.com/ 30
31. Geradores de Páginas Estáticas 31
32. http://www.sphinx-doc.org/en/master/ 32
33. https://www.mkdocs.org/ 33
34. Linguagens de Markup 34
35. https://www.writethedocs.org/guide/writing/markdown/ 35
36. http://docutils.sourceforge.net/rst.html 36
37. http://asciidoc.org/ 37
38. Comunidade 38
39. https://www.writethedocs.org/ 39
40. OBRIGADO! 40