Padrão editorial

O problema do material técnico em português não é falta de texto. É texto que tenta ser tudo ao mesmo tempo: começa explicando o que é um container, no meio vira tutorial de Kubernetes, termina com uma lista de comandos. Quem quer aprender se perde; quem quer consultar não acha.

Este portal segue o Diátaxis, que separa conteúdo pela intenção do leitor. A regra é curta e não negociável:

Uma página tem exatamente um propósito. Quando outro propósito aparece, ele vira um link, não um parágrafo.

Os quatro tipos

Trilha (tutorial)

O leitor quer aprender. Ele não sabe o que não sabe, então você conduz.

Escrita na segunda pessoa, mostrando o caminho: “agora rode isto, você vai ver isto”.
Tudo funciona do começo ao fim. O leitor termina com algo rodando.
Pré-requisitos declarados no frontmatter, linkados.
Não explique alternativas no meio. “Também dá para fazer com X” quebra o fio.
Não seja exaustivo. Uma trilha ensina um caminho, não todos.

Guia prático (how-to)

O leitor tem um problema agora. Ele já sabe o suficiente; quer a solução.

Título começa com o problema, não com a ferramenta: “Resolver um Pod em CrashLoopBackOff”, não “Guia de kubectl describe”.
Passos numerados, cada um com um resultado verificável.
Assume competência. Não explique o que é um Pod.
Não ensine teoria. Linke para o conceito.

Referência

O leitor quer consultar. Ele já sabe o que procura.

Estrutura previsível, tabelas, densidade alta.
Feita para Ctrl+F, não para leitura sequencial.
Neutra e completa dentro do escopo declarado.
Não conte história, não dê opinião, não conduza.

Conceito (explicação)

O leitor quer entender. Normalmente longe do teclado.

Discute o porquê, o contexto histórico, os trade-offs.
Pode e deve ter opinião — desde que fundamentada e identificada como tal.
Não dê instruções passo a passo. Linke para o guia.

Regras que valem para tudo

Diga quando não usar. Toda recomendação técnica tem um limite. Uma página que só elogia uma ferramenta é propaganda, não documentação. É por isso que cada item do catálogo tem um campo explícito de “quando não usar”.

Mostre o custo, não só o benefício. Service mesh resolve problemas reais e custa operação real. Diga os dois.

Nada de “simplesmente” e “basta”. Se fosse simples, a pessoa não estaria lendo. Essas palavras não economizam explicação, só fazem quem não entendeu se sentir burro.

Código que roda. Todo bloco deve funcionar como está, ou declarar o que precisa ser substituído. Nada de <seu-valor-aqui> sem dizer onde consegui-lo.

Comente o porquê, não o quê. # incrementa i é ruído. # ordem inversa porque o provedor destrói dependentes primeiro é o que salva alguém.

Português direto. Termo em inglês consagrado no dia a dia fica em inglês — “deployment”, “pipeline”, “commit”. Traduzir para “implantação” numa conversa de time só atrapalha. Mas explique a primeira ocorrência de sigla.

Data de atualização importa. Conteúdo de infraestrutura envelhece rápido. O rodapé mostra a última alteração; se você mexeu numa página, ela ficou atual.

Metadados obrigatórios

---
title: Título da página
description: Uma frase que funcione como resultado de busca no Google.
tipo: trilha | guia | referencia | conceito | indice
dominio: kubernetes
nivel: iniciante | intermediario | avancado
minutos: 18
prerequisitos:
  - label: Fundamentos de Linux
    href: /trilhas/fundamentos/linux/
tags: [kubernetes, diagnostico]
rascunho: false
---

O tipo não é decoração: é o compromisso que a página assume com o leitor. Se você não consegue escolher um, a página está tentando fazer duas coisas — divida em duas.

O nivel, o minutos e os prerequisitos aparecem como faixa de metadados no topo. Eles existem para o leitor decidir antes de investir tempo.

Callouts têm significado fixo

Não invente callout novo e não use danger para chamar atenção — inflação de severidade faz o leitor ignorar todos.

Antes de abrir o pull request

A página tem um tipo, e o conteúdo respeita esse tipo.
O frontmatter está completo e rascunho reflete a realidade.
Há dominio e pelo menos duas tags que outras páginas já usam (npm run taxonomia reprova tag que só existe na sua página).
Todo link interno resolve (npm run build reprova link quebrado).
Os blocos de código foram executados por você.
Existe pelo menos uma menção honesta a limitação, custo ou “quando não usar”.
Nenhum segredo, IP interno ou nome de cliente ficou no exemplo.

Como contribuir na prática está em Como contribuir.