{"id":1293,"date":"2021-04-17T19:28:38","date_gmt":"2021-04-17T22:28:38","guid":{"rendered":"https:\/\/elemarjr.com\/arquiteturadesoftware\/?p=1293"},"modified":"2024-01-11T17:56:22","modified_gmt":"2024-01-11T20:56:22","slug":"capitulo-2-v1","status":"publish","type":"volume-1","link":"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/volume-1\/capitulo-2-v1\/","title":{"rendered":"Documentar \u00e9 preciso (?) … \/ Cap\u00edtulo 2 v1.0"},"content":{"rendered":"Muitos times qualificados e profissionais experientes s\u00e3o resistentes a ideia de documentar arquitetura de software.\u00a0<\/strong>A raiz dessa resist\u00eancia costuma estar em um passado cheio de burocracia exagerada e processos\u00a0up-front\u00a0<\/em>para design. H\u00e1 tamb\u00e9m quem fa\u00e7a associa\u00e7\u00e3o de documenta\u00e7\u00e3o com “arquitetos de torre de marfim”, que consomem tempo e outros recursos preciosos de projetos elaborando diagramas que ningu\u00e9m consulta ou mesmo se importa. Entretanto, negar a utilidade de boa documenta\u00e7\u00e3o arquitetural pode ser um problema grande, principalmente em projetos mais complexos.<\/strong>\n
\n

Se\u00a0 o prop\u00f3sito das pr\u00e1ticas de arquitetura de software \u00e9 aumentar as chances de que os objetivos do neg\u00f3cio sejam atingidos – respeitando restri\u00e7\u00f5es e atributos de qualidade – \u00e9 importante disseminar esses par\u00e2metros, com o m\u00ednimo de ambiguidade e subjetividade, durante todo o ciclo de vida do software que, ali\u00e1s, pode durar d\u00e9cadas come\u00e7ando muito antes da primeira linha de c\u00f3digo ser escrita.<\/p>\nSeja por motivos nobres, como aumentar o alinhamento de prop\u00f3sito que autoriza autonomia de atua\u00e7\u00e3o, ou tristes, como gerar evid\u00eancias de trabalho ou de acordos passados, documenta\u00e7\u00e3o arquitetural exerce papel importante e \u00e9 \u00fatil desde que feita na medida certa.<\/strong>\n

\n

Documenta\u00e7\u00e3o arquitetural em processos \u00e1geis<\/h2>\n

Estamos descobrindo maneiras melhores de desenvolver <\/em>software, fazendo-o n\u00f3s mesmos e ajudando outros a <\/em>fazerem o mesmo. Atrav\u00e9s deste trabalho, passamos a valorizar: 1) <\/em>Indiv\u00edduos e intera\u00e7\u00f5es mais que processos e ferramentas; 2) <\/em>Software em funcionamento mais que documenta\u00e7\u00e3o abrangente; 3) <\/em>Colabora\u00e7\u00e3o com o cliente mais que negocia\u00e7\u00e3o de contratos e 4) <\/em>Responder a mudan\u00e7as mais que seguir um plano. <\/em>(Manifesto \u00e1gil)<\/em><\/p>\n

Os processos \u00e1geis de desenvolvimento de software s\u00e3o uma rea\u00e7\u00e3o a m\u00e9todos pesados que eram comuns no passado (com resqu\u00edcios fortes dentro de muitas empresas ainda hoje, infelizmente).<\/p>\n

Por causa de um rigor dif\u00edcil de justificar hoje em dia, era comum que se consumisse semanas elaborando documenta\u00e7\u00f5es detalhadas, n\u00e3o apenas em n\u00edvel arquitetural mas bem “perto do c\u00f3digo”, para um esfor\u00e7o de implementa\u00e7\u00e3o que iria durar apenas dias. A justificativa era uma pretensa garantia de qualidade que nunca se confirmava na pr\u00e1tica. Felizmente, essa j\u00e1 n\u00e3o \u00e9 mais a realidade, embora, talvez, hoje pequemos pelo contr\u00e1rio.<\/p>\n

Na \u00e2nsia de eliminar etapas desnecess\u00e1rias para o desenvolvimento de sistemas de software, muitos “agilistas” resistem n\u00e3o apenas a documenta\u00e7\u00e3o arquitetural mas a tudo que esteja relacionado com t\u00e9cnicas para a pr\u00e1tica da arquitetura. Importante, entretanto, destacar que essa posi\u00e7\u00e3o n\u00e3o \u00e9 universal. Muitos expoentes das pr\u00e1ticas \u00e1geis – incluindo Martin Fowler, Robert Martin, Scott Ambler – reconhecem que essa conduta \u00e9 perigosa.<\/p>\n

Os m\u00e9todos \u00e1geis n\u00e3o se op\u00f5em \u00e0 documenta\u00e7\u00e3o, apenas \u00e0 documenta\u00e7\u00e3o sem valor. Documentos que auxiliam a pr\u00f3pria equipe podem ter valor, mas somente se forem mantidos atualizados. Documentos grandes nunca s\u00e3o atualizados. Documentos pequenos e modulares t\u00eam pelo menos uma chance de serem atualizados. (Nygard)<\/em><\/p>\nAtividades de refatora\u00e7\u00e3o para corrigir escolhas ruins de arquitetura s\u00e3o, muitas vezes, caras demais para serem colocadas em pr\u00e1tica.<\/strong> Por isso, \u00e9 importante que decis\u00f5es razo\u00e1veis sejam adotadas cedo e, para que isso aconte\u00e7a, s\u00e3o necess\u00e1rias aplica\u00e7\u00e3o de algumas t\u00e9cnicas incluindo, acredito, elabora\u00e7\u00e3o e manuten\u00e7\u00e3o de boa documenta\u00e7\u00e3o arquitetural. Resistir a pr\u00e1ticas arquiteturais, inclusive documenta\u00e7\u00e3o na medida certa, tem pouco haver com agilidade, mas com teimosia ou imaturidade.<\/strong>\n

\n

Documenta\u00e7\u00e3o arquitetural e a comunica\u00e7\u00e3o<\/h2>\nComunica\u00e7\u00e3o \u00e9 parte fundamental de qualquer atividade relacionada \u00e0 engenharia de software<\/b>. Quanto melhor (n\u00e3o necessariamente ampla) a comunica\u00e7\u00e3o, maiores as chances de que exista alinhamento de prop\u00f3sito e que autonomia de atua\u00e7\u00e3o seja poss\u00edvel. A documenta\u00e7\u00e3o arquitetural \u00e9 ferramenta para a comunica\u00e7\u00e3o em projetos de sistemas de software<\/span>\n
\n

Se a organiza\u00e7\u00e3o tem uma expectativa de que \u201ctodos devem ver todas as mensagens do chat\u201d ou \u201ctodos precisam comparecer \u00e0s massivas reuni\u00f5es standup\u201d ou \u201ctodos precisam estar presentes nas reuni\u00f5es\u201d para aprovar as decis\u00f5es, ent\u00e3o temos um problema de design da organiza\u00e7\u00e3o. A lei de Conway sugere que este tipo de comunica\u00e7\u00e3o muitos-para-muitos tende a produzir sistemas monol\u00edticos, emaranhados, altamente acoplados e interdependentes que n\u00e3o suportam fluxo r\u00e1pido. Mais comunica\u00e7\u00e3o n\u00e3o \u00e9 necessariamente uma coisa boa. <\/strong>(Skelton e Pais)<\/em><\/p>\n

Os componentes de um software, evidentes em sua arquitetura, interagem e s\u00e3o desenvolvidos por times que tamb\u00e9m precisam interagir.<\/strong> Ambos, componentes e times, precisam de interfaces qualificadas, sem revelar seus funcionamentos internos, para que comunica\u00e7\u00e3o eficiente aconte\u00e7a.<\/span><\/p>\n

Arquitetura de software \u00e9 a divis\u00e3o prudente de um todo em partes, com rela\u00e7\u00f5es espec\u00edficas entre essas partes. Esse particionamento \u00e9 o que permite que grupos de pessoas – geralmente separados por limites organizacionais, geogr\u00e1ficos e at\u00e9 mesmo de fusos hor\u00e1rios – trabalhem em conjunto de forma cooperativa e produtiva para resolver um problema muito maior do que qualquer um deles resolve individualmente. (Clements et al.)<\/span><\/i><\/p>\nDocumenta\u00e7\u00e3o arquitetural bem-feita exerce papel importante na comunica\u00e7\u00e3o. <\/b>H\u00e1 quem defenda que o c\u00f3digo, testes, <\/span>scripts <\/span><\/i>para automa\u00e7\u00e3o de <\/span>deploy e<\/span><\/i> gr\u00e1ficos din\u00e2micos gerados por ferramentas APM s\u00e3o suficientes. Pessoalmente, n\u00e3o concordo com essa vis\u00e3o pois todos esses artefatos, embora fundamentais para a comunica\u00e7\u00e3o, revelam apenas o “como” e dificilmente o “porqu\u00ea” das coisas.<\/span>\n

\n

Arquitetura de software \u00e9 o conjunto de decis\u00f5es de design que, se feitas incorretamente, talvez causem o cancelamento do seu projeto. (Rosanski e Woods)<\/span><\/i><\/p>\nMesmo o melhor projeto de arquitetura de um software ser\u00e1 in\u00fatil se as pessoas n\u00e3o forem capazes de entend\u00ea-lo direito, ao longo do tempo, para coloc\u00e1-lo em pr\u00e1tica ou, pior, entend\u00ea-lo errado implantando-o incorretamente.<\/strong> A documenta\u00e7\u00e3o bem-feita da arquitetura registra e explica os “porqu\u00eas” das decis\u00f5es e deve facilitar o entendimento do projeto de software, reduzindo chances de\u00a0 equ\u00edvocos de entendimento.\n

\n

Fazer neg\u00f3cios sem anunciar [ou projetar uma arquitetura sem document\u00e1-la] \u00e9 como piscar para uma garota no escuro. Voc\u00ea sabe o que est\u00e1 fazendo, mas ningu\u00e9m mais sabe. (frase adaptada de <\/span><\/i>Steaurt Henderson Britt<\/a> em Skelton e Pais<\/em>)<\/span><\/p>\nDocumenta\u00e7\u00e3o arquitetural fala sobre a arquitetura hoje, liberando o arquiteto para que ele seja mais produtivo, tirando d\u00favidas dos envolvidos e, principalmente, fala sobre a arquitetura “amanh\u00e3”, quando outras pessoas, fora do time original, forem respons\u00e1veis por manter o sistema. <\/span>Documenta\u00e7\u00e3o insuficiente ou ruim aumenta as chances de eros\u00e3o arquitetural!<\/b>\n

\n

(Documenta\u00e7\u00e3o da) arquitetura de software e a complexidade<\/span><\/h2>\nProjetos de software t\u00eam se tornado maiores e mais complexos com o passar dos anos.<\/strong> Esse aumento da complexidade dos sistemas tem sido compensada, de alguma forma com o surgimento de IDEs inteligentes, compiladores sofisticados, linguagens de programa\u00e7\u00e3o mais expressivas, <\/span>frameworks <\/span><\/i>e componentes prontos. A complexidade dos projetos de software tamb\u00e9m pode ser mitigada pela ado\u00e7\u00e3o de pr\u00e1ticas eficientes de arquitetura de software.<\/strong><\/span>\n
\n

H\u00e1 pelo menos tr\u00eas contribui\u00e7\u00f5es not\u00e1veis da arquitetura de software para o combate da complexidade:<\/span><\/p>\n

    \n
  1. Divis\u00e3o do problema <\/b>– 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 \u00eanfase passa ser nas intera\u00e7\u00f5es.<\/span><\/li>\n
  2. Aproveitamento do conhecimento dos times <\/b>– facilitando, a partir de componentes pequenos e desacoplados, o reaproveitamento do conhecimento dos desenvolvedores na implementa\u00e7\u00e3o do projeto (ex: algu\u00e9m que j\u00e1 implementou um mecanismo de cobran\u00e7a, ter\u00e1 uma boa ideia de como implementar essa solu\u00e7\u00e3o). Tamb\u00e9m crescem as chances de encontrar boas fontes de conhecimento em livros, palestras, descri\u00e7\u00e3o de padr\u00f5es, projetos de c\u00f3digo aberto e mais.<\/span><\/li>\n
  3. Ado\u00e7\u00e3o de abstra\u00e7\u00f5es <\/b>– facilitando, ao ignorar detalhes menos significativos, os esfor\u00e7os para desenvolver solu\u00e7\u00f5es.<\/span><\/b><\/li>\n<\/ol>\n
    \nTanto os crit\u00e9rios utilizados na “divis\u00e3o do problema” como as abstra\u00e7\u00f5es utilizadas para desenvolver solu\u00e7\u00f5es se perdem facilmente em detalhes de implementa\u00e7\u00e3o e ficam melhor representados em boas documenta\u00e7\u00f5es fora do c\u00f3digo.\n
    \n

    Em software, coisas maiores geralmente s\u00e3o feitas de coisas menores. Voc\u00ea sempre pode raciocinar sobre as coisas menores em um sistema (como linhas individuais de c\u00f3digo), mas normalmente voc\u00ea achar\u00e1 mais eficiente pensar em coisas maiores (como clientes e servidores) [..] Voc\u00ea pode come\u00e7ar seu processo de racioc\u00ednio considerando o pequenos peda\u00e7os, como objetos e chamadas de procedimento, mas que seriam ineficientes e provavelmente o inundariam com detalhes. (Fairbanks)<\/em><\/p>\n

    Atividades suportadas pela documenta\u00e7\u00e3o arquitetural<\/h2>\n

    Falar que a documenta\u00e7\u00e3o ajuda a melhorar a arquitetura facilita a comunica\u00e7\u00e3o \u00e9 importante, mas um tanto abstrato. Dando “um passo \u00e0 frente”, ficam evidentes tr\u00eas usos comuns para a documenta\u00e7\u00e3o:<\/span><\/p>\n

      \n
    1. Educa\u00e7\u00e3o, seja para novos membros do time, analistas externos ou at\u00e9 mesmo um novo arquiteto.<\/span><\/li>\n
    2. Alinhamento com <\/span>stakeholders<\/span><\/i><\/li>\n
    3. Base para a continuidade da constru\u00e7\u00e3o e an\u00e1lise do software.<\/span><\/li>\n<\/ol>\n
      \nEm termos econ\u00f4micos, a documenta\u00e7\u00e3o da arquitetura \u00e9 essencial porque ela reduz o custo total de propriedade do software. Ali\u00e1s, a medida certa de quanto documentar \u00e9 determinada pela a capacidade de “c\u00f3digo+documenta\u00e7\u00e3o” custar menos do que “apenas c\u00f3digo”. <\/span>Ou seja, precisa ser mais barato e menos arriscado adicionar features ou fazer ajustes quando h\u00e1 boa documenta\u00e7\u00e3o arquitetural dispon\u00edvel.<\/b>\u00a0<\/span>\n
      \n

      O esfor\u00e7o precisa ser compat\u00edvel com o risco de falha no projeto. Cada projeto enfrenta diferentes riscos e n\u00e3o h\u00e1 uma \u00fanica forma de fazer de arquitetura de software.<\/strong> \u00c9 sempre necess\u00e1rio avaliar os riscos de cada projeto e aceitar que, eventualmente, a sa\u00edda pode ser\u00a0 sequer fazer esfor\u00e7o para elabora\u00e7\u00e3o da arquitetura pois h\u00e1 tantos projetos\u00a0 similares anteriores bem-sucedidos que n\u00e3o haver\u00e1 risco, desde que arquiteturas que deram certo sejam usadas como refer\u00eancia. (Fairbanks)<\/em><\/p>\n

      \nA utilidade de um documento arquitetural \u00e9 aquele onde o custo para sua produ\u00e7\u00e3o \u00e9 menor do que as economias que este ir\u00e1 gerar em outras atividades, ou ainda, por sua contribui\u00e7\u00e3o para mitiga\u00e7\u00e3o de riscos. <\/b>Documento \u00e9 \u00fatil se \u00e9 consultado, em algum momento. Se um documento n\u00e3o for utilizado ativamente, valer\u00e1 menos do que os <\/span>bytes <\/span><\/i>comprometidos com ele.<\/span>\n
      \n

      <\/p>\n

      Em minha atua\u00e7\u00e3o como consultor \u00e9 comum encontrar software, principalmente em empresas menores, sem qualquer tipo de documenta\u00e7\u00e3o. Por outro lado, tamb\u00e9m n\u00e3o \u00e9 incomum, principalmente em empresas maiores, encontrar documenta\u00e7\u00e3o t\u00e3o \u201cabstrata\u201d e desatualizada que n\u00e3o resolve d\u00favida alguma. H\u00e1 tanta burocracia envolvida que toda informa\u00e7\u00e3o relevante, quando h\u00e1, fica escondida atr\u00e1s de formatos e normas. <\/span>Muitas vezes, as \u201cdores\u201d que geram a necessidade de consultoria s\u00e3o provenientes da falta de alinhamento do time sob aspectos b\u00e1sicos da arquitetura. Quase sempre, os problemas \u201cse resolvem sozinhos\u201d assim que se inicia o esfor\u00e7o para gerar documenta\u00e7\u00e3o b\u00e1sica, por\u00e9m de qualidade.<\/b><\/p>\n

      O que (geralmente) precisa ser documentado<\/span><\/h2>\n

      Se a documenta\u00e7\u00e3o \u00e9 boa quando o custo de sua elabora\u00e7\u00e3o \u00e9 compensado pela redu\u00e7\u00e3o de custos em outras atividades ou pela mitiga\u00e7\u00e3o de riscos, ent\u00e3o, sua manuten\u00e7\u00e3o precisa custar o m\u00ednimo poss\u00edvel. De forma objetiva, a documenta\u00e7\u00e3o de arquitetura \u00fatil para os projetos demanda atualiza\u00e7\u00f5es menos frequentes.<\/span><\/p>\n

      A documenta\u00e7\u00e3o arquitetural deve registrar, primeiro, aspectos que v\u00e3o permanecer verdadeiros por mais tempo.<\/b> Sem d\u00favidas, se encaixam nessa caracter\u00edstica algum detalhamento das restri\u00e7\u00f5es e dos atributos de qualidade.<\/span><\/p>\n

      A documenta\u00e7\u00e3o arquitetural tamb\u00e9m precisa dar \u00eanfase na estrat\u00e9gia – padr\u00e3o coerente para tomada de decis\u00f5es – que ir\u00e1 autorizar mudan\u00e7as. <\/b>Ou seja, que crit\u00e9rios devem ser observados para determinar a necessidade de adicionar, remover ou substituir a implementa\u00e7\u00e3o dos componentes.<\/span><\/p>\n

      Finalmente, a documenta\u00e7\u00e3o tamb\u00e9m deve expor a estrutura atual e suas propriedades. <\/b>Entretanto, quanto maior for a fragmenta\u00e7\u00e3o de componentes de um software, por exemplo, em arquiteturas baseadas em microsservi\u00e7os – extremamente din\u00e2micos e auto organizados, com estrat\u00e9gias de descoberta sofisticadas – menor ser\u00e1 o incentivo para documentar suas intera\u00e7\u00f5es. Nesses casos, o uso de ferramentas que permitam a “captura” da arquitetura-do-momento automaticamente, como, por exemplo, solu\u00e7\u00f5es APM \u00e9 essencial.<\/span><\/p>\n

      Considera\u00e7\u00f5es sobre ADRs (Architecture Decision Records)<\/h2>\n

      Uma decis\u00e3o arquitetural trata sempre de uma escolha de design <\/em>relacionada a uma caracter\u00edstica funcional ou n\u00e3o-funcional \u00a0indiscutivelmente relevante, pois, geralmente, tem algumas das seguintes caracter\u00edsticas:<\/p>\n

        \n
      • afeta os objetivos do neg\u00f3cio ou atributos de qualidade (como performance, disponibilidade, seguran\u00e7a, manutenabilidade, etc.)<\/li>\n
      • \u00e9 dif\u00edcil de ser desfeita (uma das quatro fontes da complexidade)<\/li>\n
      • implica em gastos ou economias consider\u00e1veis de tempo ou dinheiro (protip<\/strong>: tempo geralmente \u00e9 um proxy<\/em> para dinheiro)<\/li>\n
      • demandou, para sua formula\u00e7\u00e3o, consider\u00e1vel tempo e esfor\u00e7o do time, geralmente demandando provas de conceito e avalia\u00e7\u00e3o de trade-offs<\/em>.<\/li>\n
      • \u00e9 extremamente complexa podendo n\u00e3o fazer sentido em primeira an\u00e1lise, sem o\u00a0background\u00a0<\/em>necess\u00e1rio.<\/li>\n<\/ul>\n
        \nDecis\u00f5es arquiteturais s\u00e3o realizadas durante todo o ciclo de vida de um software, com maior frequ\u00eancia em sua concep\u00e7\u00e3o e em pontos onde ocorrem mudan\u00e7as sens\u00edveis na escala ou escopo.<\/strong> Se n\u00e3o forem adequadamente documentadas, podem, no futuro, gerar comportamentos perigosos que coloquem em risco o sistema.\n
        \n

        Uma das coisas mais dif\u00edceis de rastrear durante a vida de um projeto \u00e9 a motiva\u00e7\u00e3o por tr\u00e1s de certas decis\u00f5es. Uma nova pessoa que est\u00e1 entrando em um projeto pode ficar perplexa, perplexa, encantada ou enfurecida com alguma decis\u00e3o passada. Sem compreender a l\u00f3gica ou as consequ\u00eancias, essa pessoa tem apenas duas op\u00e7\u00f5es: aceitar cegamente a decis\u00e3o ou mud\u00e1-la cegamente. (Nygard)<\/em><\/p>\n

        \n

        Uma pr\u00e1tica que tem se tornado comum \u00e9 documentar as decis\u00f5es arquiteturais em registros (architectural decision records<\/em>) em um arquivo de texto curto, mantidos no reposit\u00f3rio do projeto, geralmente composto das seguintes se\u00e7\u00f5es:<\/p>\n

          \n
        • T\u00edtulo<\/strong>, curto e expressivo<\/li>\n
        • Contexto<\/strong>, descrevendo aspectos t\u00e9cnicos, pol\u00edticos, sociais e espec\u00edficos que impactam na decis\u00e3o, preferencialmente em linguagem neutra.<\/li>\n
        • Decis\u00e3o<\/strong>, expressando, em linguagem ativa, que caminho deve ser seguido.<\/li>\n
        • Status<\/em><\/strong>, visto que a decis\u00e3o ainda pode ser uma proposta, estar implementada (aceita), ultrapassada (deprecated<\/em>) ou revertida (superseded<\/em>).<\/li>\n
        • Consequ\u00eancias<\/strong>, descrevendo o contexto geral resultante da decis\u00e3o. Devem ser observados aspectos positivos, negativos e neutros.<\/li>\n<\/ul>\n
          \n

          ADRs \u00e9 pr\u00e1tica recomendada pela Toughtworks em seu famoso radar.<\/p>\n

          Muita documenta\u00e7\u00e3o pode ser substitu\u00edda por c\u00f3digos e testes altamente leg\u00edveis. Em um mundo de arquitetura evolutiva, no entanto, \u00e9 importante registrar certas decis\u00f5es de design para o benef\u00edcio dos futuros membros da equipe, bem como para supervis\u00e3o externa. Registros de decis\u00e3o de arquitetura leve \u00e9 uma t\u00e9cnica para capturar decis\u00f5es arquitet\u00f4nicas importantes junto com seu contexto e consequ\u00eancias. 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\u00f3prio c\u00f3digo. Para a maioria dos projetos, n\u00e3o vemos raz\u00e3o para voc\u00ea n\u00e3o querer usar essa t\u00e9cnica. (Toughtworks)<\/em><\/p>\n

          Grandes jornadas s\u00e3o mais f\u00e1ceis com um mapa\u2026<\/h2>\nAs decis\u00f5es de design que se relacionam com a arquitetura garantem o atendimento dos objetivos do neg\u00f3cio, respeitando restri\u00e7\u00f5es e atingindo atributos de qualidade. <\/strong>Entretanto, para que essas decis\u00f5es cumpram seu papel, precisam ser rememoradas e compartilhadas com quem se juntar ao time ao longo do tempo. Tudo bem come\u00e7ar um projeto sem um mapa, mas \u00e9 sempre bom ter um registro do caminho que foi percorrido e dos motivos para cada decis\u00e3o.\n
          \n

          Documenta\u00e7\u00e3o 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\u00e3o.<\/p>\n

          Nos pr\u00f3ximos cap\u00edtulos, iremos introduzir, aos poucos, alguns documentos arquiteturais \u00fateis para a maioria dos projetos.<\/p>\n

          \/\/ TODO<\/h2>\n

          Antes de avan\u00e7ar para o pr\u00f3ximo cap\u00edtulo recomendo as seguintes atividades:<\/p>\n

            \n
          • Relacione quais documenta\u00e7\u00f5es arquiteturais voc\u00ea est\u00e1 habituado a utilizar.<\/li>\n
          • Pondere sobre os “gaps<\/em>” de informa\u00e7\u00e3o que precisa enfrentar rotineiramente em seu trabalho. Que informa\u00e7\u00f5es entende que precisaram estar documentadas?<\/li>\n
          • Pondere sobre o qu\u00e3o f\u00e1cil (ou dif\u00edcil) \u00e9 incluir algu\u00e9m novo no seu time hoje. Como \u00e9 feita a integra\u00e7\u00e3o t\u00e9cnica?<\/li>\n<\/ul>\n","protected":false},"featured_media":1363,"parent":0,"comment_status":"open","ping_status":"closed","template":"","url":[],"sessoes":[57],"apendices":[],"capitulos":[16],"class_list":["post-1293","volume-1","type-volume-1","status-publish","has-post-thumbnail","hentry","sessoes-secao-1","capitulos-capitulo-1-3"],"acf":[],"yoast_head":"\nDocumentar \u00e9 preciso (?) ... \/ Cap\u00edtulo 2 v1.0 - Manual do Arquiteto de Software<\/title>\n<meta name=\"robots\" content=\"index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1\" \/>\n<link rel=\"canonical\" href=\"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/volume-1\/capitulo-2-v1\/\" \/>\n<meta property=\"og:locale\" content=\"pt_BR\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"Documentar \u00e9 preciso (?) ... \/ Cap\u00edtulo 2 v1.0 - Manual do Arquiteto de Software\" \/>\n<meta property=\"og:description\" content=\"Se\u00a0 o prop\u00f3sito das pr\u00e1ticas de arquitetura de software \u00e9 aumentar as chances de que os objetivos do neg\u00f3cio sejam atingidos – respeitando restri\u00e7\u00f5es e atributos de qualidade – \u00e9 importante disseminar esses par\u00e2metros, com o m\u00ednimo de ambiguidade e subjetividade, durante todo o ciclo de vida do software que, ali\u00e1s, pode durar d\u00e9cadas come\u00e7ando […]\" \/>\n<meta property=\"og:url\" content=\"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/volume-1\/capitulo-2-v1\/\" \/>\n<meta property=\"og:site_name\" content=\"Manual do Arquiteto de Software\" \/>\n<meta property=\"article:publisher\" content=\"https:\/\/facebook.com\/eximiaco\" \/>\n<meta property=\"article:modified_time\" content=\"2024-01-11T20:56:22+00:00\" \/>\n<meta property=\"og:image\" content=\"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/wp-content\/uploads\/2021\/04\/viktor-talashuk-05HLFQu8bFw-unsplash.jpg\" \/>\n\t<meta property=\"og:image:width\" content=\"1024\" \/>\n\t<meta property=\"og:image:height\" content=\"681\" \/>\n\t<meta property=\"og:image:type\" content=\"image\/jpeg\" \/>\n<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n<meta name=\"twitter:site\" content=\"@eximiaco\" \/>\n<meta name=\"twitter:label1\" content=\"Est. tempo de leitura\" \/>\n\t<meta name=\"twitter:data1\" content=\"15 minutos\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\/\/schema.org\",\"@graph\":[{\"@type\":\"WebPage\",\"@id\":\"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/volume-1\/capitulo-2-v1\/\",\"url\":\"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/volume-1\/capitulo-2-v1\/\",\"name\":\"Documentar \u00e9 preciso (?) ... \/ Cap\u00edtulo 2 v1.0 - Manual do Arquiteto de Software\",\"isPartOf\":{\"@id\":\"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/#website\"},\"primaryImageOfPage\":{\"@id\":\"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/volume-1\/capitulo-2-v1\/#primaryimage\"},\"image\":{\"@id\":\"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/volume-1\/capitulo-2-v1\/#primaryimage\"},\"thumbnailUrl\":\"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/wp-content\/uploads\/2021\/04\/viktor-talashuk-05HLFQu8bFw-unsplash.jpg\",\"datePublished\":\"2021-04-17T22:28:38+00:00\",\"dateModified\":\"2024-01-11T20:56:22+00:00\",\"breadcrumb\":{\"@id\":\"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/volume-1\/capitulo-2-v1\/#breadcrumb\"},\"inLanguage\":\"pt-BR\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/volume-1\/capitulo-2-v1\/\"]}]},{\"@type\":\"ImageObject\",\"inLanguage\":\"pt-BR\",\"@id\":\"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/volume-1\/capitulo-2-v1\/#primaryimage\",\"url\":\"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/wp-content\/uploads\/2021\/04\/viktor-talashuk-05HLFQu8bFw-unsplash.jpg\",\"contentUrl\":\"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/wp-content\/uploads\/2021\/04\/viktor-talashuk-05HLFQu8bFw-unsplash.jpg\",\"width\":1024,\"height\":681},{\"@type\":\"BreadcrumbList\",\"@id\":\"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/volume-1\/capitulo-2-v1\/#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Home\",\"item\":\"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Volume 1\",\"item\":\"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/volume-1\/\"},{\"@type\":\"ListItem\",\"position\":3,\"name\":\"Documentar \u00e9 preciso (?) … \/ Cap\u00edtulo 2 v1.0\"}]},{\"@type\":\"WebSite\",\"@id\":\"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/#website\",\"url\":\"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/\",\"name\":\"Manual do Arquiteto de Software\",\"description\":\"\",\"publisher\":{\"@id\":\"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/#organization\"},\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":{\"@type\":\"EntryPoint\",\"urlTemplate\":\"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/?s={search_term_string}\"},\"query-input\":{\"@type\":\"PropertyValueSpecification\",\"valueRequired\":true,\"valueName\":\"search_term_string\"}}],\"inLanguage\":\"pt-BR\"},{\"@type\":\"Organization\",\"@id\":\"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/#organization\",\"name\":\"EximiaCo\",\"url\":\"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/\",\"logo\":{\"@type\":\"ImageObject\",\"inLanguage\":\"pt-BR\",\"@id\":\"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/#\/schema\/logo\/image\/\",\"url\":\"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/wp-content\/uploads\/2022\/04\/simbolo-eximiaco.jpg\",\"contentUrl\":\"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/wp-content\/uploads\/2022\/04\/simbolo-eximiaco.jpg\",\"width\":150,\"height\":150,\"caption\":\"EximiaCo\"},\"image\":{\"@id\":\"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/#\/schema\/logo\/image\/\"},\"sameAs\":[\"https:\/\/facebook.com\/eximiaco\",\"https:\/\/x.com\/eximiaco\"]}]}<\/script>\n<!-- \/ Yoast SEO plugin. -->","yoast_head_json":{"title":"Documentar \u00e9 preciso (?) ... \/ Cap\u00edtulo 2 v1.0 - Manual do Arquiteto de Software","robots":{"index":"index","follow":"follow","max-snippet":"max-snippet:-1","max-image-preview":"max-image-preview:large","max-video-preview":"max-video-preview:-1"},"canonical":"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/volume-1\/capitulo-2-v1\/","og_locale":"pt_BR","og_type":"article","og_title":"Documentar \u00e9 preciso (?) ... \/ Cap\u00edtulo 2 v1.0 - Manual do Arquiteto de Software","og_description":"Se\u00a0 o prop\u00f3sito das pr\u00e1ticas de arquitetura de software \u00e9 aumentar as chances de que os objetivos do neg\u00f3cio sejam atingidos – respeitando restri\u00e7\u00f5es e atributos de qualidade – \u00e9 importante disseminar esses par\u00e2metros, com o m\u00ednimo de ambiguidade e subjetividade, durante todo o ciclo de vida do software que, ali\u00e1s, pode durar d\u00e9cadas come\u00e7ando […]","og_url":"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/volume-1\/capitulo-2-v1\/","og_site_name":"Manual do Arquiteto de Software","article_publisher":"https:\/\/facebook.com\/eximiaco","article_modified_time":"2024-01-11T20:56:22+00:00","og_image":[{"width":1024,"height":681,"url":"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/wp-content\/uploads\/2021\/04\/viktor-talashuk-05HLFQu8bFw-unsplash.jpg","type":"image\/jpeg"}],"twitter_card":"summary_large_image","twitter_site":"@eximiaco","twitter_misc":{"Est. tempo de leitura":"15 minutos"},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"WebPage","@id":"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/volume-1\/capitulo-2-v1\/","url":"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/volume-1\/capitulo-2-v1\/","name":"Documentar \u00e9 preciso (?) ... \/ Cap\u00edtulo 2 v1.0 - Manual do Arquiteto de Software","isPartOf":{"@id":"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/#website"},"primaryImageOfPage":{"@id":"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/volume-1\/capitulo-2-v1\/#primaryimage"},"image":{"@id":"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/volume-1\/capitulo-2-v1\/#primaryimage"},"thumbnailUrl":"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/wp-content\/uploads\/2021\/04\/viktor-talashuk-05HLFQu8bFw-unsplash.jpg","datePublished":"2021-04-17T22:28:38+00:00","dateModified":"2024-01-11T20:56:22+00:00","breadcrumb":{"@id":"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/volume-1\/capitulo-2-v1\/#breadcrumb"},"inLanguage":"pt-BR","potentialAction":[{"@type":"ReadAction","target":["https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/volume-1\/capitulo-2-v1\/"]}]},{"@type":"ImageObject","inLanguage":"pt-BR","@id":"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/volume-1\/capitulo-2-v1\/#primaryimage","url":"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/wp-content\/uploads\/2021\/04\/viktor-talashuk-05HLFQu8bFw-unsplash.jpg","contentUrl":"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/wp-content\/uploads\/2021\/04\/viktor-talashuk-05HLFQu8bFw-unsplash.jpg","width":1024,"height":681},{"@type":"BreadcrumbList","@id":"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/volume-1\/capitulo-2-v1\/#breadcrumb","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/"},{"@type":"ListItem","position":2,"name":"Volume 1","item":"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/volume-1\/"},{"@type":"ListItem","position":3,"name":"Documentar \u00e9 preciso (?) … \/ Cap\u00edtulo 2 v1.0"}]},{"@type":"WebSite","@id":"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/#website","url":"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/","name":"Manual do Arquiteto de Software","description":"","publisher":{"@id":"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/#organization"},"potentialAction":[{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/?s={search_term_string}"},"query-input":{"@type":"PropertyValueSpecification","valueRequired":true,"valueName":"search_term_string"}}],"inLanguage":"pt-BR"},{"@type":"Organization","@id":"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/#organization","name":"EximiaCo","url":"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/","logo":{"@type":"ImageObject","inLanguage":"pt-BR","@id":"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/#\/schema\/logo\/image\/","url":"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/wp-content\/uploads\/2022\/04\/simbolo-eximiaco.jpg","contentUrl":"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/wp-content\/uploads\/2022\/04\/simbolo-eximiaco.jpg","width":150,"height":150,"caption":"EximiaCo"},"image":{"@id":"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/#\/schema\/logo\/image\/"},"sameAs":["https:\/\/facebook.com\/eximiaco","https:\/\/x.com\/eximiaco"]}]}},"_links":{"self":[{"href":"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/wp-json\/wp\/v2\/volume-1\/1293","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/wp-json\/wp\/v2\/volume-1"}],"about":[{"href":"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/wp-json\/wp\/v2\/types\/volume-1"}],"replies":[{"embeddable":true,"href":"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/wp-json\/wp\/v2\/comments?post=1293"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/wp-json\/wp\/v2\/media\/1363"}],"wp:attachment":[{"href":"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/wp-json\/wp\/v2\/media?parent=1293"}],"wp:term":[{"taxonomy":"url","embeddable":true,"href":"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/wp-json\/wp\/v2\/url?post=1293"},{"taxonomy":"sessoes","embeddable":true,"href":"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/wp-json\/wp\/v2\/sessoes?post=1293"},{"taxonomy":"apendices","embeddable":true,"href":"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/wp-json\/wp\/v2\/apendices?post=1293"},{"taxonomy":"capitulos","embeddable":true,"href":"https:\/\/elemarjr.com\/livros\/arquiteturadesoftware\/wp-json\/wp\/v2\/capitulos?post=1293"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}