Páginas de arquitetura

Propósito

Uma página de arquitetura mostra uma arquitetura de referência do catálogo de casos de uso: como produtos e recursos da plataforma se combinam em um design. O leitor quer entender o formato do design antes de construí-lo.

Ela aplica a forma base de explicação, a mesma de uma página de conceito. A diferença é o assunto: uma página de conceito explica uma coisa, uma página de arquitetura explica como muitas coisas se encaixam.

Quando usar

Escreva uma página de arquitetura quando:

• Um design precisa de mais de um produto ou recurso da plataforma, e a relação entre eles é o ponto.
• O leitor precisa ver a ordem de uma requisição ou de um dataflow para entender o design.
• Um guia fica redesenhando o mesmo sistema em texto corrido.

Não escreva uma página de arquitetura quando:

• O assunto é um produto ou uma ideia. Escreva uma página de conceito.
• O leitor quer construir a coisa. Escreva a página de caso de uso que a constrói, ou um guia multiproduto, e aponte para ela daqui.
• O catálogo não tem entrada para o design. Proponha o design ao catálogo de casos de uso primeiro; a página vem depois da entrada.
• O design não pode ser desenhado. Um design que você não consegue desenhar é um design que você ainda não entende bem o suficiente para publicar.

Registro

Descritivo: 25 palavras por frase, voz ativa, passiva apenas quando o agente é desconhecido. Tom: explicativo, claro, sistemático. Estrutura de frases tem as regras.

Estrutura

O título é o nome da arquitetura de referência no catálogo, sem alteração, traduzido na página em português. Esse nome é um sintagma nominal que nomeia o sistema construído, como Server-rendered headless CMS website, nunca com o sufixo Reference Architecture. O parágrafo de abertura é o Resumo da entrada: qual problema o design resolve, e para quem. Ele nomeia o caso de uso que o design implementa, com link para a página de caso de uso quando ela existe.

Seções obrigatórias, nesta ordem

• ## Diagrama de arquitetura: o diagrama como um bloco de código mermaid, e depois um parágrafo que o lê.
• ### Dataflow: um passo a passo numerado do que vai para onde, com no máximo seis itens.
• ## Componentes: uma entrada por componente da entrada do catálogo, com o seu papel. Produtos entram pelo nome, recursos da plataforma em minúscula como instâncias, e features e integrações rotuladas como o catálogo as rotula.
• ## Implementação: apenas links. A página de caso de uso entra aqui quando ela constrói este design, seguida dos guias e templates do Marketplace que implementam todo o design ou parte dele. Uma página de caso de uso que constrói um design irmão recebe o link no parágrafo de abertura, como o caso de uso que a arquitetura implementa, e não aqui.
• ## Recursos relacionados: a seção de fechamento, uma lista de DocItem, cada linha com sua razão.

Template

Regras

• Desenhe o diagrama em mermaid. O diagrama é texto, então um agente que busca o gêmeo em markdown lê o próprio design em vez de uma referência de imagem. Não use imagem para um diagrama de arquitetura.
• O diagrama nunca fica sozinho. O dataflow numerado carrega o significado, e ele permanece mesmo quando o diagrama é renderizado.
• Rotule cada nó e cada aresta com palavras, e nunca dependa apenas de cor para carregar uma distinção.
• Nomeie cada componente e diga por que ele está ali. Uma lista de nomes de produto é uma lista de peças.
• Aponte para a implementação, não a coloque aqui. Os passos vão na página de caso de uso ou em um guia multiproduto.
• Escreva só as seções que você consegue confirmar. Uma seção obrigatória cujo conteúdo você não consegue confirmar com o time que cuida do produto fica de fora até que consiga, nunca é preenchida com um palpite.
• Informe o permalink quando a página é publicada, para que o campo Docs da entrada do catálogo passe a Published.

Exemplos

• Implante sites Jamstack: a página publicada que o catálogo liga a Git-driven static website. Ela traz um diagrama, um dataflow numerado, os componentes envolvidos e links para a implementação.

Este trecho mostra a abertura, a seção do diagrama e o dataflow da página Git-driven static website. O catálogo registra essa arquitetura de referência sob o caso de uso Build and run marketing websites. Nenhuma página de caso de uso foi publicada ainda, então o caso de uso é nomeado sem link:

Relacionados