Guia de estilo da documentação

Este guia define como a documentação do EmDash é escrita. As contribuições são editadas para se adequar a ele. Você não precisa memorizá-lo — revisores e editores ajudarão — mas segui-lo faz com que uma contribuição seja mesclada mais rápido.

A documentação existe para ajudar alguém a fazer algo e depois voltar ao seu projeto. Escreva para um leitor cansado, com pressa, lendo em um segundo idioma ou novo no stack. Sirva esse leitor acima de tudo.

Legibilidade

Prefira:

• Frases curtas e parágrafos curtos.
• Vocabulário simples em vez de jargão.
• Abreviações e acrônimos escritos por extenso na primeira vez.
• Títulos e listas para dividir passagens longas.
• Voz ativa.

Documente como construir com o EmDash, não como o EmDash é construído. Detalhes de implementação pertencem à documentação somente quando mudam uma decisão que o leitor precisa tomar (quando escolher um valor não padrão, uma ressalva que afeta seu projeto). Nunca substituem um exemplo de uso.

Para tópicos que não são do EmDash — TypeScript, o AT Protocol, fontes web, SQL — faça link para uma fonte confiável em vez de explicá-los. Documente o que alguém precisa saber para usar o recurso no EmDash.

O que enfatizar

A ênfase de uma página deve ser definida pelo que o leitor precisa para fazer sua tarefa, nunca pelo que foi interessante ou recente para as pessoas que construíram o EmDash. Três hábitos aos quais resistir ativamente:

• Peso da recência de autoria. Uma decisão ser nova, ou fresca na mente do escritor, não é motivo para destacá-la. O que mais mudou raramente é o mais importante para um leitor. Ordene seções, itens de lista e títulos pela frequência com que um leitor precisa deles, não por quando foram adicionados. Se você está documentando algo porque acabou de mudar, provavelmente está escrevendo uma entrada de changelog, não documentação.

• Relevância do construtor acima da relevância do leitor. Arquitetura interna e decisões de design que foram significativas de tomar são geralmente invisíveis e irrelevantes de usar. Declare a capacidade que o leitor obtém, não o mecanismo por trás dela. Um leitor definindo uma coleção não precisa saber onde o esquema é armazenado, assim como não precisa saber a linguagem do parser. Se o mecanismo genuinamente ajuda alguém trabalhando no EmDash, pertence à documentação interna, não a uma página voltada ao usuário.

• Autodefinição por espantalho. Não defina o EmDash por contraste com uma caricatura de outras ferramentas (“Ao contrário da maioria dos CMSs…”, “CMSs tradicionais forçam você a…”, “em muitos CMSs você declara X no código”). Descreva o que o EmDash faz, diretamente, e deixe que se sustente por si só. Comparação é permitida somente quando a comparação é a própria pergunta do leitor: na página de avaliação e nas páginas de orientação “Vindo de…”. Mesmo lá deve ser específica e justa — comportamentos concretos e trade-offs, não um espantalho que o leitor é convidado a rejeitar.

• Definição por negação. Enquadrar uma capacidade como o trabalho que você não precisa fazer — “sem migração para escrever”, “sem rebuild”, “sem tocar no código”, “sem serviço separado” — é um espantalho disfarçado: só funciona para um leitor que carrega a alternativa que você inventou para ele. Declare o que o leitor faz e o que acontece. “Adicione um campo no painel de administração; ele entra em vigor imediatamente” — não “adicione um campo sem migração, sem rebuild, sem código”. A exceção é um comportamento concreto, relevante para o leitor, declarado positivamente: “conteúdo é servido em runtime, então edições aparecem imediatamente” é um fato sobre o EmDash; “sem rebuilds necessários” é o mesmo fato formulado como a dor ausente de outra pessoa — prefira o primeiro.

O teste para qualquer frase: um leitor tentando terminar sua tarefa ficaria pior se ela fosse deletada? Se não, delete. Se só faz sentido para um leitor comparando o EmDash com outra coisa, está no lugar errado ou deve ser cortada.

Perene, não changelog

Páginas voltadas ao usuário descrevem como o EmDash funciona agora, para um leitor que não tem nenhuma versão anterior na cabeça. Sem “agora”, “não mais”, “costumava”, “em vez do antigo”, “isso mudou”. Diferenças de versão para versão existem apenas em um guia de atualização. Um conceito ter sido introduzido recentemente nunca é motivo para mencionar que é recente.

Voz e tom

Escreva frases neutras e factuais. Declare fatos diretamente.

✅ Plugins rodam em um runtime isolado e só podem acessar as APIs que declaram.

❌ Plugins vivem em uma caixinha de areia aconchegante onde nada de ruim pode acontecer!

• Não use nós, nosso ou vamos. Você não está sentado com o leitor. Reformule para se dirigir ao leitor diretamente ou descrever o sistema.
• Nunca use eu. Documentação não é sobre o autor.
• Dirija-se ao leitor como você quando necessário, especialmente para sinalizar um passo onde algo pode dar errado.
• Não narre nem conte uma história. Sem “agora que configuramos X, vamos para Y”. Comece uma seção com o objetivo, depois os passos.
• Evite extravagâncias, mascotes e referências culturais. Adicionam esforço de leitura e não se traduzem.
• Pontos de exclamação são raros. Use um apenas para algo genuinamente encorajador ou surpreendente. Na dúvida, use um ponto final.

Títulos

• O título da página é o <h1> (do frontmatter title). Seções começam em <h2>.
• Mantenha títulos curtos. <h2> e <h3> aparecem na barra lateral “Nesta página”; visualize e encurte qualquer coisa que quebre linha.
• Sem pontuação final, incluindo dois pontos.
• Formate código como <code> em títulos da mesma forma que no corpo do texto.

Listas

• Use uma lista com marcadores quando a ordem não importa, como um conjunto de opções ou propriedades.
• Use uma lista numerada para passos que devem ser seguidos em sequência. Use o componente <Steps> do Starlight para procedimentos.
• Quando itens de lista crescem para múltiplos parágrafos ou contêm vários termos de código, troque para seções <h3>.

Exemplos

• “por exemplo” por extenso introduz um único exemplo ou hipotético.
• “ex.” entre parênteses introduz uma lista não exaustiva (ex. GitHub, GitLab).
• Uma lista que cobre cada opção não é uma lista de exemplos — use parênteses sem “ex.” (as propriedades obrigatórias (src, alt)).

Capturas de tela

Use uma captura de tela apenas quando ela esclarece materialmente relações espaciais, um estado de interface ou a localização de controles. Mantenha instruções e outras informações essenciais no texto para que a página permaneça utilizável sem a imagem.

Toda captura de tela deve ser atual e capturada para o propósito específico da página. Forneça texto alternativo que descreva a tela e o estado relevantes. Registre o fixture, a rota, o viewport, o locale e o tema para que outro contribuidor possa reproduzir a captura.

Exemplos de código

Exemplos de código são tão importantes quanto a prosa ao redor deles.

Introduza cada bloco de código com uma frase completa e independente em sua própria linha, dizendo ao leitor o que o bloco faz. Não comece com um fragmento de frase terminando em dois pontos, um título nu ou “assim:”.

✅ O exemplo a seguir registra um plugin no array sandboxed:

❌ Adicione o plugin assim:

A introdução prepara o leitor para o que o código faz, para que ele só precise descobrir como. Ela também cria um padrão de preenchimento para um leitor fazendo algo ligeiramente diferente.

Dentro de um procedimento <Steps>, uma instrução imperativa direta é a introdução (“Adicione um tsconfig.json:” seguido do arquivo é aceitável em um passo numerado).

Outras regras:

• Use código real e funcional. Sem foo/bar. Mostre uma configuração realista, não todo valor possível — o leitor terá apenas uma.

• Adicione um nome de arquivo title= a qualquer bloco que represente um arquivo, para que o leitor saiba onde o código vai.

  ```ts title="src/plugin.ts"

• Use anotações Expressive Code, não cercas ```diff brutas, para mudanças antes/depois. Marque linhas alteradas com del={n} / ins={n} ou texto alterado com del="…" / ins="…". Mantenha diffs mínimos e locais às linhas que mudam.

  O exemplo a seguir mostra uma alteração de uma única linha:

  ```ts del={1} ins={2}
  import { definePlugin } from "emdash";
  import type { SandboxedPlugin } from "emdash/plugin";
  ```

• Visualize o código renderizado localmente antes de enviar. Um erro de digitação pode quebrar a exibição.

Guias de atualização e migração

Um guia que ajuda um leitor a mover um projeto existente para uma nova versão segue uma estrutura fixa. As seções “O que devo fazer?” são a parte que os leitores mais valorizam — não economize nelas.

Abra com: como atualizar, uma nota de que as coisas podem “simplesmente funcionar” mas para continuar lendo se não, e um link para o changelog.

Então liste cada mudança que quebra compatibilidade como sua própria entrada:

### [Renomeado/Alterado/Removido/Depreciado]: <recurso>

Em versões anteriores, <uma frase, passado, o que fazia>.

<Uma frase, presente, como funciona agora>.

#### O que devo fazer?

<Ações imperativas: Atualizar… / Substituir… / Remover…, com um diff mínimo.>

Escolha o verbo pela forma como o leitor sente o impacto. Se um novo padrão substitui o valor dele, isso é um “Alterado: valor padrão”, não um “Adicionado: opção”.

Uma mudança que quebra compatibilidade é uma que requer uma alteração no projeto do leitor ou ele para de funcionar. Dê a ação, não apenas o fato. Não “a versão mínima do Node.js agora é X” mas “verifique sua versão do Node.js com o seguinte comando e atualize se estiver abaixo de X”.

Especificidades do EmDash

Convenções para situações recorrentes, ordenadas pela frequência com que um contribuidor as encontra. Esta é uma lista de convenções, não um ranking de quais recursos importam mais.

Plugins: sandboxed vs nativos

Plugins sandboxed e nativos são formatos diferentes com formas de autoria diferentes. Uma mudança em um raramente afeta o outro. Declare qual formato uma página ou exemplo trata. Ao editar uma página de plugin sandboxed, não altere exemplos de plugins nativos, e vice-versa.

Localização

Não inclua mudanças de messages.po em um PR de documentação. Um workflow extrai catálogos ao mesclar em main. Incluí-los cria churn e conflitos de merge.

Recursos experimentais

Um recurso atrás de uma flag experimental, ou um formato wire instável sob um RFC, pode mudar sem aviso. Mantenha sua documentação enxuta, sinalize com um <Aside> de cautela e aponte para o RFC ou discussão como fonte da verdade. Não documente uma superfície instável em detalhe exaustivo.

Contas Atmosphere

Quando a identidade portátil, de propriedade do usuário, por trás do Bluesky e da rede mais ampla do AT Protocol surgir, chame-a de conta Atmosphere e use esse termo consistentemente. Faça link da primeira menção para o guia de login Atmosphere ou atmosphereaccount.com. did:plc:… e handles são seus identificadores concretos; use-os onde um valor literal for necessário.

Documentação é código

O site de documentação é um projeto Astro adjacente ao EmDash. Mudanças na documentação passam pelo mesmo fluxo de pull request e revisão que o código. Toda mudança de texto aguarda uma revisão; uma mudança de redação pode alterar o significado de uma frase ou precisar de edições correspondentes em outro lugar do site. Mudanças pequenas, revisadas e consistentes mantêm todo o site coerente.