Documentação de projeto de software é a resposta para garantir alta qualidade e longevidade

Design
• 12 jan 2023

Este artigo explica por qual motivo a documentação de projeto de software é crucial para um bom resultado. Além disso, é um guia prático para escrever a documentação mínima em um repositório de projeto.

Eu sei… neste momento, você está se preparando para deixar este artigo.

A documentação de projeto de software não é um assunto da moda, como microsserviços, Kubernetes, cloud native etc. No entanto, uma boa documentação garante um projeto escalável, sustentável e saudável.

Vamos explicar como manter um projeto melhor taticamente através da documentação.

Por que precisamos de documentação?

A primeira pergunta sobre a documentação é: por que você deveria gastar tempo com a documentação em vez do código?

O desenvolvimento de software é caro e devemos garantir que esse projeto tenha uma vida longa. Para tornar isso possível, precisamos facilitar a vida de uma futura pessoa engenheira.

Portanto, uma boa documentação de projeto de software pode nos ajudar a:

torná-lo mais natural para devs que trabalharão no projeto;
explicar o motivo de algumas decisões em torno do design do código e, eventualmente, da arquitetura;
evitar cometer o mesmo erro duas vezes;
reforçar que o conhecimento não pode se perder quando as pessoas saem de uma organização;
lembrar que não temos o poder de ler a mente das pessoas. Confie em mim, eu tentei várias vezes.

Documentação de projeto de software? Que tal uma nova tendência tecnológica

Muitas vezes, as pessoas vêm até mim para pedir conselhos sobre projetos de software e, geralmente, enfrentam esses problemas que acontecem após três anos do projeto:

as pessoas precisam de ajuda para entender o atual código do projeto;
ainda estamos determinando o porquê das decisões anteriores;
é difícil manter o código;
o software continua mudando;
existem componentes que as pessoas precisam conhecer para dominar o que estão fazendo, mas é difícil.

Sim, esses são grandes problemas em qualquer organização e queremos resolvê-los. Ainda assim, uma proposta de solução segue um caminho diferente: reescrever um projeto do zero com a nova linguagem tecnológica, a arquitetura.

A parte triste é que não resolverá o problema por completo. De fato, depois de três anos, uma nova equipe no mesmo projeto vai enfrentar o mesmo impasse.

A solução vem com a simplicidade da documentação de projeto de software. Mas por que não pensar nisso primeiro? Porque temos um viés em torno da complexidade!

É inconsciente, mas está lá. O artigo “Complexity Bias: Why We Prefer Complicated to Simple” explica porque não gostamos do simples: acreditamos que falhará.

Até mesmo temos um nome para essa complexidade desnecessária na engenharia de software: over-engineering. E já sabemos que também não vai ajudar a resolver o problema.

Inclusive, existem dois excelentes livros que explicam sobre complexidade:

Just Enough Software Architecture: A Risk-Driven Approach, que menciona o poder da simplicidade e o design orientado a riscos;
A Philosophy of Software Design, que segue a mente de Leonardo Da Vinci: simplicidade é a sofisticação máxima.

Para acelerar e lutar contra nosso inconsciente, siga o caminho mais simples e não subestime o poder da documentação de projetos de software.

Vamos falar sobre escalabilidade

A escalabilidade vai além da possibilidade de aumentar o número de instâncias do aplicativo. É o poder de lidar com a quantidade de:

pessoas;
culturas;
qualidade de software;
metodologias de organização;
objetivos da empresa.

E a documentação de projeto de software pode ser uma boa aliada nisso.

Inimigo vs. Aliado

“Espere: o que você quer dizer com ‘pode’?”

Como acontece com qualquer decisão em software, há uma compensação. Portanto, nenhuma documentação de projeto de software implica em ler a mente das pessoas, mil reuniões e escalar duramente toda a organização.

Considerando que uma documentação excessiva é difícil de manter e se torna um livro sofisticado que ninguém lê ou entende, o equilíbrio certo é a fórmula. Assim pequenas e contínuas entregas de documentação ajudam a encontrar essa estabilidade, sempre pensando que todas ações podem ser revertidas, caso não façam sentido para uma melhor documentação.

Porém, como chegar nessa fórmula? Como saber a quantidade certa para a minha organização?

Não existe uma fórmula mágica, afinal, cada projeto ou organização dependerá do contexto do qual ele está inserido. A metodologia sempre seria trabalhar de forma incremental e caminhar no sentido do impacto da entrega de uma peça.

Para facilitar essas entregas, é importante ter uma documentação que traz uma visão de maior amplitude organizacional, estratégica e tática dentro do seu projeto.

Separando as duas visões documentacionais, vamos adentrar e discutir quais são os primeiros passos para trabalhar a documentação em cada uma das categorias.

Arquitetura x Design e Tática x Estratégia

Precisamos de um artigo inteiro só para tentar uma definição de todos esses termos. Afinal, há uma quantidade enorme de literatura sobre eles.

No Domain-Driven Design (DDD), temos as visões tática e estratégica onde o processo está mais próximo do código com design e padrões como repositório, agregador e entidade, etc.

Ainda assim, o livro Filosofia de Design de Software traz uma abordagem diferenciada, onde tática é fazer as coisas e a estratégia é supervisionar o código.

Não vamos cobrir a definição desses termos aqui, abordaremos Documentação para Design e como fornecer um repositório de projetos, como quais são as etapas mínimas para arquivar um bom software.

Do ponto de vista arquitetural, temos o Architecture by Advice de Andrews Law ou Scalability in the architecture de Otávio Santana, onde ambos propuseram o início de uma boa documentação usando:

Modelo C4;
Radar tecnológico (Tech Radar);
Comunicação limpa ou fórum;
Registro de decisão de arquitetura (ADR).

Colocar em prática

Agora que explicamos o escopo deste artigo, vamos colocar em prática respondendo a pergunta anterior: dado um repositório de projeto, quais são seus requisitos mínimos?

Usando o princípio do equilíbrio certo, listamos três:

README;
Changelog;
Documentação do código.

Vamos falar mais sobre esses três pontos, mas primeiro precisamos entender Markdown vs. Asciidoc.

Markdown vs. Asciidoc

As duas primeiras partes da documentação que abordaremos em breve são baseadas em um único arquivo que você pode ver on-line. É um princípio básico de qualquer documentação, deve ser visível e de fácil acesso.

Se o repositório do seu projeto estiver no GitHub, você pode estar familiarizado com o Markdown. Na verdade, é uma ótima linguagem de marcação leve para criar texto formatado.

Além disso, também temos as ferramentas Asciidoc tools, inclusive várias fontes abertas estão migrando para ele principalmente porque é mais direto e robusto. Se você possui um arquivo Markdown e deseja migrar para o Asciidoc, não é difícil fazê-lo.

Frequentemente, queremos uma tabela de conteúdo nos arquivos readme e change log.

Onde no Markdown precisamos fazer isso manualmente:

# Table of Contents
1. [Example](#example)
2. [Example2](#example2)
3. [Third Example](#third-example)
4. [Fourth Example](#fourth-examplehttpwwwfourthexamplecom)

## Example
## Example2
## Third Example

Enquanto no Asciidoc, precisamos preencher uma única linha :toc: auto.

:toc: auto

## Example
## Example2
## Third Example

Markdown e Asciidoc têm suporte GitHub para visualizar no navegador. Vale a pena experimentar.

Arquivo Leiame (README)

Este arquivo LeiaMe (ou README) é a primeira impressão do seu projeto; este pode ter informações consideráveis e transparentes, principalmente porque outra pessoa deve cuidar dele.

Existem vários bons READMEs de projetos:

Usando-os como referência, criei meu modelo de estrutura README:

= Project Name
:toc: auto

== Introduction

A paragraph that explains the "why" or reason for this project exists.

== Goals

* The goals on bullets
* The second goal

== Getting Started

Your reader gets into here; they need to know how to use and install it.

== The API overview

The coolest features here

== To know more

More references such as books, articles, videos, and so on.

Registo de alterações (Changelog)

Um changelog é um log ou registro de todas as alterações notáveis feitas em um projeto. Isso reduz seu trabalho indo para um git log.

= Changelog
:toc: auto

All notable changes to this project will be documented in this file.

The format is based on https://keepachangelog.com/en/1.0.0/[Keep a Changelog],
and this project adheres to https://semver.org/spec/v2.0.0.html[Semantic Versioning].

== [Unreleased]

=== Added
- Create

=== Changed

- Changed

=== Removed

- Remove

=== Fixed
- Ops, fixed

== [old-version] - 2022-08-04

Por que o código autocomentado é uma utopia?

Antes de tudo, vale lembrar que um código autocomentado é aquele onde o nome das variáveis descrevem o que são ou armazenam. A documentação existe justamente para fazer esse papel de detalhamento.

Por outro lado, softwares com destaque na indústria, com vários cases reais e décadas de existência, possuem boa documentação até no código. Esses poucos softwares duraram mais de duas décadas e ainda são relevantes no mercado:

Java – mais de 25 anos;
Hibernar – mais de 20 anos;
Linux – mais de 30 anos.

Para saber mais sobre a documentação

Este artigo é uma breve visão de como explorar uma boa documentação de projeto de software. Ainda há muito para se abordar sobre o assunto e dicas para se dar.

Como referência de livro e aprofundamento desses temas existe o Docs for Developers: An Engineer’s Field Guide to Technical Writing, nele o foco principal é tratar a documentação como um produto e quem lê como uma pessoa usuária.

O livro explica várias técnicas para dar uma melhor experiência para quem vai consumir a documentação. É daqueles livros para ter na biblioteca.

Além disso, no Jakarta NoSQL, decidimos passar um mês inteiro estudando, analisando e aplicando uma melhor cultura de documentação nesses repositórios:

Conclusão

Espero que você goste desta jornada e artigo sobre qualidade de código usando documentação de projeto de software. É descomplicado, mas eficiente e garante mais contribuição ao projeto de código.

Você pode aproveitar para aplicar no seu projeto e, uma vez que eles sejam de código aberto, sinta-se à vontade para contribuir para tornar a documentação e o código ainda melhores.

Gostou do artigo? Então compartilhe sua experiência com documentação de projetos nos comentários, vamos adorar conversar sobre o tema.