Documentação de Software

O que documentar neste projeto?

Documentação em projetos/produtos digitais é importante para transferir conhecimento sobre o projeto. Prazo para completarem a documentação: 26/06. Nas próximas seções são descritos os requisitos de documentação dos projetos desta disciplina:

Código

Sabemos que o principal artefato de um projeto é o código em si, afinal é ele que descreve o comportamento do sistema. Quando falamos em código, estamos também falando do código de testes (a famosa malha de testes automatizados).

Código bem escrito é documentação. Isso é o principal. Design bem feito reflete-se em código claro, portanto também é documentação. Código de teste de unidade, de teste de integração, de teste de aceitação etc, também é documentação.

Documentação dentro do código pode ser relevante em alguns pontos do sistema.

Artefatos deste projeto

• Histórias desenvolvidas, com link para a versão correspondente no repositório.
• Lista de bugs conhecidos e dívida técnica como “issues”.
• Apresentações de showcase (fazer upload de todas), com link para a versão correspondente no repositório.
• Fazer um resumo de todas as práticas ágeis adotadas, colete fotos do time e do ambiente. Descreva um pouco sobre como isso ajudou o desenvolvimento e lições aprendidas.

Questões éticas

Descreva algumas questões éticas em aberto sobre o uso das APIs das redes sociais. Para ajudar nisso, vocês podem dar uma olhada no artigo:

Claudia de O. Melo and Thiago C. de Sousa. 2017. Reflections on cyberethics education for millennial software engineers. In Proceedings of the 1st International Workshop on Software Engineering Curricula for Millennials (SECM '17). IEEE Press, Piscataway, NJ, USA, 40-46. https://arxiv.org/pdf/1703.00619.pdf A Tabela 1 mostra um resumo de questões éticas em tecnologia e artigos relacionados.

Organizando o projeto (de software livre) para iniciantes

(Baseado em: STEINMACHER, Igor; TREUDE, Christoph; GEROSA, Marco Aurélio. Let me in: Guidelines for the Successful Onboarding of Newcomers to Open Source Projects, IEEE Software, v.PP (99), 2018.)

Crie uma página ou portal específico para iniciantes (pode ser um arquivo .md com nome bem CLARO). Página estruturada, com informações limpas e organizadas mostrando:

• O que é essencial para os primeiros passos, como o projeto é organizado e quais são os recursos importantes (por exemplo, repositório de código, listas de discussão, rastreador de problemas, canal de IRC e ferramentas de revisão de código).
• Aponte os iniciantes para tarefas fáceis: "Encontrar uma tarefa para começar". Esclareça como é o processo de contribuição.
• Mantenha a lista de problemas atualizada: Fornecer uma lista marcada de issues (requisitos/bugs) é um grande suporte a recém-chegados.
• Torne mais fácil para os recém-chegados fazer o build do sistema localmente. Assim, crie um guia só para isso.
• Para ajudar os recém-chegados a entender o código, os projetos devem documentar a estrutura do código. É importante documentar claramente a estrutura organizacional do código e como os componentes, módulos, classes e pacotes se relacionam entre si. Use diagramas que mostram como o projeto é organizado.

Alguns exemplos de projetos de software livre e sua documentação https://github.com/paulormm/analizo https://github.com/fga-gpp-mds/Falko-2017.2-FrontEnd

Quer ler mais sobre documentação de projetos de software? Dê uma olhada em: http://www.agilemodeling.com/essays/agileDocumentationBestPractices.htm