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.

Padrõ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 o arquivo .markdownlint.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

Aplicamos formatação de arquivos usando o Prettier. Execute-o com npm run fix:format.

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.