Como documentar o notebook em projetos de ciência de dados?
Desenvolver uma boa comunicação é uma das principais habilidades a se aprimorar como profissional. Principalmente na área de ciência de dados que precisamos conversar com diversas pessoas que não são da área.
Estou realizando o Bootcamp Data Science da Alura e a cada módulo concluído, temos a possibilidade de desenvolver um projeto para aplicarmos todos os conhecimentos que tivemos no módulo.
Tenho utilizado principalmente o google colab como ferramenta para desenvolvimento.
Se você não sabe o que é o google colab ou o jupyter, confira este artigo e esse vídeo.
Mas apenas desenvolver algumas linhas de código e apresentar números e gráficos, não necessariamente explica o seu projeto. Documentar o que será feito, organizar as etapas, redigir os passos dados, além de comentar na própria linha de código, ajudarão muito a legibilidade e entendimento do seu projeto.
Para os bibliotecários (assim como eu), esta organização das informações é bem familiar a qualquer desenvolvimento de artigos científicos e tenho certeza que as aulas de normalização da ABNT trarão algum benefício para nós.
Neste artigo darei algumas dicas no qual eu venho aplicando em meus notebooks, para que você também possa colocar nos seus.
Bora lá?!
Sumário:
- Resumo e introdução
- Seções e índices
- Descrição das etapas
- Comentários nos códigos
- Considerações finais
Resumo e introdução
Além do título, você deve escrever uma boa introdução no início do seu notebook, para contextualizar o projeto para todos que irão ler.
Parta da ideia que a pessoa que está lendo, não sabe nada do assunto.
Coloque o objetivo e delimite todo o escopo.
Tenho certeza que te ajudará, até mesmo para quando você retomar (muitas vezes, você não terminará em um dia apenas).
Use de links no texto também e imagens além de recursos como negrito ou itálico.
O colab, assim como o jupyter notebook utilizam o markdown como padrão nos textos. Você pode ver um guia rápido do próprio colab aqui.
Aproveite e deixe ele bem claro, para que possa usar também no Readme do seu repositório do projeto no GitHub.
Não confunda com o readme do seu perfil. Caso o seu ainda não esteja bonitão como esse, não deixe de conferir esse artigo e esse para dar aquele upgrade.
Então use e abuse desses recursos!
Seções e índices
Outro ponto importante é organizar seu notebook por seções.
Você que é bibliotecário, se lembra do sumário e das alíneas (aquelas subdivisões do documento, conforme a NBR 6024) da ABNT?
Use esse conhecimento aqui.
Muita gente não gosta, mas quando você aprende a normalizar… gente que sucesso é escrever trabalhos.
Esse índice lateral:
Ajuda muito a qualquer pessoa se localizar no notebook.
Quebre cada seção com os # no Markdown.
Outro ponto importante é a customização da cor das suas seções.
Eu uso o notebook com o tema escuro, você pode escolher com tema claro, mas use a possibilidade de mudar de cor a sua escrita e aproveite de cores que contrastam.
Usei de recursos de html que ajudam nisso:
Use a cor em hexadecimal e aproveite
Descrição das etapas
Descreva o que você irá fazer em cada etapa, dialogue com o leitor.
Explicar detalhadamente, poderá ajudar terceiros a entender, assim como seus colegas (em trabalhos em equipes) ou mesmo você daqui a algum tempo.
Documentar qualquer projeto é de suma importância!
Comentários nos códigos
Pode parecer bobo e até repetitivo, mas isso pode ajudar a entenderem como você pensou para conduzir até o objetivo.
Explique a linha de código que você escreveu. Utilize o # para anular a escrita à direita e mande bala!
Considerações finais
Desenvolver projetos com uma melhor documentação, vale para qualquer projeto que você faça.
Sempre haverá o que melhorar e indico você sempre persistir nesta habilidade. Descrever os projetos de forma completa, concisa e simples não é fácil, mas com a prática ela virá.
Agora me diga, dentre as dicas, você conheceu algo novo? Tem alguma outra que você gostaria de compartilhar?
Escreva nos comentários e compartilhe comigo.
Se você chegou até aqui e curtiu, dê o claps, compartilhe e se inscreva para me acompanhar.
Porque…
Ainda há muito a se explorar…
