Desenvolvimento

Modelo de especificação técnica em Markdown

Este modelo de especificação técnica é um exemplo prático, não um formulário em branco. Ele descreve um serviço de pagamento e mostra como um diagrama, uma fórmula e um exemplo de código se encaixam num só documento. Troque o conteúdo pelo seu próprio projeto e mantenha a estrutura.

Abrir este modelo no editor

Categoria: Desenvolvimento
Estilo padrão: Técnico

Quando usar

Escreva uma especificação antes de construir qualquer coisa que mais de uma pessoa precise aprovar. Engenheiros leem para revisar o projeto, e colegas de produto ou QA leem para saber o que vai ser lançado. Uma versão em PDF serve bem para revisões de projeto, aprovação de clientes e qualquer arquivo em que o documento precise parecer igual anos depois.

O que tem dentro

Uma visão geral com campos para preencher projeto e responsável, seguida de um diagrama de sequência Mermaid do fluxo da requisição.
Uma seção de orçamento de novas tentativas com uma fórmula em TeX, e um exemplo em TypeScript num bloco de código com realce.
Uma quebra de página manual antes da lista de questões abertas, para que ela comece numa página nova.

Dicas para um documento melhor

Coloque o diagrama de fluxo antes dos detalhes. Revisores que entendem a sequência primeiro leem as demais seções mais rápido e fazem perguntas melhores.
Mantenha as questões abertas na especificação até alguém respondê-las, depois mova cada resposta para a seção certa. Para uma especificação longa, adicione uma capa e um sumário.

Pré-visualização do modelo

Especificação do serviço de pagamento

Projeto: Projeto ou tema Responsável: Seu nome

Visão geral

O serviço de pagamento recebe um pedido, cobra o cartão e registra o resultado. As requisições são idempotentes por 24 horas.

Fluxo

sequenceDiagram
  participant App
  participant API
  participant Stripe
  App->>API: POST /charge
  API->>Stripe: create PaymentIntent
  Stripe-->>API: status
  API-->>App: recibo

Orçamento de novas tentativas

Cada cliente pode tentar novamente com espera exponencial, em que a espera após a tentativa $n$ é

w_n = \min(2^n \cdot 250\,\text{ms},\ 8\,\text{s})

Exemplo

export const charge = async (order: Order) => {
  const intent = await stripe.paymentIntents.create({ amount: order.total });
  return { id: intent.id, status: intent.status };
};

Questões em aberto

Vamos armazenar os últimos quatro dígitos?
Quais moedas serão lançadas primeiro?

Os campos de preenchimento, como seu nome e a data, são substituídos quando você abre o modelo no editor.