Guia de Estilo de Documentação

Este guia define como a documentação do EmDash é escrita. As contribuições são editadas para corresponder. Não é necessário memorizá-lo — revisores e editores ajudarão — mas segui-lo faz com que uma contribuição seja mesclada mais rapidamente.

A documentação existe para ajudar alguém a fazer algo e depois voltar ao seu projeto. Escreva para um leitor que está cansado, com pressa, lendo em um segundo idioma ou novo na 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 EmDash, não como o EmDash é construído. Detalhes de implementação pertencem aos documentos apenas quando mudam uma decisão que o leitor deve tomar (quando escolher um valor não padrão, uma ressalva que afeta seu projeto). Nunca substituem um exemplo de uso.

Para tópicos não relacionados ao EmDash — TypeScript, o Protocolo AT, fontes web, SQL — faça um 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 a resistir ativamente:

• Peso de autoria por recência. Uma decisão ser nova ou estar fresca na mente do escritor não é motivo para destacá-la. A coisa mais alterada raramente é a mais importante para um leitor. Ordene seções, itens de lista e manchetes 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 um documento.

• Saliência do construtor sobre saliência do leitor. Decisões de arquitetura e design internas que foram significativas para tomar são geralmente invisíveis e irrelevantes para usar. Indique 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 conhecer a linguagem do analisador. Se o mecanismo realmente ajuda alguém trabalhando no EmDash, pertence ao documento de internos, não a uma página voltada para o 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 CMS…”, “CMSs tradicionais forçam você a…”, “em muitos CMSs você declara X no código”). Descreva o que o EmDash faz, diretamente, e deixe-o se destacar por si só. A comparação só é permitida 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 e trade-offs concretos, não um espantalho que o leitor é convidado a não gostar.

• Definição por negação. Enquadrar uma capacidade como o trabalho que você não precisa fazer — “nenhuma migração para escrever”, “nenhuma reconstrução”, “sem tocar no código”, “nenhum serviço separado” — é um espantalho disfarçado: só funciona para um leitor que está carregando a alternativa que você inventou para eles. Indique 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 reconstrução, sem código”. A exceção é um comportamento concreto relevante para o leitor declarado positivamente: “o conteúdo é servido em tempo de execução, então as edições aparecem imediatamente” é um fato sobre o EmDash; “nenhuma reconstrução necessária” é o mesmo fato expresso como a dor ausente de outra pessoa — prefira o primeiro.

O teste para qualquer frase: um leitor tentando terminar sua tarefa estaria pior se fosse excluída? Se não, exclua-a. Se só faz sentido para um leitor comparando o EmDash com outra coisa, está no lugar errado ou deve ser cortada.

Sempre atual, não changelog

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

Voz e tom

Escreva frases neutras e factuais. Declare os fatos diretamente.

✅ Os plugins executam em um runtime isolado e só podem acessar as APIs que declaram.

❌ Os plugins vivem em uma pequena sandbox aconchegante onde nada de ruim pode acontecer!

• Não use nós, nos, nosso ou vamos. Você não está sentado com o leitor. Reformule para se dirigir diretamente ao leitor ou descrever o sistema.
• Nunca use eu. A documentação não é sobre o autor.
• Dirija-se ao leitor como você quando necessário, especialmente para sinalizar uma etapa 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 as etapas.
• Evite extravagância, mascotes e referências culturais. Eles 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. Quando estiver em dúvida, use um ponto final.

Títulos

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

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 etapas que devem ser seguidas em sequência. Use o componente <Steps> do Starlight para procedimentos.
• Quando os itens da lista crescem em vários parágrafos ou carregam vários termos de código, mude para seções <h3>.

Exemplos

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

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, então eles só precisam descobrir como. Também cria um padrão de preenchimento de lacunas 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 uma etapa numerada).

Outras regras:

• Use código real e funcional. Sem foo/bar. Mostre uma configuração realista, não todos os valores possíveis — o leitor terá apenas um.

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

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

• Use anotações do 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 os diffs mínimos e locais às linhas que mudam.

  O exemplo a seguir mostra uma única linha mudando:

  ```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 continue lendo caso contrário, e um link para o changelog.

Em seguida, liste cada mudança significativa como sua própria entrada:

### [Renamed/Changed/Removed/Deprecated]: <feature>

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

<Uma frase, tempo 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 valor padrão substitui o valor deles, isso é um “Changed: default value”, não um “Added: option”.

Uma mudança significativa é aquela 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”.

Especificações 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 uma classificação de quais recursos importam.

Plugins: sandboxed vs native

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

Localização

Não inclua alterações de messages.po em um PR de documentação. Um fluxo de trabalho extrai catálogos ao mesclar em main. Incluí-los cria churn e conflitos de mesclagem.

Recursos experimentais

Um recurso por trás de um sinalizador experimental, ou um formato de fio instável sob um RFC, pode mudar sem aviso. Mantenha sua documentação enxuta, sinalize-a com um <Aside> de cautela e aponte para o RFC ou discussão como a fonte da verdade. Não documente uma superfície instável em detalhes exaustivos.

Contas Atmosphere

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

Documentos são código

O site de documentação é um projeto Astro adjacente ao EmDash. As alterações de documentação passam pelo mesmo fluxo de pull request e revisão do código. Cada alteração de texto aguarda uma revisão; uma mudança de redação pode mudar o significado de uma frase ou precisar de edições correspondentes em outro lugar no site. Pequenas alterações revisadas e consistentes mantêm todo o site coerente.