Casos de uso

Propósito

Uma página de caso de uso transforma uma entrada do catálogo de casos de uso em uma configuração que alguém consegue construir e verificar. A entrada dá à página o título, o cenário, os produtos e as arquiteturas de referência que ela pode construir. A página nunca inventa um caso de uso próprio. O catálogo é mantido pela Azion. Quem precisa de uma entrada, ou encontra uma errada, pede antes de escrever a página. O pedido vai pelos templates de issue do repositório, ou pelo dono do catálogo dentro da Azion. O leitor chega com uma situação, não com uma tarefa: uma loja que fica lenta durante uma promoção, um evento ao vivo que precisa alcançar mais uma região.

Um caso de uso é uma especificação, não um artigo. Ele carrega em uma página tudo de que o implementador precisa: os produtos que o cenário exige, a arquitetura, a configuração, as verificações e as métricas que mostram o resultado funcionando. Esse implementador muitas vezes é um agente, então a página é escrita para ser executada, não para ser lida.

Casos de uso vivem na seção Guias, nunca dentro de um produto, na área da solução da sua entrada no catálogo. O rótulo da área é o nome da solução.

Quando usar

Reconheça um caso de uso por:

• Um título que é o nome de um caso de uso do catálogo, sem alteração, traduzido na página em português: uma frase verbal no imperativo que nomeia um workload, sem nomes de produto.
• Um leitor que chegou com uma situação de negócio, e não com uma tarefa.
• Uma tabela de requisitos ligando cada necessidade de negócio ao produto que a atende.
• Um resultado que continua mensurável depois que a configuração funciona.
• Uma especificação completa o bastante para um agente executar sem fazer perguntas.

Continua sendo um caso de uso quando:

• Configura quatro coisas ou menos. Mais de quatro significa que a entrada é larga demais para uma página.
• Aponta para o procedimento genérico em vez de repeti-lo aqui.
• É publicado sem demo, porque nenhuma existe. Nunca descreva uma demo que não roda.

Escreva outra coisa quando:

• Não há nada a configurar. A página explica um design, então escreva uma página de arquitetura.
• A configuração é uma tarefa só. Isso é um guia how-to.
• O catálogo não tem entrada para ele, e o objetivo não precisa de uma situação de cliente. Isso é um guia multiproduto. Uma entrada faz da página um caso de uso, qualquer que seja a redação do objetivo.
• O leitor não tem cenário, só o produto. Isso é um tutorial.

Registro

Procedural: 20 palavras por frase, uma instrução por passo, imperativo e ativo. Tom: preciso, claro, objetivo, sóbrio. Estrutura de frases tem as regras.

Estrutura

Componentes obrigatórios

• Cenário: três a cinco frases tiradas do Cenário da entrada do catálogo. Elas nomeiam o ator, o workload e a situação em que ele está, o que esta página configura e o resultado mensurável. Seguidas de uma linha declarando o que o caso de uso não cobre, a exclusão da própria entrada.
• Pré-requisitos: uma seção ## Pré-requisitos, cada item um link ou um comando de uma linha quando existe um.
• Produtos exigidos: a tabela de requisitos. Uma linha por requisito, nomeando a necessidade técnica, o produto que a atende e a página que a documenta. A coluna Produto contém os produtos da entrada do catálogo. Uma dependência que a documentação do produto confirma e a entrada omite também entra na tabela, e a lacuna é informada ao catálogo. A necessidade técnica nomeia o recurso da plataforma que o leitor configura.
• Arquitetura de referência: uma seção ## Arquitetura de referência. Ela abre nomeando qual das arquiteturas de referência da entrada esta página constrói, e depois traz um diagrama em mermaid e um ### Fluxo de dados numerado. As outras arquiteturas de referência da entrada viram links para páginas de arquitetura, quando existem.
• Configuração: uma seção ## Configure <coisa> por requisito cuja configuração é específica deste caso de uso, no máximo quatro. Cada uma tem um procedimento que termina com sua frase de resultado. Um requisito atendido por um procedimento genérico não ganha seção. A tabela de requisitos aponta o guia que o documenta, e a checagem fica na seção de verificação.
• Verificação: uma seção ## Verifique a configuração com uma checagem por requisito e o resultado esperado.
• Medição de resultados: uma seção ## Medindo resultados nomeando as métricas que mostram a configuração funcionando, e onde ler cada uma.
• Best practices: uma seção ## Best practices com as recomendações e o raciocínio por trás de cada uma.
• Próximos passos: um fechamento ## Próximos passos, um DocCardGroup com um card por destino: o título, o link e o motivo como texto do card.

Componentes opcionais

• Demo: uma seção ## Demo apontando para um exemplo em execução, um template ou um repositório. Omita quando não existir; nunca descreva uma demo que não roda.

As seções mantêm essa ordem. O que governa a página é a proporção, não o comprimento. Um caso de uso é mais longo do que os outros tipos por definição: ele é uma especificação, e quem implementa a partir dele não pode preencher uma lacuna perguntando. O peso da página fica nas seções que quem implementa executa:

• As seções de configuração sustentam a página. No máximo quatro, e juntas elas são a maior parte dela. Se não são, a página está descrevendo um cenário em vez de construir um.
• Cenário, pré-requisitos, demo e próximos passos ficam curtos. Cada um orienta e encaminha. Um cenário que passa de dois parágrafos está vendendo.
• Arquitetura de referência, verificação, medição e best practices ficam entre os dois. Cada uma carrega conteúdo real — um diagrama, uma verificação que roda, um sinal a observar — e nenhuma delas é lugar para expandir.

O limite que mantém um caso de uso honesto é o teto de quatro seções em ## Configure, não um comprimento. Comprimir nunca é a solução, porque o que se comprime é o diagrama, o output do comando e o valor concreto — as partes sem as quais quem implementa não consegue seguir.

Template

Copie o template e substitua cada <placeholder>:

Regras

• Escreva uma especificação, não um artigo. Todo valor é concreto, todo comando roda, e nenhum passo diz “dependendo da sua configuração”. O leitor pode ser um agente, e um agente não resolve uma ambiguidade perguntando.
• Mostre o output depois de cada comando. O leitor vê como o sucesso se parece antes que o próximo passo dependa dele. A regra está em Procedimentos.
• Reduza o cenário a uma configuração construível. Declare assim: Um <time> que <tem isto> configura <esta configuração> para que <este resultado verificável>. Se a frase precisa de um “e também”, a entrada é larga demais para uma página. Escreva a primeira configuração e informe a largura ao catálogo. Não invente um segundo caso de uso.
• Comece pela tabela de requisitos. Cada linha é um requisito que você confirmou no produto. Um requisito que você não consegue confirmar não entra na tabela.
• Deixe no corpo o que é específico deste caso de uso. Aponte para o que vale para todos. O caminho genérico é um link; a página carrega o que o cenário muda.
• Limite a configuração a quatro seções. Um requisito atendido por um procedimento genérico nunca conta: o guia dele é apontado na tabela de requisitos, e a checagem dele fica na seção de verificação. Mais de quatro requisitos que precisam de seção própria significa que a entrada é larga demais para uma página. Reduza a configuração à arquitetura de referência que a página constrói e informe a largura ao catálogo. Nunca aumente o limite, e nunca invente um segundo caso de uso.
• Faça o diagrama em mermaid. O diagrama é texto, então um agente lendo o markdown twin recebe o design, não uma referência de imagem. O fluxo de dados numerado continua carregando o significado: o diagrama nunca fica sozinho.
• Separe verificação de medição. Verificação é uma checagem única de que a configuração está correta. Medição é o sinal contínuo de que ela continua funcionando.
• Mantenha as best practices como recomendações com razões. Uma recomendação sem a razão é uma instrução na seção errada, e o lugar dela é no procedimento.
• Nunca faça uma afirmação comercial. Sem economia de custo, sem porcentagem, sem concorrente, sem nome de cliente e sem afirmar que uma configuração torna alguém compliance.
• Números de exemplo não são limites. Um número que enquadra o cenário fica no parágrafo de cenário e não aparece em nenhum outro lugar.
• Tire o título, o cenário e os produtos da entrada do catálogo. Um pedido que chega como cenário solto, como e-commerce ou live streaming, é ligado a uma entrada primeiro. Uma entrada faz da página um caso de uso, qualquer que seja a redação do objetivo. Quando nenhuma entrada o cobre, um objetivo que não precisa de uma situação de cliente é um guia multiproduto. Uma situação de cliente que o catálogo deveria ter é proposta como entrada primeiro. Um caso de uso nunca é inventado na página.
• Nunca invente nome de produto, campo ou valor. Tire os nomes de produto de Terminologia da documentação, e campos e valores do produto, não de uma URL ou de um caminho de diretório.
• Informe o permalink quando a página é publicada, para que o campo Docs da entrada do catálogo passe a Published.

Exemplos

Este exemplo, em inglês, do caso de uso Build e-commerce storefronts constrói a arquitetura de referência Origin-hosted commerce platform storefront. Ele mostra o cenário, a linha do que não é coberto e a tabela de requisitos:

Cada linha nomeia um requisito, o recurso que o leitor configura, o produto que o atende e a página que o documenta. O leitor consegue conferir cada afirmação antes de rodar um único passo.

Application Accelerator não está entre os produtos da entrada do catálogo. A referência do Rules Engine confirma que o comportamento Bypass Cache exige o produto, então a linha o carrega e a lacuna volta para o catálogo.

Relacionados