Olá, turma. Vamos começar nossa aula sobre Documentação Arquitetônica e Comunicação Técnica. Este é um tema muito importante para o desenvolvimento de nossa carreira como pessoa arquiteta de soluções.
Antes de começarmos a falar exatamente sobre o curso, vou fazer minha autodescrição.
Audiodescrição: Sou um homem branco de 49 anos, com cabelo curto castanho-escuro, barba curta, olhos claros, usando óculos e vestindo uma camisa preta básica, sem detalhes.
Agora, vamos falar um pouco sobre esta disciplina específica, que é Documentação Arquitetônica e Comunicação Técnica.
Neste curso, nós vamos compreender como a arquitetura e a documentação de arquitetura são ferramentas essenciais para comunicar o que estamos fazendo, o que as pessoas arquitetas estão desenvolvendo e as soluções propostas.
Nós também vamos discutir os diferentes públicos com os quais precisamos nos comunicar em empresas de grande porte: equipe de negócios, pessoas desenvolvedoras, CIOs (diretores de TI) e executivos de nível C.
Nós vamos diferenciar a documentação útil daquela que é inútil — a que geramos e não utilizamos ou que apenas gera trabalho sem valor.
Nós vamos abordar a governança, como a documentação de arquitetura nos orienta nessa governança e quais são os erros mais comuns que, ocasionalmente, cometemos na documentação de arquitetura.
Vamos prosseguir; em seguida, detalharemos cada um desses tópicos.
Abraço!
Olá, equipe. Vamos começar falando sobre documentação arquitetônica e trazer uma pergunta: por onde devemos começar?
Vamos levar o tema para a construção civil. Se queremos construir uma casa, eventualmente compramos um terreno e queremos construir, ou compramos uma casa antiga e queremos modernizá-la, por onde começamos? Iniciamos pelo projeto da casa ou começamos a obra diretamente? Sabemos que, no Brasil, costumamos iniciar a obra antes do projeto, mas por onde deveríamos começar? Se respondemos que devemos iniciar pelo projeto, acertamos. De fato, devemos começar pelo projeto.
O projeto reúne uma série de informações que nos guiam durante a obra. No projeto, descrevemos qual é o tamanho do terreno; se a pessoa cliente, ou nós, deseja uma casa com quantos dormitórios; se queremos uma área gourmet; se queremos piscina; e se há área suficiente no terreno para construir tudo o que desejamos. Às vezes compramos um terreno pequeno e queremos construir uma mansão, mas não cabe naquele espaço. Então, cogitamos construir um edifício, porém isso aumenta o custo. É isso que queremos? É isso que temos?
O mesmo se aplica a uma solução e a software (programa/sistema). Abrimos aqui um parêntese sobre software (programa/sistema): é um conceito amplamente conhecido; trata-se de um sistema. E temos uma solução quando há mais de um sistema entregando uma resposta ao negócio. Por exemplo, se temos um CRM (Gestão de Relacionamento com a Pessoa Cliente) onde realizamos a venda, um sistema de pagamentos, um sistema de faturamento e um sistema de cobranças, quando tudo isso se integra, estamos em um ecossistema; temos uma solução.
Para a solução, precisamos, em um projeto, da planta baixa. O que significa planta baixa? Quem contrata o arquiteto ou a pessoa engenheira para construir a casa quer visualizar como ela ficará: se haverá um jardim na frente; se a garagem comporta dois ou três carros; qual será o tamanho da frente e do fundo da casa; se a piscina ficará ao centro; se a casa ficará no centro do terreno ou encostada em um dos lados. Precisamos dessas informações para aprovar ou não aprovar, já que vamos investir dinheiro na construção da casa.
Temos o projeto elétrico, o projeto hidráulico, o projeto de concreto. Reunimos várias informações para entendermos: “Certo, é isso que queremos construir; por isso vamos fazer assim.” Se o terreno é pequeno, talvez não vamos posicionar a casa no centro do lote. Mas por que não? Porque queremos um corredor lateral para que o carro possa chegar até a parte de trás. Então, tomamos essa decisão.
O mesmo ocorre em nossa arquitetura de solução: precisamos escrever o que é necessário. Vamos imaginar que contratamos uma pessoa engenheira para construir a casa e ela diz: “Tudo bem, vamos entregar a casa, custará 200 mil reais.” Perguntamos: “Mas como será a casa?” E recebemos: “Não se preocupem, vocês vão gostar. Será funcional.” Sem as informações de que precisamos, certamente não pagaríamos sem saber previamente o que será entregue. Em arquitetura, é a mesma lógica.
Temos um terreno; temos uma casa antiga e queremos chegar à casa modernizada ou a uma casa nova. Esse conceito é o que aplicamos com o as-is (estado atual) e o to-be (estado futuro desejado). O as-is é o estado em que estamos hoje: como nossa solução funciona e atende ao negócio; é o que temos. O to-be é para onde queremos ir; qual é o objetivo. Temos um terreno vazio, mas queremos nossa casa bonita. O to-be é a documentação que descreve: “Minha casa ficará assim.” Depois de construir, pegamos a documentação e verificamos: foi dito que a garagem comportaria dois carros e não comporta; então, há algo errado. O que foi feito de forma incorreta? O cálculo? A dimensão? O que aconteceu? Nosso to-be serve para mostrar como será o resultado.
A documentação arquitetônica tem a mesma importância, na arquitetura de solução, que a documentação e os projetos têm na engenharia e na construção civil. Caso pensemos em não documentar — e às vezes surge a ideia de “não precisamos de documentação, está tudo aqui” —, vale refletir: se tudo estiver apenas na cabeça da pessoa engenheira ou da pessoa construtora, como o dono da casa, em uma futura revenda, se sentirá ao precisar perfurar uma parede sem saber por onde passam os canos ou a fiação? Da mesma forma, precisamos oferecer às pessoas clientes a mesma confiança que recebemos na construção civil.
Vamos adiante. O que não é documentação arquitetônica? Temos código, comentários no código, manuais, temos o Figma (ferramenta de design), diversas fontes de informação, mas que não são necessariamente documentação arquitetônica. A implementação e o uso estão explicados no código e em outros artefatos. A documentação arquitetônica entrega o contexto, a estrutura e as decisões que nos levaram por determinado caminho. No exemplo da casa, a documentação registra: qual foi o requisito? Era necessária uma casa com três dormitórios, por isso foi desenhada assim; era preciso um escritório, por isso o escritório foi incluído. A documentação arquitetônica não é “o que foi feito”, e sim “por que foi feito dessa forma”.
Agora, o que é e o que ela aporta? Pensemos na chegada a um projeto em que quem o desenvolveu não está mais presente. A solução funciona, mas com uma série de problemas: lentidão, indisponibilidade, perda de documentos, falta de comunicação entre sistemas. Quem desenvolveu não está mais lá; não há documentação em lugar algum; procuramos nos “drives (unidades de armazenamento)” e em todos os locais; não encontramos documentação; não conseguimos falar com ninguém daquela época. Concordamos que será um trabalho hercúleo entender por que funciona daquela maneira, por que recebe um arquivo e o coloca em outro diretório, qual era o contexto no momento da elaboração, que propósito tinha a solução, por que foi feita assim, se não temos nada registrado?
A documentação arquitetônica fornece a quem chega ao projeto esse contexto. Talvez as pessoas que participaram não estejam mais presentes, mas a documentação registra qual era o problema, o que a solução buscava resolver, por que determinada direção foi tomada. Pode ter havido um requisito de comunicação, uma exigência regulatória ou uma restrição de capacidade de processamento — no passado era uma, hoje é outra. Todas essas informações devem estar na documentação arquitetônica.
Ela mostrará quais são os componentes, como são utilizados, que softwares compõem a solução. Se eventualmente precisamos processar um sistema de faturamento e um sistema contábil, e ainda informar outra área, a documentação arquitetônica traz essas informações. Se houve um “trade-off (compensação)” com duas ou três opções de solução e adotamos uma delas — e não as outras — pelas razões A, B, C, D etc., explicamos na documentação por que não seguimos os demais caminhos. Assim, mantemos a explicação e a visão de todo o ecossistema, não apenas de um único software.
A documentação arquitetônica é o que entrega ao negócio, ao desenvolvimento e às pessoas “stakeholders (partes interessadas)” a visão de todo esse contexto de decisões, componentes e justificativas do porquê se fez assim.
Uma boa documentação é fundamental. Quando chegamos e não há documentação, enfrentamos problemas. Já desenvolvemos sem documentação e, ao revisarmos quase um ano depois, não lembrávamos por que fizemos daquela forma, por que usamos determinada rotina, por que aplicamos certa condição. Sem registrar, nem nós conseguimos resgatar os motivos.
A documentação de arquitetura reduz o esforço de transferência de conhecimento e a curva de aprendizado de quem chega para contribuir com a solução e com o contexto. A pessoa aprende mais rápido porque existe documentação. Com isso, economizamos tempo: se, sem documentação, levaríamos dois ou três meses para entender todo o contexto e ganhar segurança, com a documentação de arquitetura resolvemos em menos tempo. Também mantemos o histórico: os porquês das mudanças, por que algo foi resolvido de certa forma, qual foi o problema, e toda a complexidade do negócio — tudo isso deve estar presente na documentação.
Lembramos de uma experiência em que estávamos trabalhando em uma seguradora sem documentação de arquitetura. Atuávamos para uma área que não tinha documentação nem diagramas. Começamos a preparar a documentação e havia televisores no andar nos quais eram projetadas métricas — os KPIs (indicadores-chave de desempenho) da área, como o volume de contratações. Solicitamos ao time projetar ali também uma visão com um diagrama da solução, mostrando como os componentes se comunicam. Projetamos.
Em uma manhã de trabalho, a pessoa superintendente chegou, nos cumprimentou, olhou para a televisão, viu o diagrama e perguntou: “O que é isso?” Explicamos: “Estes são os componentes e como se relacionam para atender a esta área.” A pessoa respondeu: “Agora faz sentido. Entendo por que, quando pedimos algo, é tão complicado: há muitas caixas.” Respondemos: “Exato. Nosso propósito é reduzir essa complexidade.” A documentação trouxe a visão da complexidade que enfrentávamos naquela área. Às vezes, para a liderança, não fazia sentido por que uma entrega demorava tanto; ao visualizar a complexidade, veio o reconhecimento: “Agora entendemos; realmente é complexo.” A documentação de arquitetura traz esse tipo de benefício.
Para que serve essa documentação? O código nos dirá como algo foi implementado. Hoje existem agentes que leem o código, fazem engenharia reversa, identificam tabelas e extraem regras de negócio presentes ali. Isso é válido. Porém, mesmo a engenharia reversa e o uso de IA não informam por que se fez daquela maneira. Esse conhecimento está com quem desenvolveu. Se não for escrito, não há como saber o motivo das decisões. Quando conseguimos entender como algo foi feito e por que foi feito, podemos decidir seguir pelo caminho A ou B com muito mais segurança, pois consideramos todas as frentes.
Surge a dúvida: até quando devemos documentar? Mais documentação é melhor? Não. Esse é um erro comum — nós também já erramos bastante. Escrever mais não significa documentar melhor. Gera-se muita informação e a leitura se perde. É muito trabalho para pouco aproveitamento, e às vezes vira apenas burocracia. Existem manuais com mil páginas que ninguém lê. Dá trabalho produzir, mas ninguém consome. A documentação de arquitetura não pode ser assim.
Ela também não deve ficar desatualizada. O pior cenário em arquitetura é consultar uma documentação que não condiz com o ambiente de produção. Isso a torna inútil. Tomar uma decisão estratégica com base nessa documentação e descobrir que, em produção, aquilo não é verdade significa que a documentação não serviu, gerou mais ruído do que comunicação — o que é perigoso. Documentação pode ser insuficiente ou excessiva; ambos os extremos não funcionam.
O que funciona? O que é uma boa documentação? Primeiro, uma boa documentação é a que comunica. Não importa se foi feita em um papel simples — veremos ferramentas que auxiliam a documentar, mas o essencial é comunicar. Documentação eficiente explica por que algo foi feito, o que está sendo feito, os componentes principais e o que vimos anteriormente. Ela deve responder aos porquês, ser atualizada regularmente e alinhar as pessoas. É muito útil quando, em uma reunião, há informações contraditórias. Dizemos: “Esperem, vamos mostrar um diagrama ou uma documentação de arquitetura com um ADR (Registro de Decisão de Arquitetura) ou uma diretriz.” Em 5 ou 10 minutos, alinhamos todas as pessoas, conectamos os pontos e seguimos na mesma direção.
A documentação também deve ser proporcional à complexidade do sistema. Em nossa casa, se a construção é simples, a documentação é pequena; mas, se falamos de uma mansão com 16 quartos e 21 suítes, imaginamos o tamanho do plano. O mesmo vale para o nosso ecossistema: se é um software (software) ou uma solução com dois ou três sistemas, a documentação será mais enxuta; se envolve 20 componentes, será mais complexa e precisará trazer mais informações.
O que documentar?
O que não documentar?
Para concluir, uma boa documentação transforma complexidade em clareza compartilhada. Quem documenta compartilha entendimento; quem não documenta cria dependência. Lembramos de um professor, filósofo; na época, éramos estudantes de Marketing (mercadologia). Ele dizia que a empresa sem área de Marketing (mercadologia) é como alguém no escuro acenando para outra pessoa: só ela sabe que é uma boa empresa, porque não vende, não comunica. Essa ideia se aplica à arquitetura: a pessoa arquiteta que não documenta pode ter uma solução excelente, perfeita, mas só ela sabe — porque não documentou. Ninguém mais conhece o conjunto de regras, situações e decisões tomadas.
Vamos documentar. Uma boa arquitetura existe para ser compreendida e não apenas construída; ela deve ser comunicada. Quando toda a equipe conhece a documentação e a solução, atingimos o objetivo.
Encerramos esta primeira aula e, em breve, falaremos de outras. Um grande abraço!
Vamos continuar discutindo nossa documentação arquitetônica e a comunicação técnica. Pensamos o seguinte: vamos trazer um exemplo. Já falamos sobre documentação, sobre sua importância, sobre o que é e o que não é. Agora queremos mostrar este exemplo: Backstage.
Backstage é uma ferramenta desenvolvida pela Spotify. Vocês podem acessar o link no material, ou, se buscarem no Google, encontrarão facilmente esse endereço. Esta é uma documentação de referência. Não é isso que desenvolvemos no dia a dia. Pode ser que, no projeto em que estivermos, na indústria ou especificamente na empresa, exista a necessidade de gerar uma documentação tão completa quanto esta. Esta documentação é de altíssima qualidade, mas, na prática, a experiência que vemos é que nem todas as empresas precisam de um nível de refinamento de documentação como este. Portanto, tratemos isto como referência para começarmos a nos familiarizar com documentação arquitetônica. Para quem nunca teve experiência com soluções ou documentação arquitetônica, este material ajuda a entender qual é o caminho que precisamos percorrer.
No início, a página apresenta uma barra à esquerda com itens em Markdown (linguagem de marcação leve) e, à direita, uma área maior onde é exibido o conteúdo dos menus da barra esquerda. Antes de a equipe começar a apresentar o design ou os componentes, ou se houver APIs (interfaces de programação de aplicações) — isto é interessante — primeiro apresenta o que é o Backstage. Antes de explicar como fez, explica o que fez.
O que é o Backstage? Um framework (estrutura) de código aberto para a criação de portais de pessoas desenvolvedoras, impulsionado por um catálogo de software centralizado. Em seguida, explica-se o que é o Backstage, ressaltando que começou como uma necessidade interna da equipe do Spotify, ganhou força, foi se estruturando até se tornar um componente aberto. Hoje, qualquer equipe pode fazer uso desse framework. Primeiro, portanto, apresenta-se o que é o Backstage e, depois, o que está incluído no Backstage: canal, catálogo de software, modelo de software e os Tech Docs (documentação técnica), com documentação para criar e facilitar o trabalho, entre outros itens.
Não vamos detalhar nem explicar o que é o Backstage; o foco é entendermos a documentação. Assim, a documentação mostra o que é a ferramenta e, em seguida, apresenta os benefícios. Ou seja, temos o Backstage. Talvez nos perguntemos: para que serve? Qual é o benefício? Aqui está um exemplo de benefício: para pessoas gerentes de engenharia, o Backstage permite manter melhores práticas em toda a organização.
É interessante conectarmos este conteúdo com a aula anterior para entender o seguinte: ao publicarmos a documentação, ela precisa fazer sentido para quem a ler.
Vamos realizar um exercício: consideremos que nunca ouvimos falar do Backstage e que talvez não estejamos acostumados com documentação. Vamos navegar e tentar entender que informações precisaríamos ver e se elas estão disponíveis aqui. Talvez não seja sobre benefícios, mas sobre termos uma visão técnica.
Há uma seção sobre a visão técnica. De início, entendemos que há um componente central do Backstage, o catálogo de software, que já apareceu três ou quatro vezes. Esse componente central utiliza uma arquitetura de plugins (extensões).
Mais uma vez, o propósito aqui não é explicar a ferramenta nem fornecer recomendações. Apresentamos o Backstage como um caso de documentação, destacando benefícios e principais características.
Podemos observar o que se destaca, considerando a complexidade desta solução: autenticação, identidade, Kubernetes, notificações, permissões, busca, catálogo, modelo de software e TechDocs. Também há uma visão geral da arquitetura, com um modelo proposto.
Isso já apresenta o modelo do sistema do catálogo de software e traz uma representação em diagrama com três caixas, indicando que há um componente que conversa com um recurso; há uma API; e esses elementos se comunicam. O diagrama tem três caixas e explica com o que cada uma se relaciona.
Percebemos como isso já fornece informações para que, em pouco tempo, não partamos do zero? A compreensão sobre o que é o Backstage já se torna mais robusta. Esse é o propósito da documentação.
A documentação também apresenta uma modelagem do ecossistema, trazendo mais informações. Talvez já estivéssemos familiarizados com essas três caixas e, agora, foram apresentados o recurso, o componente e a API.
Observamos, ainda, mais elementos ao redor. Vamos ver a visão geral da arquitetura: aparecem o front-end (camada de apresentação) e o back-end (camada de serviços), e como se comunicam. A proposta é utilizarmos este documento, esta documentação, como referência.
Se estivermos trabalhando em um projeto, iniciando a iniciativa e a empresa não tiver maturidade em documentação, por onde começamos? Começamos seguindo este modelo: explicar qual é a solução; criar um diagrama macro de como os componentes se relacionam; e, depois, apresentar uma visão técnica indicando as tecnologias utilizadas — por exemplo, Java/.NET; se a base de dados é SQL, como Oracle; se é SQL ou NoSQL, e qual é. Isso oferece uma visão e já trará muitas informações para quem vier depois de nós.
Portanto, vamos praticar: vamos consultar este link (hiperlink) do Backstage, buscar elementos que não estão visíveis aqui e que gostaríamos de saber e, então, avaliar: esta documentação está muito boa.
Até a próxima aula. Muito obrigado.
O curso Documentação Arquitetural e Comunicação Técnica possui 163 minutos de vídeos, em um total de 41 atividades. Gostou? Conheça nossos outros cursos de Arquitetura em DevOps, ou leia nossos artigos de DevOps.
Matricule-se e comece a estudar com a gente hoje! Conheça outros tópicos abordados durante o curso:
O Plano Plus evoluiu: agora com Luri para impulsionar sua carreira com os melhores cursos e acesso à maior comunidade tech.
2 anos de Alura
Matricule-se no plano PLUS 24 e garanta:
Jornada de estudos progressiva que te guia desde os fundamentos até a atuação prática. Você acompanha sua evolução, entende os próximos passos e se aprofunda nos conteúdos com quem é referência no mercado.
Programação, Data Science, Front-end, DevOps, Mobile, Inovação & Gestão, UX & Design, Inteligência Artificial
Formações com mais de 1500 cursos atualizados e novos lançamentos semanais, em Programação, Inteligência Artificial, Front-end, UX & Design, Data Science, Mobile, DevOps e Inovação & Gestão.
A cada curso ou formação concluído, um novo certificado para turbinar seu currículo e LinkedIn.
Acesso à inteligência artificial da Alura.
No Discord, você participa de eventos exclusivos, pode tirar dúvidas em estudos colaborativos e ainda conta com mentorias em grupo com especialistas de diversas áreas.
Faça parte da maior comunidade Dev do país e crie conexões com mais de 120 mil pessoas no Discord.
Acesso ilimitado ao catálogo de Imersões da Alura para praticar conhecimentos em diferentes áreas.
Explore um universo de possibilidades na palma da sua mão. Baixe as aulas para assistir offline, onde e quando quiser.
Luri Vision chegou no Plano Pro: a IA da Alura que enxerga suas dúvidas, acelera seu aprendizado e conta também com o Alura Língua que prepara você para competir no mercado internacional.
2 anos de Alura
Todos os benefícios do PLUS 24 e mais vantagens exclusivas:
Chat, busca, exercícios abertos, revisão de aula, geração de legenda para certificado.
Envie imagens para a Luri e ela te ajuda a solucionar problemas, identificar erros, esclarecer gráficos, analisar design e muito mais.
Aprenda um novo idioma e expanda seus horizontes profissionais. Cursos de Inglês, Espanhol e Inglês para Devs, 100% focado em tecnologia.
Escolha os ebooks da Casa do Código, a editora da Alura, que apoiarão a sua jornada de aprendizado para sempre.
Para quem quer atingir seus objetivos mais rápido: Luri Vision ilimitado, vagas de emprego exclusivas e mentorias para acelerar cada etapa da jornada.
2 anos de Alura
Todos os benefícios do PRO 24 e mais vantagens exclusivas:
Catálogo de tecnologia para quem é da área de Marketing
Envie imagens para a Luri e ela te ajuda a solucionar problemas, identificar erros, esclarecer gráficos, analisar design e muito mais de forma ilimitada.
Escolha os ebooks da Casa do Código, a editora da Alura, que apoiarão a sua jornada de aprendizado para sempre.
Conecte-se ao mercado com mentoria individual personalizada, vagas exclusivas e networking estratégico que impulsionam sua carreira tech para o próximo nível.
