Documentação de Desenvolvimento

Nos meus anos de desenvolvimento vi muitos projetos. Alguns caótico outros bem definidos.

Vou apresentar aqui uma breve apresentação sobre documentação de desenvolvimento.

Muitas vezes pegamos projetos bem elaborados, com documentação precisa. Que por vezes são encaminhados aos programadores.

Estes programadores, criam os artefatos desenhados. Onde são testados pelos analistas de testes.

E por fim, passados para o cliente, onde sofrem validações. Sendo ou não modificados.

Por fim, no ciclo final, a documentação é gerada para o Cliente, orientando como realizar.

Neste ciclo de projeto bem elaborado e muitas vezes idealizado, documentos são criados na fase de fazer, e por fim na etapa de entrega.

Percebemos que existem 2 documentos criados:

• Documentação de Projeto – O que precisa, elencando os artefatos necessários para a entrega.
• Manual de Usuário – O manual, contem a experiência de uso. Diz como realizar, é básicamente uma cópia da documentação do projeto, após acabado.

Perceba, caro leitor, que temos, duas etapas, onde criamos documentação para os clientes, porem o conhecimento do que foi feito, continua na mão de quem fez.

De fato, muitos podem chegar a conclusão equivocada, que é obrigação de quem programa, entender o código.

Para contestar essa afirmação, vou apresentar duas alusões:

Imaginemos que lemos um livro de Shakespeare, como por exemplo macbeth Espera-se que após esse ponto, tenhamos o entendimento da obra.

E possamos responder a qualquer questão, correto?

Bom olhando alguns sites:

https://www.britishcouncil.org.br/atividades/shakespeare-lives/escolas/dicas/macbeth

https://www.conjur.com.br/2011-jul-31/embargos-culturais-licoes-historia-direito-macbeth

https://institutoling.org.br/explore/licoes-sobre-ambicao-e-poder-em-macbeth

Perceba que de fato, a leitura do livro, pode não trazer a visão do detalhe, que passará desapercebido, em uma leitura plana.

O mesmo acontece com o programador, muitas vezes lemos trechos de código, não nos atentando para detalhes ou melindres do programador original.

Tal ardil só será revelado, após maior exposição ao conteúdo da obra.

Perceba que documentação, não tem a obrigação de explicar o óbvio, mas apresentar as verdades ocultas. Que seriam reveladas, apenas uma leitura mais densa, envolvendo e consumindo horas de trabalho exaustivo.

Qual objetivo da documentação do programador

Após a explanação anterior, percebemos, que a documentação técnica visa apresentar detalhes ou dicas que de fato fugiriam da atenção.

Documentando e apresentando de forma clara e direta.

Formas de fazer isso:

HOWTO

A primeira forma de fazer isso, é a criação de um roteiro, onde por exemplo elaboramos uma “receita de bolo” da elaboração da atividade de uma forma genérica. O intuíto deste trabalho é conduzir o programador novato na realização da atividade, evitando que este incaia em caminhos poucos produtivos.

Documentação Técnica

Em sistemas complexos, a documentação técnica exige que todo o código passe por uma revisão, apresentando detalhes de informações de entrada e resultados (saída).

De forma geral, a documentação técnica custa caro, pois precisa ser revisionada, a cada novo lançamento.

Provas e treinamento

Treinar pessoas é qualificar estas para realização das atividades. O processo de treinamento exige que apresentemos o problema, entreguemos a solução e testemos o conhecimento.

Hoje existem diversos softwares destinados a este fim, entre eles o moodle. Que permite que utilizemos recursos multi mídia para treinar pessoas ou grupos. Testando a qualidade dos mesmos.

Problemas relacionados

Prazo x Qualidade

Muitas vezes para cumprir prazos temos que simplificar ou omitir certas etapas do processo produtivo. De forma geral, a primeira coisa que se tira é a documentação técnica, a justificativa é bem simples. Documentação técnica não é para o usuário, é para a própria empresa. Sendo assim, o usuário ou o cliente não sentirá falta.

A omissão deste muitas vezes justificada, tem consenquências a médio e longo prazo.

De fato um sistema complexo muitas vezes exige um volume enorme de conhecimento prévio, que exige um esforço na obtenção por parte do programador. Muitas vezes esse esforço é utilizado em outro momento como moeda de barganha, para negociação salarial.

A diferença de Ser e Ter

A grande maioria das empresas de software detem o direito legal do produto, mas de fato não os tem.

A bem da verdade ser da empresa, não necessáriamente diz que a empresa o têm.

Muitas vezes, a empresa, precisa de pessoas especificas, para modificar pontos chave. Quando um produto exige que um individuo especifico o modifique, de fato a empresa é refem de um individuo. Sendo de fato o detentor do direito, mas não tendo a capacidade de gerir suas mudanças.

Sobre este argumento, que percebemos a necessidade da gestão interna.

Como fazer

Programador Estépe – No seu carro, quando o pneu fura, vc tem um segundo pneu, pois sabe se perder o primeiro, ficará no meio da estrada sem conseguir seguir. O mesmo acontece com seu produto. Muitas vezes centralizamos tudo em uma pessoa, pois ele é eficiente, barato, e resolve o meu problema. Dai o empresário pensa, bom vou deixar na mão dele. Ele resolve isso, eu fico com o negócio, os clientes e o que espero do produto. Um belo dia, o seu funcionário vai embora, morre ou aposenta. Se voce não tiver um plano B, ficará a mercê do colaborador.

Muitas vezes manter um programador redundante é complicado, pois exige um investimento alto.

Rotatividade de funções – A rotatividade de funções é quando em uma equipe (squad) temos pessoas que fazem a mesma coisa. Alternando entre elas.

De forma geral, a rotatividade não funciona, na prática o PO (product Owner) sempre elegerá o programador que sabidamente tem melhor performace para uma determinada especialidade. Criando um especialista. De fato, mesmo com a pseudo rotatividade, sempre haverá individuos que sabem mais que outros, em um sistema rotativo. Esta rotatividade tem um ponto fraco, juntamente com o programador estépe. Conta com o conhecimento das pessoas. Não mantendo este na empresa.

Vídeos e Treinamentos – Durante o ciclo de treinamento, muitas vezes apresentamos processos para recrutas (programadores junior) que desenvolvem a capacidade de realizar o processo. Porem tal treinamento é perdido no momento da saída do recruta. Uma forma de manter, é não gerar o treinamento diretamente, mas sim indireto, exigindo que o Analista Sr, grave um vídeo que será depois passado ao recruta. Onde este questionará suas duvidas, que tambem serão armazenadas em um Howto.

De forma geral, a apresentação audio visual, é sempre melhor que o treinamento presencial. Pois permite primeiro armazenamento e depois correções evolutivas.

Tambem cria ou propicia a faze do aprendizado, permitindo que duvidas comuns sejam feitas e respondidas de forma coletiva.

Auto treinamento – O Ciclo de auto treinamento, exige que disponhamos de tempo produtivo, para capacitar da melhor maneira o colaborador.

Como realizar, a bem da verdade existem duas maneiras de aplicar isso:

1. Dentro do ciclo produtivo, neste processo, o colaborador durante o ciclo de trabalho, realiza pequenos treinamentos, onde se capacitará para execução de atividades extras.
2. Fora do ciclo produtivo, a capacitação fora do ciclo produtivo, deve ser qualificativa, onde o colaborador ganha de forma indireta, através de melhora salarial ou premiações.

Espero que a apresentação destas dicas tenham inspirado voces nas melhores práticas de desenvolvimento.

PS: Apenas para mostrar o óbvio, em um dado momento, disse que iria apresentar 2 alusões, e apresentei apenas 1. Mas voce não percebeu, a segunda alusão é voce. Pois de fato, não se ateve a esse detalhe. Agora imagina o programador.

Boa sorte.