vlaskos/skill-documentacao-arquitetura

Documentando arquiteturas de software

A documentação de arquitetura existe para responder perguntas que os stakeholders, de outra forma, farão a você em reuniões durante toda a vida do sistema: Como isso é montado? Por que é assim? Onde eu mudo X? Isso suporta Y? Uma boa documentação responde a essas perguntas uma vez, por escrito, de uma forma que cada leitor realmente possa usar.

Este skill é um método para produzir essa documentação e para revisar documentação escrita por outra pessoa. Ele é construído sobre padrões e modelos abertos e gratuitamente disponíveis, não sobre um único texto protegido por direitos autorais:

• ISO/IEC/IEEE 42010 — o padrão internacional para descrição de arquitetura. Ele fornece o vocabulário usado em todo o processo: stakeholder, preocupação, viewpoint, visão, modelo, decisão de arquitetura, justificativa.
• O modelo C4 (Simon Brown) — um conjunto leve de diagramas estruturais em quatro níveis de zoom: contexto, contêiner, componente, código.
• O modelo 4+1 visões (Philippe Kruchten) — cinco perspectivas concorrentes: lógica, processo, desenvolvimento, física e os cenários que as unem.
• arc42 — um template de documentação licenciado sob Creative Commons cuja estrutura de seções é um esqueleto prático para uma descrição completa de arquitetura.
• Registros de Decisão de Arquitetura (o formato ADR popularizado por Michael Nygard) — um arquivo curto por decisão significativa.

O método

A documentação é guiada por quem a lê e o que eles precisam decidir ou fazer. Trabalhe nesta ordem.

1. Identifique os stakeholders e suas preocupações. Liste quem depende da arquitetura (desenvolvedores, operadores, revisores de segurança, donos de produto, integradores, auditores) e o que cada um precisa que a documentação responda. Uma preocupação é uma pergunta ou qualidade que importa para alguém: "posso implantar isso sem tempo de inatividade?", "onde os dados do cliente residem?", "como adiciono um novo provedor de pagamento?". As preocupações determinam tudo o que se segue. Consulte references/viewpoints-and-views.md.

2. Selecione os viewpoints que cobrem as preocupações. Um viewpoint é um tipo reutilizável de visão: as convenções para construir um tipo de representação (quais elementos mostra, quais relacionamentos, qual notação). Escolha o menor conjunto de viewpoints que, juntos, abordem todas as preocupações importantes. Não escreva uma visão que ninguém precisa. Consulte references/view-catalog.md.

3. Construa as visões. Cada visão é uma representação do sistema a partir de um viewpoint: um diagrama mais a prosa que o explica. A maioria dos sistemas precisa de uma visão estrutural (quais são as peças e como dependem umas das outras), uma visão de tempo de execução (o que acontece durante a execução: processos, fluxos, interações) e uma visão de implantação (como o software é mapeado para a infraestrutura). Adicione visões comportamentais para as partes onde o tempo ou a sequência são o ponto principal. Os níveis C4 e as perspectivas 4+1 são maneiras concretas e comprovadas de preencher essas visões. Consulte references/view-catalog.md.

4. Capture as decisões e suas justificativas. A parte mais valiosa e mais frequentemente ausente da documentação de arquitetura é o porquê. Registre cada decisão significativa (o contexto, as opções consideradas, a escolha e as consequências) como um Registro de Decisão de Arquitetura. A justificativa é o que permite que a próxima pessoa altere o sistema com segurança, em vez de adivinhar. Consulte references/decisions-and-rationale.md.

5. Monte a descrição e adicione orientação. Uma pilha de visões não é um documento. Adicione o tecido conjuntivo: uma visão geral do sistema em uma página, uma declaração de escopo e contexto, um glossário e uma nota explícita sobre como as visões se relacionam entre si (o mesmo elemento visto em duas visões é a principal fonte de confusão do leitor, então resolva isso). Use references/documentation-template.md para um esqueleto completo de seções.

6. Revise antes de entregar. Execute a documentação contra references/review-checklist.md. Os dois modos de falha são incompletude (uma preocupação que nenhuma visão aborda) e ilegibilidade (diagramas sem chaves, termos indefinidos, nenhuma declaração sobre o que o leitor está vendo).

Como usar este skill

• Começando do zero → siga os seis passos acima, usando references/documentation-template.md como estrutura alvo.
• Decidindo o que escrever → references/viewpoints-and-views.md (preocupações → viewpoints) e references/view-catalog.md (o catálogo de tipos de visão).
• Registrando uma decisão → references/decisions-and-rationale.md (formato ADR e exemplos).
• Revisando documentação existente → references/review-checklist.md.
• Escolhendo entre frameworks ou mapeando um no outro → references/frameworks-map.md.

Princípios

• Escreva para um leitor, não para completude. Toda visão, diagrama e parágrafo deve remeter a uma preocupação de stakeholder. Se você não puder nomear quem precisa daquilo, corte.
• Todo diagrama precisa de uma chave. Notação que "parece óbvia" não é. Declare o que as caixas e linhas significam. Um diagrama não explicado é um palpite esperando para dar errado.
• Registre a justificativa enquanto você avança. Decisões são baratas de capturar no momento em que são tomadas e caras de reconstruir depois.
• Mantenha próximo ao código e atualizado. Documentação que se desvia da realidade é pior do que nenhuma, porque as pessoas confiam nela. Prefira um documento menor que você manterá a um grande que não manterá.
• Deixe o risco do sistema definir a profundidade. Documente detalhadamente as partes onde errar é caro; esboce o resto.