jonshaw199/decision-doc-quality

Qualidade de Documentos de Decisão / Opções

Use estas regras para todo documento de decisão técnica, spike ou opções que proponha escolhas e uma recomendação. O leitor é um colega de equipe ocupado, sem contexto algum; o documento deve ser escaneável, claro e demonstrável.

Público: assuma contexto zero

• Assuma que o leitor não conhece nenhum conhecimento tácito da equipe. Explique ou linke cada termo, acrônimo, nome de serviço, ferramenta e padrão em uso (ex: CDC, Debezium, Kafka, SNS, SQS, outbox, replicação lógica, Temporal). "Ninguém sabe o que nada disso significa."
• Explique o que uma coisa é e faz em palavras simples antes de usá-la como premissa. Prefira uma frase simples + um link em vez de jargão isolado.
• Não adicione uma seção separada de glossário a menos que solicitado; linke os termos inline.

Estilo de escrita

• Vá direto ao ponto (BLUF). Apresente a conclusão principal primeiro, depois os detalhes.
• Seja curto. Frases únicas vencem parágrafos. Se uma seção parecer um muro de texto, corte-a. Ninguém lê documentos longos.
• Linguagem clara. Sem exageros de IA, sem preenchimento que "soa bem", sem narrar a evolução do próprio documento, sem defender seu raciocínio dentro do texto (ex: nunca "evidência direta, não teoria").
• Sem travessões em lugar nenhum. Sem ÊNFASE EM CAIXA ALTA (use negrito). Sem numeração decorativa ou separadores middot que pareçam gerados por máquina.
• "Nós" para o trabalho que a equipe faria; "Eu" para a opinião/inclinação do autor. Mantenha-os distintos.

Estrutura

• Recomendação / TL;DR no início. Algumas linhas: a inclinação, os principais motivos (como marcadores), enquadrado como uma visão inicial de um documento vivo que mudará após contribuições da equipe. Torne a indiferença e a flexibilidade explícitas quando forem reais; ainda assim, declare uma preferência e o porquê.
• Um bloco colapsável (toggle) por opção. A linha recolhida mostra um rótulo curto + uma descrição em inglês simples de uma linha. Dentro: um diagrama simples, Como funciona, o que é reutilizado (com links de prova), o que é novo, escala/trade-off e um pequeno esboço de código ou configuração. Mantenha a superfície escaneável.
• Mantenha seções paralelas consistentes (consistência não é opcional). Opções/ferramentas/candidatos são irmãos, então cada UM DEVE seguir o mesmo modelo: os mesmos subtítulos na mesma ordem, a mesma presença de diagrama / mídia / esboço de código, a mesma profundidade. Corrija o modelo uma vez (a partir da seção mais forte) e aplique-o a todos; ao adicionar ou editar uma seção, realinhe as outras. Nunca deixe cada seção derivar para sua própria forma; estrutura divergente parece descuidada e derrota todo o propósito (comparação lado a lado fácil). Este é um modo de falha recorrente: verifique antes de compartilhar.
• Agrupe opções por um único eixo limpo (ex: quando algo acontece, ou como). Nunca misture dois eixos em um único agrupamento ou crie categorias falsas que se sobreponham. Se algo é um detalhe de implementação de outra opção (um executor, um local de destino), incorpore-o, não o liste como irmão.
• Ilustre o núcleo compartilhado/mais difícil, não apenas as opções, com seu próprio esboço (cubra o ciclo de vida completo, ex: criar/atualizar e excluir).
• Diagramas (mermaid) para ilustração; mantenha-os precisos (não desenhe uma tabela como um banco de dados separado, etc.).
• Termine com um convite para feedback ("Outras ideias?"); nunca termine abruptamente.
• Mantenha os metadados mínimos, apenas o que for desejado (geralmente apenas o link do ticket). Descarte status/linhas padronizadas com as quais o autor não se importa.

Abrangência das opções

• Liste as opções de forma exaustiva, não apenas as duas ou três habituais. Problemas reais têm muitas; inclua também as claramente ruins para que todo o campo seja visível (identifique-as como fracas/linha de base).
• Sempre reconheça a linha de base "não fazer nada" e declare sua consequência.
• Pesquise fontes reais (documentação, Stack Overflow, Reddit, referências de fornecedores/padrões) para encontrar opções e a terminologia correta. A Wikipédia sozinha é o padrão preguiçoso; encontre a fonte primária relevante.
• Nomeie os padrões de design estabelecidos corretamente e linke-os; não aplique erroneamente o nome de um padrão. Verifique se o padrão realmente se encaixa antes de citá-lo.

Evidência (a regra central)

• Toda afirmação sobre o que o sistema já possui é respaldada por um hyperlink para a prova (arquivo fonte + linha, configuração de infraestrutura, ticket). Sem suposições, sem rodeios.
• Se uma afirmação não puder ser comprovada com um link, marque-a como não verificada, em vez de apresentá-la como fato.
• Verifique lendo o arquivo/infraestrutura real você mesmo. Não afirme a descoberta de um subagente como fato sem lê-la; distinga "eu li" de "um agente relatou", e declare a confiança quando for relevante.
• Nunca mude de opinião silenciosamente. Quando uma verificação alterar uma afirmação anterior, diga o que estava errado e por que, e corrija.
• Desafie a premissa e suas próprias conclusões quando pressionado; re-verifique em vez de defender.
• Hiperlinke todo identificador, nome de arquivo, ticket, PR e referência; nunca deixe um ID solto para o leitor caçar.

Conteúdo do documento de opções

• Separe o núcleo compartilhado difícil (o trabalho necessário independentemente da opção) dos wrappers/mecanismos ao redor dele, e diga qual é o verdadeiro esforço e risco.
• Apresente prós e contras, fundamentados. Não exagere ("a maior parte do trabalho e quase todo o risco" → suavize para o que é preciso).
• Observe o que cada opção reutiliza (que já existe) vs. o que é novo.

Processo

• Faça edições mínimas e direcionadas. Não reescreva o documento inteiro para uma pequena alteração.
• Para redação sensível, mostre o rascunho no chat e itere antes de aplicar.
• Para uma mensagem de revisão/Slack de acompanhamento: mantenha-a incrivelmente curta e genuinamente convidativa (as pessoas estão ocupadas e não vão querer lê-la); não afirme que é urgente ou não urgente a menos que solicitado; prepare os revisores com o enquadramento mais útil.

Verificação final

Antes de compartilhar um documento, verifique:

• O ponto principal / recomendação está no início e é curto.
• Toda afirmação "o que temos" tem um link de prova; afirmações não verificadas estão identificadas.
• Jargão é explicado ou linkado; um leitor sem contexto consegue acompanhar.
• As opções estão agrupadas em um único eixo limpo, cada uma colapsável com um resumo de uma linha em linguagem simples.
• Sem travessões, sem ênfase em CAIXA ALTA, sem auto-narração, sem exageros de IA.
• "Nós" vs "Eu" usado corretamente; inclinação declarada, mas flexibilidade clara.
• O documento convida feedback e não termina abruptamente.