Como determinar o volume de documentação arquitetural para um software?

Elemar Júnior

A quantidade adequada de documentação arquitetural para um software depende de análises de risco e de custo.

Entendemos que boa documentação arquitetural reduz os custos totais de um software. Ou seja, é mais barato adicionar features ou fazer ajustes quando há boa documentação arquitetural disponível. De forma análoga, entendemos que, com boa documentação, os riscos envolvidos são menores ou mitigados.

A diferença entre as somas dos custos de criação e manutenção de um software com e sem documentação, deve superar os custos de elaboração e manutenção dessa documentação. Exceto, quando ela for fundamental para mitigar riscos. Em termos simples, toda documentação arquitetural que aumente os custos, sem ao menos mitigar riscos que o negócio reconhece, não se justifica e não deveria ser produzida ou mantida.

Não é incomum encontrarmos software, principalmente em empresas menores, sem qualquer tipo de documentação. Muitas vezes, as “dores” que geram a necessidade de consultoria são provenientes da falta de alinhamento do time sob aspectos básicos da arquitetura. Quase sempre, os problemas “se resolvem sozinhos” assim que se inicia o esforço para gerar documentação básica – ainda em nível alto.

Veja também

Também não é incomum, principalmente em empresas grandes, encontrarmos documentação tão “abstrata” que não resolve dúvida alguma. Há tanta burocracia envolvida que toda informação relevante, quando há, fica escondida atrás de formatos e normas.

Embora muitos discordem, gerentes e patrocinadores de projetos são pessoas “racionais”. Por isso, dificilmente negariam investimentos em atividades que gerem benefícios percebidos. Cabe aos arquitetos a responsabilidade de demonstrar para o negócio a utilidade de produzir a documentação de qualidade.

É importante, antes da elaboração ou atualização de um documento, que seja estimado o esforço e, também, que sejam determinadas que atividades que vão ficar “mais baratas” em decorrência. Se isso não for possível, faremos melhor alocando recursos em outras frentes.

Se você não consegue enumerar benefícios percebíveis de uma “boa prática” é porque, provavelmente, não tem condições de produzir algum.

Em resumo

O problema
É difícil determinar o volume de documentação arquitetural adequado para um software.
O insight
A quantidade adequada de documentação arquitetural para um software depende de análises de risco e de custo. A diferença entre as somas dos custos de criação e manutenção de um software com e sem documentação, deve superar os custos de elaboração e manutenção dessa documentação. Exceto, quando ela for fundamental para mitigar riscos
Os benefícios
Assumir que a documentação de um software precisa “se pagar” pela redução dos custos totais em um software ajuda o time a manter o foco no que é importante.

Compartilhe este insight:

Comentários

Participe deixando seu comentário sobre este artigo a seguir:

Subscribe
Notify of
guest
1 Comentário
Oldest
Newest Most Voted
Inline Feedbacks
View all comments
Alessandro Brito
Alessandro Brito
2 anos atrás

Olá Elemar, tudo bem? Excelente ponto. Recentemente tenho estudado essa questão do papel do arquiteto e da arquitetura no contexto de times ágeis. Talvez por excessos do passado, a prática de design do sistema tenha sido rotulado de burocracia. Mas ao meu ver, um mínimo de planejamento e arquitetura é necessária para se evitar problemas futuros. Isso não significa que a documentação é mais importante que o software funcionando. Em times grandes com relativo turnover a ausência de uma documentação mínima pode levar ao caos.

AUTOR

Elemar Júnior
Fundador e CEO da EximiaCo atua como tech trusted advisor ajudando empresas e profissionais a gerar mais resultados através da tecnologia.

NOVOS HORIZONTES PARA O SEU NEGÓCIO

Nosso time está preparado para superar junto com você grandes desafios tecnológicos.

Entre em contato e vamos juntos utilizar a tecnologia do jeito certo para gerar mais resultados.

Insights EximiaCo

Confira os conteúdos de negócios e tecnologia desenvolvidos pelos nossos consultores:

Arquitetura de Dados

Insights de um DBA na análise de um plano de execução

Especialista em performance de Bancos de Dados de larga escala
Arquitetura de Software

Estratégias para modernização do legado

Desenvolvedor .NET/NodeJs e especialista em Kafka com experiência em startups e grandes empresas
Infraestrutura e Nuvem

Migração para a nuvem, mais do que mudança tecnológica, implica em mudança da cultura organizacional

Engenheiro de nuvem, arquiteto de software e especialista em Containers e Devops

Acesse nossos canais

Simplificamos, potencializamos e aceleramos resultados usando a tecnologia do jeito certo

EximiaCo 2022 – Todos os direitos reservados

1
0
Queremos saber a sua opinião, deixe seu comentáriox
()
x

Como determinar o volume de documentação arquitetural para um software?

Para se candidatar nesta turma aberta, preencha o formulário a seguir:

Condição especial de pré-venda: R$ 14.000,00 - contratando a mentoria até até 31/01/2023 e R$ 15.000,00 - contratando a mentoria a partir de 01/02/2023, em até 12x com taxas.

Tenho interesse nessa capacitação

Para solicitar mais informações sobre essa capacitação para a sua empresa, preencha o formulário a seguir:

Tenho interesse em conversar

Se você está querendo gerar resultados através da tecnologia, preencha este formulário que um de nossos consultores entrará em contato com você:

O seu insight foi excluído com sucesso!

O seu insight foi excluído e não está mais disponível.

O seu insight foi salvo com sucesso!

Ele está na fila de espera, aguardando ser revisado para ter sua publicação programada.

Tenho interesse em conversar

Se você está querendo gerar resultados através da tecnologia, preencha este formulário que um de nossos consultores entrará em contato com você:

Tenho interesse nessa solução

Se você está procurando este tipo de solução para o seu negócio, preencha este formulário que um de nossos consultores entrará em contato com você:

Tenho interesse neste serviço

Se você está procurando este tipo de solução para o seu negócio, preencha este formulário que um de nossos consultores entrará em contato com você:

× Precisa de ajuda?