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.

Você também pode utilizar as seguintes extensões:

• Alertas do GitHub-flavored Markdown (GFM)
• Emojis. Para a lista completa de emojis disponíveis, consulte os Emojis da documentação do Hugo.

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.

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. Para uma lista de palavras específicas do site OpenTelemetry, consulte o arquivo .cspell.yml.

Se o cspell indicar um erro de Unknown word (palavra desconhecida), verifique se você escreveu essa palavra corretamente. Se sim, adicione essa palavra à seção cSpell:ignore no início do seu arquivo. Se essa seção não existir, você pode adicioná-la ao front matter de um arquivo Markdown:

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

Para qualquer outro arquivo, adicione cSpell:ignore <palavra> em uma linha de comentário apropriada para o contexto do arquivo. Para um arquivo YAML de entrada de registro, pode ser assim:

# cSpell:ignore <palavra>
title: TituloDoRegistro

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.