Tweet
Tweet

Slide 1

Slide 1 text

1

Slide 2

Slide 2 text

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

Slide 3

Slide 3 text

Renne Rocha Python Developer @Scrapinghub Grupy-Campinas | Grupy-Jundiaí Laboratório Hacker de Campinas @rennerocha (Telegram, GitHub, etc...) renne@rennerocha.com 3

Slide 4

Slide 4 text

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

Slide 5

Slide 5 text

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

Slide 6

Slide 6 text

6

Slide 7

Slide 7 text

Você estará usando o seu código em 6 meses 7

Slide 8

Slide 8 text

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

Slide 9

Slide 9 text

Você quer que as pessoas utilizem o seu código 9

Slide 10

Slide 10 text

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

Slide 11

Slide 11 text

Você quer que as pessoas contribuam 11

Slide 12

Slide 12 text

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

Slide 13

Slide 13 text

Você quer que seu código seja melhor 13

Slide 14

Slide 14 text

...documentação é uma carta de amor que você escreve para você mesmo no futuro. Conway, Damian - Perl Best Practices 14

Slide 15

Slide 15 text

15

Slide 16

Slide 16 text

Usuários Desenvolvedores 16

Slide 17

Slide 17 text

17

Slide 18

Slide 18 text

Usuários não querem documentação, usuários querem respostas! 18

Slide 19

Slide 19 text

Normalmente o README é o primeiro contato da pessoa com o seu projeto. 19

Slide 20

Slide 20 text

Readme Driven Development http://bit.ly/readme-driven-development Original: http://tom.preston-werner.com/2010/08/23/readme-driven-development.html 20

Slide 21

Slide 21 text

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

Slide 22

Slide 22 text

Docs-As-Code 22

Slide 23

Slide 23 text

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

Slide 24

Slide 24 text

Documentar utilizando as mesmas ferramentas usadas para fazer o código 24

Slide 25

Slide 25 text

Issue Trackers Controle de Versão (Git) Texto-plano (Markdown, reStructuredText, Asciidoc) Revisão de Código Testes Automatizados 25

Slide 26

Slide 26 text

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

Slide 27

Slide 27 text

Criar cultura onde todos sentem que tem a propriedade e responsabilidade sobre a documentação 27

Slide 28

Slide 28 text

Onde hospedar? 28

Slide 29

Slide 29 text

https://readthedocs.org/ 29

Slide 30

Slide 30 text

https://pages.github.com/ 30

Slide 31

Slide 31 text

Geradores de Páginas Estáticas 31

Slide 32

Slide 32 text

http://www.sphinx-doc.org/en/master/ 32

Slide 33

Slide 33 text

https://www.mkdocs.org/ 33

Slide 34

Slide 34 text

Linguagens de Markup 34

Slide 35

Slide 35 text

https://www.writethedocs.org/guide/writing/markdown/ 35

Slide 36

Slide 36 text

http://docutils.sourceforge.net/rst.html 36

Slide 37

Slide 37 text

http://asciidoc.org/ 37

Slide 38

Slide 38 text

Comunidade 38

Slide 39

Slide 39 text

https://www.writethedocs.org/ 39

Slide 40

Slide 40 text

OBRIGADO! 40