Faça um favor para si e para os outros - escreva Documentação

Você está todo animado e ansioso por começar, você deu duro no teste técnico e na entrevista com o seu Gestor, e finalmente você vai começar a colocar a “mão na massa”.

Mas, todos os teus sonhos e esperanças, vão pouco a pouco sendo consumidos pelas semanas que vão se passando, o projeto está confuso e difícil de entender o que foi feito e o que é esperado.

“Mas e a documentação?” _ Perguntas tu… 🤔

A resposta:

Isso nos remete a um problema antigo na Engenharia de Software: Documentação

Mas, porque os desenvolvedores não documentam o seu trabalho? Como essa prática pode salvar o seu dia?

Vamos falar disso neste artigo.


Porque os desenvolvedores não documentam o seu trabalho?

1- Tempo : Os desenvolvedores têm 2 dias para fazer o que se faria em 5 dias de alterações, sem esquecer os testes e, em seguida, mais 5 dias para corrigir os problemas encontrados pelo controle de qualidade, a maioria dos quais não estavam nas especificações originais.

Depois de 2 semanas trabalhando em uma tarefa de “2 dias”, ninguém está esperando que você entre no Confluence(ou outra ferramenta) e digite algum documento bem fofo sobre como seu código funciona e uma lista de cada entrada, saída, caso de uso, tipo de exceção, etc.

2 - Negligência: Provavelmente esse seja o motivo mais relevante. Mas, as pessoas devem se lembrar que nós esquecemos das coisas, e alguns dias depois podemos não ter ideia do que acabamos por implementar.

Por outro lado, normalmente não trabalhamos sozinhos, temos uma equipa que vai beneficiar de uma documentação clara e descritiva e que descreve os requisitos técnicos e funcionais do projecto.

3 - Escopo mal definido: Por vezes o escopo do projeto muda com muita facilidade, então alguns pensam: porque perder tempo a documentar esse modulo e daqui a pouco vão mudar completamente ele?


Como essa prática pode salvar o seu dia?

Neste ponto, gostaria de contar uma história em um projeto onde trabalhei:

Entrei como desenvolvedor Back-End Laravel em uma startup Brasileira, estava ansioso para começar a gerar valor para a empresa.

Como bom escoteiro perguntei onde estava a documentação da Api, e a resposta foi um grande e seco: “Não temos isso, eu(CEO da startUp) entendo bem a regra de negócio, qualquer dúvida eu explico, dê uma olhada no código e você vai entender”.

A Partir desse momento eu dei conta que as coisas não dariam certo, mas, clonei o projeto e fiquei algumas horas analisando e tirando dúvidas. E depois de 4 horas eu não entendi Patavina de Nada. As variáveis eram confusas, cada módulo que existia no projeto, eu sabia o que fazia, mas não os detalhes, cada serviço externo que ele comunicava eu não fazia ideia do que se passava.

O projeto passou na mão de várias pessoas, e cada um veio, fez o que lhe apeteceu e foi embora, deixou uma bagunça sem documentação. Sem falar que o código estava muito amarrado, uma alteração em uma função alterava outra parte do código.Mexer no projeto estava a tornar-se inviável.

Até aqui talvez você notou que o único problema não é a documentação, mas que ela é a base, não podemos mexer em algo que desconhecemos os detalhes. Costumo comparar isso a um cirurgião, um cirurgião não vai começar uma cirurgia se não conhece a parte do corpo que ele vai trabalhar, o mesmo é com os engenheiros, não trabalhamos sobre terreno minado, nem muito menos desconhecido.

Eu fiz a minha parte, documentei o que eu pude,e espero que os outros continuem com essa boa prática.

Acho que a lição ficou subentendido, então vou clarear: Faça um favor para mim e para ti e para os outros e documente o que você fez.

Hoje temos ferramentas simples, Confluence, GitHub Wiki, ou ser for uma Api temos o Postman, o Swagger.

No final de contas, esse detalhe separa os meninos dos Homens.

Boa semana de trabalho.

Did you find this article valuable?

Support Tilson Mateus by becoming a sponsor. Any amount is appreciated!