Manual de estilo da documentação

Ainda não possuímos um manual de estilo oficial, porém, a atual aparência da documentação do OpenTelemetry é influenciada pelos seguintes manuais de estilo:

• Google Developer Documentation Style Guide
• Kubernetes Style Guide

As seções a seguir contêm orientações específicas para o projeto OpenTelemetry.

Lista de palavras do OpenTelemetry.io

Uma lista de termos e palavras específicas do OpenTelemetry que devem ser usadas de forma consistente em todo o site:

• OpenTelemetry e OTel
• Collector
• OTEP
• OpAMP

Para uma lista completa de termos do OpenTelemetry e suas definições, consulte o Glossário.

Certifique-se de que nomes próprios, como outros projetos da CNCF ou ferramentas de terceiros, sejam escritos corretamente e utilizem a capitalização original. Por exemplo, escreva “PostgreSQL” em vez de “postgre”. Para uma lista completa, verifique o arquivo .textlintrc.yml.

Markdown

As páginas do site são escritas na sintaxe Markdown suportada pelo renderizador Markdown Goldmark. Para a lista completa de extensões Markdown suportadas, consulte Goldmark.

Também é possível utilizar as seguintes extensões Markdown:

• Alertas
• Emojis: para a lista completa de emojis disponíveis, consulte os Emojis da documentação do Hugo.

Alertas

É possível escrever alertas utilizando a seguinte sintaxe estendida:

• Alertas do GitHub-flavored Markdown (GFM)
• Sintaxe de Obsidian callout para títulos de alerta personalizados

Segue um exemplo de cada:

> [!TIP]
>
> Ao escrever novo conteúdo, prefira, em geral, esta sintaxe de alerta em
> bloco de citação em vez do
> [shortcode de alerta](https://www.docsy.dev/docs/content/shortcodes/#alert)
> do Docsy.

> [!WARNING] :warning: Linha em branco obrigatória!
>
> Este site utiliza o formatador [Prettier], que exige uma linha vazia
> separando a tag/título do alerta do corpo do alerta.

Esses exemplos são renderizados como:

Para mais detalhes sobre a sintaxe de alertas em bloco de citação, consulte Alertas na documentação do Docsy.

Referências de links

Ao utilizar links de referência em Markdown, prefira a forma recolhida (collapsed) [texto][] em vez da forma abreviada (shortcut) [texto]. Embora ambas sejam válidas em CommonMark, a forma abreviada não é reconhecida de maneira consistente por todas as ferramentas de Markdown. Em particular, ao escrever [exemplo] e esquecer a definição, o linter markdownlint não emite nenhum aviso¹ – o texto é renderizado silenciosamente como o literal [exemplo] em vez de um link. Com a forma recolhida [exemplo][], o linter detecta a definição ausente imediatamente.

Isso é aplicado pela regra personalizada no-shortcut-ref-link. Execute npm run fix:markdown para converter referências abreviadas automaticamente.

Verificações de Markdown

Para garantir padrões e consistência nos arquivos Markdown, todos os arquivos devem seguir certas regras, aplicadas pelo markdownlint. Para uma lista completa, verifique os arquivos .markdownlint.yaml e .markdownlint-cli2.yaml.

Quando houver exceções legítimas a uma regra, utilize a diretiva markdownlint-disable para suprimir os avisos da regra. Para mais detalhes, consulte a documentação do markdownlint.

Também aplicamos o padrão file format ao Markdown, que remove espaços em branco no final das linhas. Isso exclui a line break syntax com dois ou mais espaços. Para forçar a quebra de linha, use <br> em vez disso ou reformate seu texto.

Verificação ortográfica

Use CSpell para garantir que todo o texto esteja escrito corretamente.

Se o cspell reportar uma Unknown word (palavra desconhecida), verifique se a palavra foi escrita corretamente. Se sim, adicione a palavra a um destes locais:

• Uma lista cSpell:ignore local da página, no front matter da página. Para mais detalhes, veja abaixo.
• O arquivo de lista de palavras específico do seu idioma
• A lista de palavras geral all-words.txt

Lista cSpell:ignore local da página

Se a palavra desconhecida aparecer em apenas uma ou poucas páginas, adicione-a a uma lista cSpell:ignore local no front matter da página:

---
title: TituloDaPagina
cSpell:ignore: <palavra>
---

Para arquivos que não sejam Markdown, adicione cSpell:ignore <palavra> em uma linha de comentário apropriada para o arquivo. Por exemplo, em um arquivo YAML de entrada de registro, pode ser assim:

# cSpell:ignore <palavra>
title: TituloDoRegistro

Arquivos de lista de palavras

Se a palavra desconhecida aparecer em várias páginas ou for um termo técnico, adicione-a ao arquivo de lista de palavras específico do seu idioma. Os arquivos de lista de palavras ficam no diretório .cspell/.

Se a palavra estiver escrita corretamente em todos os idiomas, como opamp, adicione-a ao arquivo all-words.txt.

Formato de arquivo

Nós utilizamos o Prettier para aplicar a formatação de arquivos. Execute-o usando:

• npm run fix:format para formatar todos os arquivos
• npm run fix:format:diff para formatar apenas os arquivos que foram alterados desde o último commit
• npm run fix:format:staged para formatar apenas os arquivos que estão preparados para o próximo commit

Nomes de arquivos

Todos os nomes de arquivos devem estar em kebab case.

Corrigindo problemas de validação

Para aprender como corrigir problemas de validação, consulte Verificações de pull request.