Design Docs: a importância da documentação técnica no desenvolvimento de software

Já se perguntou sobre quantos projetos você já teve que decifrar e interpretar para tentar entender o que algo faz, quais são as integrações existentes e, o principal, essa foi realmente a melhor alternativa? No pior dos cenários, nem mesmo a própria equipe sabe sobre os detalhes.

Negligenciar a documentação de features segue sendo um problema comum atualmente, o que gera mal-entendidos, falta de alinhamento entre os membros da equipe e, consequentemente, retrabalho.

A necessidade de aumentar a visibilidade sobre a implementação de soluções se torna cada vez mais essencial, seja para desenvolvedores, que precisam entender como as soluções se encaixam no quadro geral, ou especialistas em negócio, que precisam ter visão sobre se o que será implementado realmente atende o que foi pedido e a complexidade envolvida.

O Design Doc existe para auxiliar nessa tarefa. É um documento contendo detalhes sobre o objetivo, motivações, estratégias e trade-offs e outros pontos sobre a implementação de uma solução.

Para entender melhor sobre como o Design Doc auxilia na tarefa de trazer visibilidade para as pessoas envolvidas, temos que entender como funciona o seu ciclo de vida.

Ciclo de Vida de um Design Doc

O ciclo de vida de um Design Doc é um processo contínuo e dinâmico, que envolve iteração entre escrita, revisão e ajustes. Esse ciclo só muda após a solução seguir para produção, onde passamos a fazer a manutenção do arquivo sempre que algum ajuste for implementado na solução.

Criação e Interação inicial

O documento é criado e os tópicos essenciais são preenchidos. É recomendado envolver toda a equipe que trabalhará na solução e as pessoas com conhecimento sobre o tema no início do processo. O ideal é que todos contribuam com dúvidas e sugestões até a conclusão da primeira versão do documento.

Revisão e Melhorias

O documento criado é compartilhado com os interessados (ou também com pessoas que podem não ter conhecimento sobre o assunto, como outras equipes da mesma tribo, por exemplo). Nessa fase, é encorajado que todas as pessoas cientes sobre a documentação possam dar sugestões, desde que faça sentido, que melhore as explicações dadas no documento ou até mesmo sugerir uma solução diferente.

O processo de revisão pode envolver várias rodadas e é concluído quando a equipe e os envolvidos entendem que todas as dúvidas foram resolvidas e os detalhes pertinentes foram bem descritos.

Implementação e Iteração

Com base no objetivo, fluxos, payloads, integrações e no plano de implementação documentados, a equipe pode começar a dividir tarefas, refinar detalhes e dar início a implementação, sempre seguindo o que foi documentado e revisado.

Como sempre há a possibilidade de mudança de requisitos, detalhes e outros pontos. É recomendável que o documento seja atualizado de acordo com esses novos detalhes e revisado novamente, pelo menos até que a feature ou serviço sejam publicados em produção.

Manutenção

Com o passar do tempo, correções e melhorias podem na solução podem tornar o documento não condizente com a implementação atual. Portanto, é recomendado que tanto o autor do documento quanto a equipe responsável revisitem e atualizem o conteúdo, se necessário.

Vale a pena notar que, mesmo que não seja possível manter o documento atualizado, ele ainda é de extrema importância. Isso se deve ao fato de que ele ajuda a entender como a solução foi concebida, levando em conta as motivações e trade-offs no momento de sua criação.

O que escrever em um Design Doc

Abaixo estão alguns tópicos que podem auxiliar na elaboração de um documento bem estruturado e com detalhes relevantes. Vale ressaltar que, dependendo da solução, nem todos os tópicos são necessários.

Contexto: visão geral das motivações para o novo desenvolvimento, o que precisa ser desenvolvido e o impacto resultante do desenvolvimento;

Fora de escopo: quais pontos não estão inclusos no escopo da solução, a fim de deixar claro que algo específico não será desenvolvido;

Solução atual: fluxogramas da solução existente e descrição dos problemas que devem ser resolvidos com a nova solução;

Proposta de solução: sub-tópicos descrevendo com detalhes a proposta de solução para o problema apresentado, como:

• Visão geral: descrição e desenho da nova solução. É recomendado utilizar alguma ferramenta que possibilite a alterações de forma fácil;
• Novos recursos: novos recursos a serem criados. Como exemplo, podemos descrever novos serviços, APIs, filas, tópicos. Utilize tabelas contendo o nome, descrição e tecnologias utilizadas nos novos recursos;
• Fluxos e diagramas: diagramas de sequência, fluxo, ou qualquer outro que ajude a descrever features, integrações e interações. É recomendado utilizar alguma ferramenta que possibilite a alterações de forma fácil, como o Mermaid;
• Payloads e integrações: alterações em payloads existentes e criação de novos payloads de API, mensagens, etc. É recomendado utilizar o formato JSON ou até mesmo o mapeamento de classes para facilitar o entendimento;
• Alternativas consideradas: soluções, fluxos e decisões que foram consideradas e os motivos pelo qual acabaram não entrando na proposta de solução final;

Monitoramento e alertas: o que precisa ser monitorado, métricas da aplicação e os alertas a serem criados. Anexar dashboards existentes e canais de comunicação para a notificação de alertas;

Segurança da Informação: autenticações, permissões e credenciais necessárias, detalhes sobre mascaramento de dados, e informações referentes a segurança dos dados e integrações;

Preocupações gerais: perguntas ou tópicos em aberto que possam impactar o desenvolvimento da solução proposta;

Plano de implementação: sugestão de quebra de tarefas de forma sequencial, até o deploy total da solução proposta;

Equipes envolvidas: quais equipes estão envolvidas no desenvolvimento da proposta de solução, seja por conta de implementações ou simplesmente por serem impactadas;

Referências: páginas, documentos, tarefas e links que serviram de referência para o desenvolvimento do documento;

Você também pode consultar outros exemplos de Design Docs na biblioteca do designdocs.dev: https://www.designdocs.dev/library

Quando criar um Design Doc?

Nem sempre é necessária a criação de um Design Doc. Tarefas de baixa complexidade ou impacto normalmente não se beneficiam com a criação desse tipo de documento.

O ideal é que a equipe entenda e defina se a tarefa é complexa o suficiente ou pode trazer um impacto considerável nas soluções existentes para justificar o tempo a ser investido na criação e revisão do documento.

Além disso, é interessante criar um Design Doc sempre que uma nova feature for implementada (por mais simples que seja), para que exista uma referência sobre as motivações e decisões tomadas para a sua criação.

Também vale notar que apesar de um Design Doc ter a possibilidade de ser composto de diversos tópicos e detalhes, a criação de uma versão simplificada do documento para soluções mais simples é igualmente útil.

Conclusão

Ter visibilidade e detalhes sobre o desenvolvimento de soluções é indiscutível necessário, especialmente para empresas que contam com muitos desenvolvedores.

O Design Doc permite que equipes alinhem suas ideias e estratégias, facilitando a comunicação e colaboração na criação de softwares de qualidade. Além disso, atua como uma fonte de referência crucial para a implementação, monitoramento e manutenção futuros do projeto.

Apesar de parecer algo burocrático, dedicar tempo e esforço para elaborar um Design Doc detalhado e cuidadoso é um investimento que traz retornos significativos para a qualidade e eficiência das soluções produzidas.

Referências

• Design Docs at Google: https://www.industrialempathy.com/posts/design-docs-at-google/
• DesignDocs.dev: https://www.designdocs.dev/