Documentação, uma “opção” (necessidade!) para o bom andamento do projeto

Uma das etapas mais importantes de um projeto, porém muitas vezes ignorada, é a de documentação do mesmo.

Muitas empresas,  desenvolvedores e analistas não tem o hábito de gerar documentação, porém, se forem definidos alguns detalhes (modo de atualização, nível de detalhamento, complexidade) o custo-benefício e tempo investido serão vantajosos.

Podemos considerar a documentação sob duas vertentes: “Documentação de Requisitos” e “Documentação do Programa”. Neste post, vamos analisar a documentação do Programa.

Por exemplo: quantos de vocês já necessitaram refazer / alterar por diversas vezes um programa que no início do projeto não teve seus requisitos bem compreendidos? O fato é que se este levantamento for bem feito e documentado, os riscos de rework, falhas, não atendimento aos prazos propostos, dentre outros, certamente serão minimizados, além de permitir uma visualização global do projeto, facilitando o seu gerenciamento e identificação de melhorias.

Considerando a documentação de programas, podemos citar alguns benefícios, tais como:

Facilidade de manutenção: todos nós sabemos que comumente um programa é desenvolvido por uma pessoa e recebe manutenção por outra (ou outras). Já pararam para pensar em quanto tempo de análise de código e qualidade podemos ganhar caso haja uma documentação bem feita e atualizada?

Transmissão de conhecimentos: muitos não costumam pensar sob a perspectiva que vou expor agora, mas independentemente de sermos contratados direta ou indiretamente por uma empresa, como CLT ou como PJ, somos contratados para gerar lucros e DEVEMOS pensar como empresa. Desta forma, é através da documentação que transmitimos nossos conhecimentos, seja de negócios, seja da parte técnica, a continuidade do projeto não deve depender dos conhecimentos de uma só pessoa.

Re-utilização de API´s: quando bem documentadas podem facilitar muito a rotina de um programador, que pode reutilizar de maneira fácil e rápida trechos de códigos já existentes (como classes e function modules, por exemplo), ganhando em tempo de desenvolvimento, qualidade e padronização de código.

Existem algumas ferramentas para auxiliar na geração de tais documentos, dentre elas, recomendamos o projeto open source ABAPDoc2, que gera as doumentações em HTML (o que possibilita sua análise sem a necessidade de acessar o SAP) e fornece informações sobre a composição de classes e seus métodos, function groups e seus function modules (parâmetros de importação / exportação, tabelas, dentre outros), assim como possibilita a exibição de comentários inseridos no header dos códigos, facilitando o entendimento técnico  e suas funcionalidades.

Este projeto é bastante indicado para documentar outros projetos open source, porém não é aplicável nos casos de documentação de requisitos, pois a necessidade é outra.

E então, prontos para colocar a  mão na massa? Baixe já e conheça o ABAPDoc2.