Este capítulo possui uma versão mais recente:

Não há nada tão inútil quanto fazer eficientemente o que não deveria ser feito.
Peter Drucker
Muitos times qualificados e profissionais experientes são resistentes a ideia de documentar arquitetura de software. A raiz dessa resistência costuma estar em um passado cheio de burocracia exagerada e processos up-front para design. Há também quem faça associação de documentação com “arquitetos de torre de marfim”, que consomem tempo e outros recursos preciosos de projetos elaborando diagramas que ninguém consulta ou mesmo se importa. Entretanto, negar a utilidade de boa documentação arquitetural pode ser um problema grande, principalmente em projetos mais complexos.
0
Você concorda com essa afirmação? Há algo a ponderar aqui?x

Se  o propósito das práticas de arquitetura de software é aumentar as chances de que os objetivos do negócio sejam atingidos – respeitando restrições e atributos de qualidade – é importante disseminar esses parâmetros, com o mínimo de ambiguidade e subjetividade, durante todo o ciclo de vida do software que, aliás, pode durar décadas começando muito antes da primeira linha de código ser escrita.

Seja por motivos nobres, como aumentar o alinhamento de propósito que autoriza autonomia de atuação, ou tristes, como gerar evidências de trabalho ou de acordos passados, documentação arquitetural exerce papel importante e é útil desde que feita na medida certa.
0
Você concorda com essa afirmação? Há algo a ponderar aqui?x

Documentação arquitetural em processos ágeis

Estamos descobrindo maneiras melhores de desenvolver software, fazendo-o nós mesmos e ajudando outros a fazerem o mesmo. Através deste trabalho, passamos a valorizar: 1) Indivíduos e interações mais que processos e ferramentas; 2) Software em funcionamento mais que documentação abrangente; 3) Colaboração com o cliente mais que negociação de contratos e 4) Responder a mudanças mais que seguir um plano. (Manifesto ágil)

Os processos ágeis de desenvolvimento de software são uma reação a métodos pesados que eram comuns no passado (com resquícios fortes dentro de muitas empresas ainda hoje, infelizmente).

Por causa de um rigor difícil de justificar hoje em dia, era comum que se consumisse semanas elaborando documentações detalhadas, não apenas em nível arquitetural mas bem “perto do código”, para um esforço de implementação que iria durar apenas dias. A justificativa era uma pretensa garantia de qualidade que nunca se confirmava na prática.
0
Qual sua experiência nessa época?x
Felizmente, essa já não é mais a realidade, embora, talvez, hoje pequemos pelo contrário.

Na ânsia de eliminar etapas desnecessárias para o desenvolvimento de sistemas de software, muitos “agilistas” resistem não apenas a documentação arquitetural mas a tudo que esteja relacionado com técnicas para a prática da arquitetura. Importante, entretanto, destacar que essa posição não é universal. Muitos expoentes das práticas ágeis – incluindo Martin Fowler, Robert Martin, Scott Ambler – reconhecem que essa conduta é perigosa.

Os métodos ágeis não se opõem à documentação, apenas à documentação sem valor. Documentos que auxiliam a própria equipe podem ter valor, mas somente se forem mantidos atualizados. Documentos grandes nunca são atualizados. Documentos pequenos e modulares têm pelo menos uma chance de serem atualizados. (Nygard)

Atividades de refatoração para corrigir escolhas ruins de arquitetura são, muitas vezes, caras demais para serem colocadas em prática. Por isso, é importante que decisões razoáveis sejam adotadas cedo e, para que isso aconteça, são necessárias aplicação de algumas técnicas incluindo, acredito, elaboração e manutenção de boa documentação arquitetural. Resistir a práticas arquiteturais, inclusive documentação na medida certa, tem pouco haver com agilidade, mas com teimosia, falta de conhecimento profundo ou imaturidade.
1
Por favor, deixe seu feedback aquix

Documentação arquitetural e a comunicação

Comunicação é parte fundamental de qualquer atividade relacionada à engenharia de software. Quanto melhor (não necessariamente ampla) a comunicação, maiores as chances de que exista alinhamento de propósito e que autonomia de atuação seja possível. A documentação arquitetural é ferramenta para a comunicação em projetos de sistemas de software
0
Você concorda com essa afirmação? Há algo a ponderar aqui?x

Se a organização tem uma expectativa de que “todos devem ver todas as mensagens do chat” ou “todos precisam comparecer às massivas reuniões standup” ou “todos precisam estar presentes nas reuniões” para aprovar as decisões, então temos um problema de design da organização. A lei de Conway sugere que este tipo de comunicação muitos-para-muitos tende a produzir sistemas monolíticos, emaranhados, altamente acoplados e interdependentes que não suportam fluxo rápido. Mais comunicação não é necessariamente uma coisa boa. (Skelton e Pais)

Os componentes de um software, evidentes em sua arquitetura, interagem e são desenvolvidos por times que também precisam interagir. Ambos, componentes e times, precisam de interfaces qualificadas, sem revelar seus funcionamentos internos, para que comunicação eficiente aconteça.

Arquitetura de software é a divisão prudente de um todo em partes, com relações específicas entre essas partes. Esse particionamento é o que permite que grupos de pessoas – geralmente separados por limites organizacionais, geográficos e até mesmo de fusos horários – trabalhem em conjunto de forma cooperativa e produtiva para resolver um problema muito maior do que qualquer um deles resolve individualmente. (Clements et al.)

Documentação arquitetural bem-feita exerce papel importante na comunicação. Há quem defenda que o código, testes, scripts para automação de deploy e gráficos dinâmicos gerados por ferramentas APM são suficientes. Pessoalmente, não concordo com essa visão pois todos esses artefatos, embora fundamentais para a comunicação, revelam apenas o “como” e dificilmente o “porquê” das coisas.
0
Você concorda com essa afirmação? Há algo a ponderar aqui?x

Arquitetura de software é o conjunto de decisões de design que, se feitas incorretamente, talvez causem o cancelamento do seu projeto. (Rosanski e Woods)

Mesmo o melhor projeto de arquitetura de um software será inútil se as pessoas não forem capazes de entendê-lo direito, ao longo do tempo, para colocá-lo em prática ou, pior, entendê-lo errado implantando-o incorretamente. A documentação bem-feita da arquitetura registra e explica os “porquês” das decisões e deve facilitar o entendimento do projeto de software, reduzindo chances de  equívocos de entendimento.
0
Você concorda com essa afirmação? Há algo a ponderar aqui?x

Fazer negócios sem anunciar [ou projetar uma arquitetura sem documentá-la] é como piscar para uma garota no escuro. Você sabe o que está fazendo, mas ninguém mais sabe. (frase adaptada de Steaurt Henderson Britt em Skelton e Pais)

Documentação arquitetural fala sobre a arquitetura hoje, liberando o arquiteto para que ele seja mais produtivo, tirando dúvidas dos envolvidos e, principalmente, fala sobre a arquitetura “amanhã”, quando outras pessoas, fora do time original, forem responsáveis por manter o sistema. Documentação insuficiente ou ruim aumenta as chances de erosão arquitetural!
0
Você concorda com essa afirmação? Há algo a ponderar aqui?x

(Documentação da) arquitetura de software e a complexidade

Projetos de software têm se tornado maiores e mais complexos com o passar dos anos. Esse aumento da complexidade dos sistemas tem sido compensada, de alguma forma com o surgimento de IDEs inteligentes, compiladores sofisticados, linguagens de programação mais expressivas, frameworks e componentes prontos. A complexidade dos projetos de software também pode ser mitigada pela adoção de práticas eficientes de arquitetura de software.
0
Você concorda com essa afirmação? Há algo a ponderar aqui?x

Há pelo menos três contribuições notáveis da arquitetura de software para o combate da complexidade:

  1. Divisão do problema – estruturando software em componentes que possam ser mantidos por times pequenos e que, depois, podem ser combinados, formando um sistema maior, a arquitetura autoriza, pelo menos por um tempo, a desenvolver partes de um software sem conhecer detalhes sobre como as outras funcionam. A ênfase passa ser nas interações.
  2. Aproveitamento do conhecimento dos times – facilitando, a partir de componentes pequenos e desacoplados, o reaproveitamento do conhecimento dos desenvolvedores na implementação do projeto (ex: alguém que já implementou um mecanismo de cobrança, terá uma boa ideia de como implementar essa solução). Também crescem as chances de encontrar boas fontes de conhecimento em livros, palestras, descrição de padrões, projetos de código aberto e mais.
  3. Adoção de abstrações – facilitando, ao ignorar detalhes menos significativos, os esforços para desenvolver soluções.

Tanto os critérios utilizados na “divisão do problema” como as abstrações utilizadas para desenvolver soluções se perdem facilmente em detalhes de implementação e ficam melhor representados em boas documentações fora do código.
0
Você concorda com essa afirmação? Há algo a ponderar aqui?x

Em software, coisas maiores geralmente são feitas de coisas menores. Você sempre pode raciocinar sobre as coisas menores em um sistema (como linhas individuais de código), mas normalmente você achará mais eficiente pensar em coisas maiores (como clientes e servidores) [..] Você pode começar seu processo de raciocínio considerando o pequenos pedaços, como objetos e chamadas de procedimento, mas que seriam ineficientes e provavelmente o inundariam com detalhes. (Fairbanks)

Atividades suportadas pela documentação arquitetural

Falar que a documentação ajuda a melhorar a arquitetura facilita a comunicação é importante, mas um tanto abstrato. Dando “um passo à frente”, ficam evidentes três usos comuns para a documentação:

  1. Educação, seja para novos membros do time, analistas externos ou até mesmo um novo arquiteto.
  2. Alinhamento com stakeholders
  3. Base para a continuidade da construção e análise do software.

Em termos econômicos, a documentação da arquitetura é essencial porque ela reduz o custo total de propriedade do software. Aliás, a medida certa de quanto documentar é determinada pela a capacidade de “código+documentação” custar menos do que “apenas código”. Ou seja, precisa ser mais barato e menos arriscado adicionar features ou fazer ajustes quando há boa documentação arquitetural disponível. 
0
Você concorda com essa afirmação? Há algo a ponderar aqui?x

O esforço precisa ser compatível com o risco de falha no projeto. Cada projeto enfrenta diferentes riscos e não há uma única forma de fazer de arquitetura de software. É sempre necessário avaliar os riscos de cada projeto e aceitar que, eventualmente, a saída pode ser  sequer fazer esforço para elaboração da arquitetura pois há tantos projetos  similares anteriores bem-sucedidos que não haverá risco, desde que arquiteturas que deram certo sejam usadas como referência. (Fairbanks)


A utilidade de um documento arquitetural é aquele onde o custo para sua produção é menor do que as economias que este irá gerar em outras atividades, ou ainda, por sua contribuição para mitigação de riscos. Documento é útil se é consultado, em algum momento. Se um documento não for utilizado ativamente, valerá menos do que os bytes comprometidos com ele.
0
Você concorda com essa afirmação? Há algo a ponderar aqui?x

Em minha atuação como consultor é comum encontrar software, principalmente em empresas menores, sem qualquer tipo de documentação. Por outro lado, também não é incomum, principalmente em empresas maiores, encontrar documentação tão “abstrata” e desatualizada 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. 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, porém de qualidade.

O que (geralmente) precisa ser documentado

Se a documentação é boa quando o custo de sua elaboração é compensado pela redução de custos em outras atividades ou pela mitigação de riscos, então, sua manutenção precisa custar o mínimo possível. De forma objetiva, a documentação de arquitetura útil para os projetos demanda atualizações menos frequentes.

A documentação arquitetural deve registrar, primeiro, aspectos que vão permanecer verdadeiros por mais tempo. Sem dúvidas, se encaixam nessa característica algum detalhamento das restrições e dos atributos de qualidade.

A documentação arquitetural também precisa dar ênfase na estratégia – padrão coerente para tomada de decisões – que irá autorizar mudanças. Ou seja, que critérios devem ser observados para determinar a necessidade de adicionar, remover ou substituir a implementação dos componentes.

Finalmente, a documentação também deve expor a estrutura atual e suas propriedades. Entretanto, quanto maior for a fragmentação de componentes de um software, por exemplo, em arquiteturas baseadas em microsserviços – extremamente dinâmicos e auto organizados, com estratégias de descoberta sofisticadas – menor será o incentivo para documentar suas interações. Nesses casos, o uso de ferramentas que permitam a “captura” da arquitetura-do-momento automaticamente, como, por exemplo, soluções APM é essencial.

Considerações sobre “Architecture Haiku”

George Fairbanks propôs a ideia do Architecture Haiku – uma descrição de design super concisa de uma página, rápida de construir.

A provocação é colocar um overview da arquitetura em uma única folha de papel A4. Assim, com menos espaços para indecisões ou prolongamentos. Eventualmente, pode não haver espaço para diagramas – o que à primeira vista parece loucura, mas talvez seja muito brilhante!

Com tão pouco espaço, escolher as informações certas a serem incluídas é extremamente importante. Aqui está o que Fairbanks recomenda:

  • breve resumo da solução geral,
  • uma lista de restrições técnicas importantes,
  • resumo de alto nível dos principais requisitos funcionais,
  • lista priorizada de atributos de qualidade,
  • breve explicação das decisões de design, incluindo justificativa e compensações,
  • lista de estilos e padrões arquitetônicos usados,
  • apenas diagramas que adicionem significado além das informações já na página.
Um Haiku pode ser um bom começo para organizações sem prática consolidada de arquitetura.
1
Você concorda?x

Considerações sobre ADRs (Architecture Decision Records)

Uma decisão arquitetural trata sempre de uma escolha de design relacionada a uma característica funcional ou não-funcional  indiscutivelmente relevante, pois, geralmente, tem algumas das seguintes características:

  • afeta os objetivos do negócio ou atributos de qualidade (como performance, disponibilidade, segurança, manutenabilidade, etc.)
  • é difícil de ser desfeita (uma das quatro fontes da complexidade)
  • implica em gastos ou economias consideráveis de tempo ou dinheiro (protip: tempo geralmente é um proxy para dinheiro)
  • demandou, para sua formulação, considerável tempo e esforço do time, geralmente demandando provas de conceito e avaliação de trade-offs.
  • é extremamente complexa podendo não fazer sentido em primeira análise, sem o background necessário.

Decisões arquiteturais são realizadas durante todo o ciclo de vida de um software, com maior frequência em sua concepção e em pontos onde ocorrem mudanças sensíveis na escala ou escopo. Se não forem adequadamente documentadas, podem, no futuro, gerar comportamentos perigosos que coloquem em risco o sistema.
0
Por favor, deixe seu feedback aquix

Uma das coisas mais difíceis de rastrear durante a vida de um projeto é a motivação por trás de certas decisões. Uma nova pessoa que está entrando em um projeto pode ficar perplexa, perplexa, encantada ou enfurecida com alguma decisão passada. Sem compreender a lógica ou as consequências, essa pessoa tem apenas duas opções: aceitar cegamente a decisão ou mudá-la cegamente. (Nygard)


Uma prática que tem se tornado comum é documentar as decisões arquiteturais em registros (architectural decision records) em um arquivo de texto curto, mantidos no repositório do projeto, geralmente composto das seguintes seções:

  • Título, curto e expressivo
  • Contexto, descrevendo aspectos técnicos, políticos, sociais e específicos que impactam na decisão, preferencialmente em linguagem neutra.
  • Decisão, expressando, em linguagem ativa, que caminho deve ser seguido.
  • Status, visto que a decisão ainda pode ser uma proposta, estar implementada (aceita), ultrapassada (deprecated) ou revertida (superseded).
  • Consequências, descrevendo o contexto geral resultante da decisão. Devem ser observados aspectos positivos, negativos e neutros.

ADRs é prática recomendada pela Toughtworks em seu famoso radar.

Muita documentação pode ser substituída por códigos e testes altamente legíveis. Em um mundo de arquitetura evolutiva, no entanto, é importante registrar certas decisões de design para o benefício dos futuros membros da equipe, bem como para supervisão externa. Registros de decisão de arquitetura leve é uma técnica para capturar decisões arquitetônicas importantes junto com seu contexto e consequências. Recomendamos armazenar esses detalhes no controle de origem, em vez de um wiki ou site, pois assim eles podem fornecer um registro que permanece sincronizado com o próprio código. Para a maioria dos projetos, não vemos razão para você não querer usar essa técnica. (Toughtworks)

Grandes jornadas são mais fáceis com um mapa…

As decisões de design que se relacionam com a arquitetura garantem o atendimento dos objetivos do negócio, respeitando restrições e atingindo atributos de qualidade. Entretanto, para que essas decisões cumpram seu papel, precisam ser rememoradas e compartilhadas com quem se juntar ao time ao longo do tempo. Tudo bem começar um projeto sem um mapa, mas é sempre bom ter um registro do caminho que foi percorrido e dos motivos para cada decisão.
0
Você concorda com essa afirmação? Há algo a ponderar aqui?x

Documentação elaborada na medida certa, de acordo com as complexidades e riscos de um sistema, reduzem o custo total de propriedade, simplificando, acelerando e potencializando as tomadas de decisão.

Nos próximos capítulos, iremos introduzir, aos poucos, alguns documentos arquiteturais úteis para a maioria dos projetos.

// TODO

Antes de avançar para o próximo capítulo recomendo as seguintes atividades:

  • Relacione quais documentações arquiteturais você está habituado a utilizar.
  • Pondere sobre os “gaps” de informação que precisa enfrentar rotineiramente em seu trabalho. Que informações entende que precisaram estar documentadas?
  • Pondere sobre o quão fácil (ou difícil) é incluir alguém novo no seu time hoje. Como é feita a integração técnica?

Referências bibliográficas

CLEMENTS, Paul et alDocumenting Software Architectures: views and beyond. 2. ed. Boston, Ma: Addison Wesley, 2011. (The SEI Series in Software Engineering).

FARBANKS, George. Just Enough Software Architecture: risk-driven approach. Boulder, Co: Marshall & Brainerd, 2010. Terceira Impressão em 2012.

MUNROE, Randall. Future Self. Disponível em: https://xkcd.com/1421/. Acesso em: 15 abr. 2021.

NIGARD, Michael. Documenting Architectural Decisions. 2011. Disponível em: https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions.html. Acesso em: 17 abr. 2021.

ROSANSKI, Nick; WOODS, Eoin. Software Systems Architecture: working with stakeholders using viewpoints and perspectives. 2. ed. Boston, Ma: Addison Wesley, 2012.

SKELTON, Matthew; PAIS, Manuel. Team Topologies: organizing business and technology teams for fast flow. Portland, Or: It Revolution Press, 2019.

TOUGHTWORKS (org.). Lightweight Architecture Decision Records. 2018. Tech Radar. Disponível em: https://www.thoughtworks.com/pt/radar/techniques/lightweight-architecture-decision-records. Acesso em: 17 abr. 2021.

Compartilhe este capítulo:

Compartilhe:

Comentários

Participe da construção deste capítulo deixando seu comentário:

Inscrever-se
Notify of
guest
4 Comentários
Oldest
Newest Most Voted
Feedbacks interativos
Ver todos os comentários
Matheus Bortolon
Matheus Bortolon
3 anos atrás
Feedback no conteúdo deste capítulo Um Haiku pode ser um bom começo para organizações sem prática consolidada de arquitetura." Ler mais »

Desafio fazer isso tudo em uma folha A4 😱

Guilherme Elias
Guilherme Elias
3 anos atrás
Responder para  Matheus Bortolon

A3 talvez 😉

Fabricio Doi
Fabricio Doi
3 anos atrás
Feedback no conteúdo deste capítulo Atividades de refatoração para corrigir escolhas ruins de arquitetura são, muitas vezes, caras demais para serem colocadas em prática. Por…" Ler mais »

Talvez outro fator que atrapalhe na adoção de documentação é falta de uma ferramenta para que isso seja feito na empresa. Aqui onde trabalho, a quantidade de documentação gerada após a adoção do Confluence foi aumentada de forma significativa. Do ponto de vista arquitetural ainda é uma ferramenta que possui GAPs significativos, porém já traz a cultura de documentação para outros patamares.

Guilherme Elias
Guilherme Elias
3 anos atrás

Senti falta de dois tópico quando se fala em documentação de software que tem como objetivo agregar valor( manter-se viva):

=> Documentação Visual x Documentação Descritiva x Ambas(cada uma a seu tempo).
=> Teste de arquitetura (Mas isso não é documentação! Como diria Cortella. Será?)

Isso bem discutido e pensado pode se tornar uma convenção/sugestão para times que entendem a necessidade de documentar melhor suas decisões e evoluções(Building Evolutionary Architectures)!

Em resumo … deixar de lado a abstração de “talvez aqui isso, talvez ali aquilo” e sim sugerir abordagens como mencionado:

=> Mapas mentais;
=> C4 Model,
=> Haiku etc …

Obviamente depois de uma boa dose de curadoria 😉

Fundador e CEO da EximiaCo, atua como tech trusted advisor ajudando diversas empresas a gerar mais resultados através da tecnologia.

Mentoria

para arquitetos de software

Imersão, em grupo, supervisionada por Elemar Júnior, onde serão discutidos tópicos avançados de arquitetura de software, extraídos de cenários reais, com ênfase em systems design.

Consultoria e Assessoria em

Arquitetura de Software

EximiaCo oferece a alocação de um Arquiteto de Software em sua empresa para orientar seu time no uso das melhores práticas de arquitetura para projetar a evolução consistente de suas aplicações.

ElemarJúnior

Fundador e CEO da EximiaCo, atua como tech trusted advisor ajudando diversas empresas a gerar mais resultados através da tecnologia.

+55 51 99942-0609 |  contato@eximia.co

+55 51 99942-0609  contato@eximia.co

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