Nos trabalhos de curso de Informática há uma regra: entre os colegas cujo código funciona, metade perde pontos na documentação. Um README com uma única linha «run main.py», um relatório de laboratório que depende inteiramente de explicações orais e uma descrição de design sem uma única imagem — na hora de avaliar, o professor só vê a documentação. O pipeline de documentação do muchsci trata especificamente este tipo de penalização invisível.
Este artigo aborda separadamente a «vertente documental» dos trabalhos de curso e inclui uma linha de geração completa.
As quatro situações desastrosas da documentação
README desastroso: uma linha de comando para executar; instalação de dependências, requisitos de ambiente e dados de exemplo não estão escritos — o professor clona o projeto, não consegue executá-lo, e o teu código, por melhor que seja, vale zero.
Relatório de laboratório desastroso: o código funciona, mas o relatório não se consegue ler — por que razão se escolheu esta solução, como foram definidos os parâmetros, como foram analisados os resultados, tudo fica por adivinhar.
Descrição de design desastrosa: não há diagrama de arquitetura; as relações entre módulos ficam por imaginar.
Formato de submissão desastroso: entregar diretamente em Markdown perde todos os pontos de formatação — o professor quer um DOCX ou PDF com formatação normalizada.
Linha de geração: entra Markdown, sai produto final
Quem escreve código usa naturalmente Markdown para registar, o problema está apenas no «último passo». O muchsci encarrega-se desse passo: o código e as ideias são registados em Markdown (custo zero para programadores) e, quando é preciso submeter, são convertidos e formatados em Word; os diagramas de arquitetura são gerados diretamente a partir da descrição — «desenha um diagrama de arquitetura em três camadas e indica as relações entre módulos»; a revisão e a uniformização de formato do relatório de laboratório também são feitas pelo caminho.
Experiência ao longo de toda a linha: entra Markdown, sai Word com formatação normalizada, e o produto final vai diretamente para a pasta de entrega.
Checklist da documentação e pontos de intervenção
README em três partes: instalação (ambiente e dependências), execução (comandos e parâmetros), exemplo (exemplo de entrada e saída) — o muchsci ajuda-te a redigir segundo esta estrutura.
Relatório de laboratório: ambiente + método + análise de resultados; os gráficos de dados são desenhados diretamente pelo script.
Descrição de design: diagrama de arquitetura + descrição dos módulos; imagem e texto são produzidos em conjunto.
Versão de submissão: exportação normalizada em Word/PDF, com verificação de uniformidade de formato.
Quem sabe escrever código não devia perder pontos na documentação. O código fica desatualizado; a documentação clara vale sempre pontos — e não só nesta disciplina: depois de terminar o projeto de curso, organiza-o como material de portefólio; na época de procura de emprego, vais agradecer ao teu eu de agora.