Documentação no processo de desenvolvimento de software muitas vezes é vista como algo de pouco valor. Estão no escopo documentações de negócio, de produto, de requisítos, e a documentação técnica de software. Esta última geralmente tem sido ignorada ou até descartada por times de desenvolvimento. O tema foca nela apresentando formas para gerar documentação técnica simples e útil, destacando também o impacto de não tê-la.

Com a adoção de métodos ágeis e outras mudanças nos processos de desenvolvimento de software, algumas práticas atreladas a modelos mais tradicionais são algumas vezes ignoradas ou descartadas. Umas destas práticas é a documentação técnica de software.

Vista normalmente como algo burocrática e rapidamente desatualizada, ela herda uma carga negativa de modelos como a UML e quando confrontada com a necessidade de “maior velocidade” dos times é considerada uma atividade que não gera valor.

De fato, em muitos projetos as documentações existentes confirmam esses pontos negativos, porém 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 na citada “velocidade” dos times e contribuir para necessidade de constantes refatorações de software.

Manter documentação burocrática e sem utilidade não é algo desejável, porém não ter documentação pode ser mais prejudicial!

O desafio é gerar documentações simples, fáceis de serem mantidas e que gerem valor aos times. Atualmente muitas ferramentas contribuem para isso ao aproximar a documentação ao código fonte, ou através da geração automática ao analisar o código. Mas elas ainda não substituem por completo algumas boas práticas que podem ser utilizadas por desenvolvedores(as).

Para verificar como os times estão trabalhando com esse tema, pode-se observar algumas situações que ocorrem no dia a dia, como:

• Pessoas fazendo perguntas semelhantes repetidamente.
• Documentação sempre desatualizada com relação ao que está implementado.
• Documentação técnica maior e/ou mais complexa que o código fonte.

Quando algumas destas situações ocorrem é um sinal de que a documentação pode não estar sendo útil. A sequência do tema aborda como times de desenvolvimento podem trabalhar para ter uma documentação técnica útil e que seja uma aliada no dia a dia.

O que documentar

O primeiro passo é saber o que documentar e isso pode se tornar difícil e variável de acordo com as características e complexidades de cada projeto. Uma boa abordagem é realizar dois questionamentos simples:

• Quais perguntas as pessoas fazem repetidamente?
• Quais informações são conhecidas somente quando perguntado a pessoas específicas?

As respostas são provavelmente informações que devem ser documentadas!

Para exemplificar, segue abaixo questões geralmente repetitivas nos times:

Nestes casos, as pessoas que detêm mais informações se tornam o ponto de referência para responder tais questões. Isso pode trazer reflexos negativos, pois geralmente elas se tornam as mais consumidas do time, o que pode ser um mau uso do tempo delas. Considerando que normalmente descarta-se a documentação para poupar tempo, se torna contraditório então usar o tempo desta forma.

Para evitar a dependência e uso inadequado do tempo das pessoas, o roteiro abaixo orienta à documentar:

Como documentar

As formas de como documentar podem variar de acordo com necessidades, composição de projetos e inclusive preferências pessoais. No guia a orientação é evitar o uso de modelos e artefatos morosos, embora existam ainda hoje setores que exijam tais documentações, o que por vezes impõe aos times a forma de como documentar.

Mais importante do que a forma e ferramentas, é entender se o time está confortável para produzir e consumir a documentação.

Pode não haver um consenso em como documentar, mas é necessário que os times cheguem a um acordo, e após isso sejam responsáveis e comprometidos em manter a documentação.

Um ponto de partida para como documentar pode ser através do uso de uma antiga prática, o arquivo README na raiz de cada projeto com código fonte. Nele podem estar documentadas ou haver links para as informações relacionadas ao projeto. Seu uso inclusive é estimulado por ferramentas como GitHub, GitLab, BitBucket, dentre outras, onde o mesmo pode ser escrito no formato Markdown e se torna o “cartão de visita” do projeto.

O README não precisa necessariamente conter uma documentação detalhada, mas pode ser o ponto de conexão a todas documentações existentes. O conteúdo nele pode ser estruturado seguindo os itens sugeridos no roteiro do tópico anterior. A seguir um exemplo.

Um projeto fictício de nome Guia Hóspede, o qual está desenvolvendo uma solução para reservas de hotéis, possui implementado vários projetos com código fonte, abaixo segue o README.md de um destes projetos, o hoteis-service:

No arquivo estão descritas todas informações necessárias para desenvolvedores(as) poderem atuar sobre o código, além de links a diversos materiais complementares onde poderão aprofundar o conhecimento.

Nos subtópicos a seguir, é detalhado como documentar cada item do roteiro.

Objetivo do projeto.

O objetivo em um arquivo README pode estar no bloco inicial de informações contendo:

• Descrição técnica do objetivo do código.
• Links para conteúdos técnicos adicionais.
• Link para materiais relacionados ao negócio, como o Modelo de negócio, Personas, Modelo de domínio, Épicos e História

Para conteúdo adicional, pode-se também fazer o uso de arquivos Markdown e eles podem estar em um diretório docs na raiz do projeto.

Analisando mais de perto o exemplo do hoteis-service, segue o bloco inicial:

A descrição do projeto é simples e direta com relação ao que é o projeto. Há também uma breve explicação do contexto a qual o projeto pertence e o foco das API’s implementadas nele, além de links para outras documentações.

Outras descrições de projetos do Guia Hóspede:

• stays-service: Serviço de Backend com as API’s do contexto de estadias.
• accounts-service: Serviço de Backend com as API’s do contexto de contas.
• travel-routing-lib: Biblioteca de roteirização de viagens e hotéis.
• guia-hospede-web: Frontend Web para as funcionalidades da solução Guia Hóspede.
• guia-hospede-admin-web: Frontend Web para funcionalidades administrativas da solução Guia Hóspede.
• guia-hospede-mobile: Frontend Mobile para as funcionalidades da solução Guia Hóspede.
• stays-payments-job: Jobs para processamento de pagamentos das estadias.

Dependendo da estruturação técnica da solução, algumas informações dizem respeito à solução como um todo e não a um código fonte específico. Para esses casos, uma boa prática é usar outras fontes para documentação e fazer o links a ela no arquivo README. Para essas documentações indica-se o uso de:

• Wikis, podendo ser ferramentas online ou rodando em infraestrutura interna.
• Plataformas SaaS de documentação e gestão de conteúdo como GitBook, Confluence, dentre outros.
• Plataformas SaaS para documentos como Google Drive, Office 365, dentre outros.

Arquitetura e stack

Documentar a arquitetura e stack pode variar de acordo com a complexidade da mesma.

Por exemplo, arquiteturas monolíticas podem ter artefatos diferentes de arquiteturas em microsserviços, onde a primeira poderá ter apenas uma documentação da sua arquitetura salva no próprio projeto e a segunda poderá ter uma documentação geral de estruturação dos serviços salva externamente.

Para ambas situações, há algumas boas práticas que podem ser aplicadas:

• Oferecer uma breve descrição sobre a arquitetura utilizada.
• Quando a arquitetura segue um padrão ou estilo conceitual, não é necessário detalhar o conceito, basta citar o padrão ou estilo criando um link para um conteúdo confiável que detalhe o mesmo.
• Caso a documentação de arquitetura esteja em um arquivo próprio, citá-lo no README com um link para o mesmo.
• Fazer uso de desenhos para representar a arquitetura. Esta prática está detalhada no tema Desenhos técnicos no guia.
• Citar a linguagem e frameworks utilizados, informando no máximo a sua versão major. Isso porque normalmente o detalhe das versões está no arquivo de configuração da ferramenta de dependências utilizada, logo não é necessário ter informações duplicadas.
• Informar as dependências do projeto, sejam as de outros serviços, projetos ou bibliotecas. Para caso de bibliotecas, o ideal é apenas citar ou fazer um link ao arquivo de configuração.

Seguindo o exemplo do hoteis-service, o bloco Arquitetura e stack:

As descrições referentes à arquitetura buscam esclarecer quais as utilizadas, fazendo link para conteúdo que detalham os padrões e estilos citados. Além disso, como é uma arquitetura de microsserviços, há um link para o desenho de arquitetura da solução do Guia Hóspede.

Há uma breve descrição de como está organizada a arquitetura do projeto em específico, com link para um arquivo Markdown adicional no projeto que mostra a organização de camadas.

Por fim, informações relacionadas a stack utilizada, integrações e dependências, sempre com links para conteúdos mais aprofundados sobre cada item, podendo ser material externo ou do próprio time.

Acesso e execução do código

Saber onde está o código fonte parece algo simples, mas muitas vezes se torna uma dificuldade em times de desenvolvimento.

A forma para documentar essa questão pode variar de acordo com a ferramenta utilizada para versionar o código. No passado, ferramentas focadas nesse assunto não proviam portais de acesso aos usuários, era necessário registrar o local do projeto em outros documentos ou apenas na memória.

Atualmente, ferramentas como as já citadas GitHub, GitLab, BitBucket, permitiram uma grande evolução na gestão de código fonte, o que tornou dispensável documentos auxiliares para esse tipo de informação.

O recomendável é o uso desta ferramentas, onde desenvolvedores(as) com seus usuários poderão ver todos os projetos com código fonte aos quais possuem acesso.

Ainda assim, é importante seguir algumas boas práticas para facilitar a localização do projeto:

• Uso de nomes adequados ao objetivo do código e que evitem confusões a desenvolvedores(as).
• Uso do campo de descrição do projeto com conteúdo inicial usado no README.
• Organização dos agrupamentos e permissões de acesso. Dar acesso a todos os projetos sem qualquer critério polui a visão da lista de projetos.

Seguindo o exemplo do hoteis-service, o mesmo está configurado assim:

• Nome: hoteis-service. Um nome direcionado ao negócio e ao que é o código.
• Descrição: Serviço de Backend com as API’s do contexto de hotéis. Que é o texto apresentado no início do README.
• Acesso: Core Team. Que é um grupo de desenvolvedores(as), o que simplifica a gestão.

Nas informações de execução do projeto, o README pode conter:

• Configurações necessárias no ambiente para rodar com sucesso o projeto.
• Instruções para uso da ferramenta de build adotada no projeto.
• Os comandos necessários para rodar o projeto localmente e demais scripts auxiliares.

No exemplo do hoteis-service, são citados:

• As variáveis de ambiente cuja confoguração é necessária.
• Uso da ferramenta Make para build, com link para sua documentação oficial e detalhamento das targets.
• Uso da ferramenta docker-compose para facilitar e padronizar a execução do projeto localmente, também com link para documentação oficial.

Alterações, testes e validações

Uma das atividades mais realizadas por desenvolvedores(as) sobre um código fonte será a de modificá-lo, logo é essencial que esteja documentado o processo utilizado pelo time para alterar, testar e validar suas alterações, sejam com testes automatizados (que é o mais adequado) ou acessando e usando o sistema localmente.

No exemplo do hoteis-service:

Estão descritas:

• Que as alterações seguem um processo de Git Flow, com um um link para detalhamento deste processo que é geral a todos os times.
• A ferramenta de testes automatizados utilizada, junto ao comando de execução.
• O comando para validação de qualidade do código.
• A forma de visualização e execução das API’s, no caso utilizando a ferramenta Swagger.
• Informação de que são aplicados testes de integração e aceitação, com links para respectivas documentações. Outros integrantes do time no papel de QA’s são os responsáveis por implementar e manter tais testes.
• Link para lista de ambientes onde o serviço está publicado. No caso com o uso da ferramenta GitLab, um link para página de ambientes que a própria ferramenta disponibiliza.

Além das informações descritas no exemplo, pode-se também documentar:

• Comandos auxiliares para geração/carregamento de cenários de dados.
• Dados de autenticação para acesso ao sistema, considerando inclusive informações de usuários de papéis diferentes quando existentes.

Atualização e monitoramento

Para atualizar o software em um ambiente, normalmente há passos que devem ser seguidos e é importante que essas informações estejam documentadas.

Ao colocar em um ambiente uma nova versão, principalmente em produção, desenvolvedores(as) precisam também saber como monitorar e verificar problemas no software caso eles ocorram.

Essas informações normalmente estão documentadas fora do projeto, é adequado então fazer o link para tais conteúdos.

Seguindo o exemplo do hoteis-service:

Está descrito que há um processo de Merge request (o mesmo que Pull request), com um link para o detalhamento do mesmo.

Para monitoramento do serviço e acesso a logs, há um link para a documentação fornecida pelo time de Infraestrutura.

Manutenção e utilização

Além do como documentar há também o desafio de manter e utilizar a documentação técnica.

Para manter uma documentação atualizada é necessário comprometimento e responsabilidade dos times para tal atividade. Uma boa prática é documentar antes de implementar. Isso evita cair na armadilha de passar para outras tarefas porque a anterior já parece estar pronta. Nesse caso documentar, quando necessário, se torna o trabalho inicial de uma tarefa de implementação, semelhante ao TDD para testes automatizados.

Outro aspecto que estimula os times manterem atualizadas as documentações é perceberem que elas são utilizadas. Nesse sentido deve-se buscar:

• Indicar a documentação sempre que as pessoas perguntarem sobre algo que esteja devidamente documentado. Se há documentação não deve-se usar muito tempo para repetir verbalmente informações contidas nelas.
• Usar a documentação em reuniões e momentos de decisões onde elas possam colaborar para clareza das conversas.
• Dar espaço a todos para contribuírem nas documentações, de forma que possam editá-las sempre que houver algo novo ou a ser corrigido.

No sentido inverso do tema, há alguns pontos aos quais deve-se evitar gerar documentações auxiliares pois estas normalmente não são utilizadas e são difíceis de serem mantidas. Abaixo segue alguns:

• Código fonte: Um ponto polêmico entre desenvolvedores(as), cuja questão não está em documentar ou não o código fonte, mas sim o porquê e como documentar. Um código bem escrito, que segue as práticas de Código Limpo (Clean Code) teoricamente não precisa de documentação. Ainda assim há casos onde uma documentação pode ser útil, porém ela precisa ser simples. Se ela se torna complexa provavelmente é porque o código está complexo.
• Modelagem detalhada: É válido ter documentação sobre a modelagem da solução, seja de entidades, de componentes, dentre outros. Porém ela deve apenas prover a visão resumida do todo. Detalhes que são voláteis normalmente se tornam desatualizados na documentação. O código é a fonte mais confiável.
• Diagramas de classe: Ter um diagrama sobre as classes base de um projeto pode ser útil, porém representar todas as classes normalmente se torna uma documentação com pouca utilidade e desatualizada. A preferência normalmente será ir diretamente ao código fonte.
• Funcionalidades: Documentação técnica sobre funcionalidades pode ser válida para questões não mapeadas a nível de negócio. O importante é não repetir conteúdo já presente em Histórias, Casos de uso, ou outras documentações de negócio e requisítos, pois é normal as funcionalidades evoluírem e tais documentações técnicas não.

Uma boa documentação técnica contribui para eficiência e escala de times de desenvolvimento. Criar e mantê-la é um sinal de profissionalismo e maturidade.

O que e como documentar pode ser sempre adaptado conforme as necessidades, inclusive complementado com o tema Desenho Técnico, para buscar o nivelamento de conhecimento, diminuição do tempo usado com perguntas repetidas e evitar informações retidas apenas “na memória das pessoas”.