A documentação no desenvolvimento de software é frequentemente vista como algo de pouco valor. No âmbito desta documentação incluem-se as documentações de negócio, de produto, de requisitos e a documentação técnica de software. Esta última tem sido frequentemente ignorada ou até descartada por equipas de desenvolvimento. Este módulo foca-se na documentação técnica, apresentando formas de gerar documentação técnica simples e útil, destacando também o impacto da sua ausência.
Com a adoção de métodos ágeis e outras mudanças nos processos de desenvolvimento de software, algumas práticas associadas a modelos mais tradicionais são por vezes ignoradas ou descartadas. Uma dessas práticas é a documentação técnica de software.
Normalmente vista como burocrática e rapidamente desatualizada, a documentação técnica herda uma carga negativa de modelos como a UML. Quando confrontada com a necessidade de "maior velocidade" das equipas, é considerada uma atividade que não gera valor.
De facto, em muitos projetos, a documentação existente confirma esses pontos negativos. Contudo, a médio e longo prazo, descartar totalmente a prática de documentar pode gerar dificuldades de padronização e desnível de conhecimento, podendo impactar inclusive a citada "velocidade" das equipas e contribuir para a necessidade de constantes refatorações de software.
Manter documentação burocrática e sem utilidade não é desejável; contudo, não ter documentação pode ser mais prejudicial!
O desafio é gerar documentações simples, fáceis de serem mantidas e que gerem valor às equipas. Atualmente, muitas ferramentas contribuem para isso, aproximando a documentação do código fonte, ou através da geração automática ao analisar o código. Mas estas ferramentas ainda não substituem por completo algumas boas práticas que podem ser utilizadas pelos(as) desenvolvedores(as).
Para verificar como as equipas estão a trabalhar com este tema, podem-se observar algumas situações que ocorrem no dia a dia, tais como:
Quando algumas destas situações ocorrem, é um sinal de que a documentação pode não estar a ser útil. A sequência deste texto aborda como as equipas de desenvolvimento podem trabalhar para ter uma documentação técnica útil e que seja uma aliada no dia a dia.