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.json.

Execute:

• npm run check:markdown para garantir que todos os arquivos sigam nossos padrões
• npm run fix:markdown para corrigir problemas de formatação relacionados ao Markdown

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.

Execute npm run check:spelling para verificar se todas as palavras estão escritas corretamente. Se o cspell indicar um erro de Unknown word, 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

As ferramentas do site normalizam os dicionários específicos de página (ou seja, as listas de palavras cSpell:ignore), removendo palavras duplicadas, excluindo palavras na lista global e ordenando as palavras. Para normalizar os dicionários específicos de página, execute npm run fix:dict.

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. Execute npm run fix:filenames para renomear automaticamente seus arquivos.