Letramento informacional de dados: Documentando códigos de software
Se você já precisou documentar qualquer processo ou produto sabe o quão trabalhoso é, mas se você já fez, talvez saiba da importância e relevância que uma boa documentação traz.
Códigos de softwares também precisam ser documentados para que possam ser compartilhados e entendidos por outras pessoas. Nem sempre eles são bem documentados ou legíveis o que ocasiona erros inexplicáveis ou mesmo a inutilização do código.
Ensinar como documentar um código de software dentro de uma equipe de engenharia em uma universidade, foi o desafio relatado no capítulo 5 do livro:
“Data Information Literacy: Librarians, Data, and the Education of a New Generation of Researchers” (clique aqui para acessá-lo).
Caso você esteja chegando agora nesse texto, confira aqui a listagem dos demais.
No texto de hoje, abordarei os principais tópicos do capítulo.
Bora lá?!
Sumário
Contexto
O projeto foi realizado na Purdue University em parceria com Engineering Projects in Community Service (EPICS), um projeto existente na universidade que tem como objetivo ensinar conceitos e habilidades de engenharia para alunos de graduação que trabalham em soluções comunitárias.
A ideia do EPICS é integrar diversos estudantes em um projeto único potencializando e fortalecendo as lacunas deles e ao mesmo tempo solucionar problemas da comunidade.
É um ambiente onde exigia muito aprendizado dos alunos, devido a prática real dos conhecimentos estudados.
Várias abordagens de ensino eram realizadas e dentre elas entravam algumas oficinas de linguagens de programação (como C++, Java e desenvolvimento mobile).
Cada aluno era responsável por realizar a documentação que descrevesse a sua parte no trabalho, tanto dos códigos quanto de documentos descritivos (docs básicos).
Mas mesmo com toda essa estrutura eles ainda não tinham uma cultura de prática de documentação muito forte e era bastante difícil para os líderes dos projetos auxiliarem todas as pessoas com “boas práticas” de documentação.
Surgiu então a oportunidade para a equipe de letramento informacional de dados atuar.
“Faz parte da curadoria de dados e da preservação digital prestar atenção no código de software, pois ele fará parte de um conjunto de dados ou de um objeto digital”.
Ao realizarem o estudo prévio para o projeto eles relataram que encontraram alguns conceitos “sinônimos” entre as comunidades de curadoria e software, como a rastreabilidade e a proveniência de software.
Esses conceitos são relacionados ao processo de garantia de qualidade da decisões tomadas ao longo do desenvolvimento do código (quem, o que, onde, quando e por que).
Além disso chegaram na escola de “programação alfabetizada” e “código legível por humanos”.
Sim, programação não é para falar apenas com a máquina e precisamos prestar muita atenção para deixar legível para outras pessoas entenderem.
“A atividade de programação deve ser encarada como um processo de criação de obras de literatura, escritas para serem lidas.”
— DE Knuth, Programação Alfabetizada
Com a continuidade dessa linha de pensamento chegaram no Robert C. Martin , com a sua obra Código Limpo.
Essa obra é uma referência essencial para as pessoas da área de desenvolvimento de software. Eu ainda não a li, mas confesso que está em minha lista e provavelmente em algum momento você vai ver nesse blog algumas considerações minha sobre ele.
Cada vez mais a qualidade de software no mundo dos dados está evoluindo e se você está nessa área, vai valer a pena você se aperfeiçoar ainda mais nessa linha.
Estrutura do projeto
Devido a estrutura de projetos do EPICS e o pouco tempo dos alunos para atividades extras eles decidiram implantaram um “serviço de bibliotecário” dentro das equipes, alinhados com os líderes.
“A biblioteconomia incorporada é um método particularmente promissor para a implementação da instrução de alfabetização informacional devido à apresentação de competências de forma mais imediata”.
Dentro das equipes eles desenvolveram principalmente 3 frentes:
- Apresentação expositiva: Ofereceram uma sessão de treinamento de habilidades sobre documentação de código e trabalho do projeto.
- Referência: Participaram de sessões de laboratórios e equipes de observação.
- Revisão: Participaram como revisores na avaliação dos alunos em sessões de revisão do projeto.
Resultados
Embora o tenham tido um feedback positivo, ninguém relatou uma mudança substancial nas atividades dos alunos ao escrever e documentar código.
Compartilhar a responsabilidade de documentação e descrição ao invés de ter apenas uma pessoa com a responsabilidade direta dessa tarefa foi uma das principais causas da baixa qualidade de documentação.
A estrutura de squad já foi citada nesse ponto e trouxeram até mesmo um papel de “arquivista de projetos” como responsável para auxiliar as equipes.
Outra ideia que surgiu dentro do projeto foi de criar um serviço de referência central para os alunos aprenderem habilidades de documentação de códigos e dados. Como um canal no Youtube com vídeos curtos, cobrindo todos os tópicos necessários.
"Uma biblioteca do YouTube criaria uma referência pronta para as necessidades que surgem enquanto os alunos estão praticando ou expandindo seus conjuntos de habilidades."
Considerações finais
A abordagem da biblioteconomia incorporada exigiu muito planejamento e investimento para a equipe, mas valeu toda a prática e conhecimentos adquiridos no processo.
Eles também relataram algumas características do perfil da pessoa bibliotecária que estaria nessa abordagem:
- Ter bons relacionamentos
- Flexibilidade para se adequar ao contexto
- Dedicação e comprometimento com a equipe
É engraçado, mas eles de alguma forma se relacionam com as características que eu já escrevi sobre, nesse texto aqui:
Esse capítulo tocou vários pontos de interconexões entre a biblioteconomia e a tecnologia nesta linha de serviços referenciais da biblioteconomia de dados.
Levarei comigo vários destes que mais para frente aprenderei mais e talvez traga aqui nesse blog, como foi o caso do “Código limpo” e até mesmo das metodologias ágeis (que ficaram nas entrelinhas do texto).
Eu ainda não fiz todos os cursos da formação, mas sei que na Alura tem vários dentro desse contexto, como essa formação:
Esse é um dos motivos do porque gosto tanto da Alura. Essa possibilidade de quantidade de cursos que ela te oferece dentro de um mesmo plano.
Caso você não seja aluna(o) ainda, confira meu cupom de desconto especial aqui.
Agora me diga, você já conhecia alguma prática de documentação de software? Tem algum texto, curso ou referência para compartilhar?
Deixe nos comentários.
Se você chegou até aqui e curtiu, dê palmas, compartilhe e se inscreva para me acompanhar.
Ainda há muito a se explorar…
Textos anteriores
Caso você ainda não tenha lido os textos anteriores, não deixe de conferir eles:
