Visão geral do estilo da documentação

• 1: Guia de Conteúdo da Documentação
• 2: Guia de Estilo da Documentação

1 - Guia de Conteúdo da Documentação

Esta página contém orientações para a documentação do Kubernetes.

Se você tiver dúvidas sobre o que é permitido, junte-se ao canal #sig-docs no Slack do Kubernetes e pergunte!

Você pode se registrar no Slack do Kubernetes através do endereço https://slack.k8s.io/.

Para informações sobre como criar novo conteúdo para a documentação do Kubernetes, siga o guia de estilo.

Visão geral

O código-fonte para o website do Kubernetes, incluindo a documentação, é armazenado no repositório kubernetes/website.

Localizada dentro da pasta kubernetes/website/content/<codigo-do-idioma>/docs, a maior parte da documentação do Kubernetes é específica para o projeto Kubernetes.

O que é permitido

A documentação do Kubernetes permite conteúdo de projetos de terceiros somente quando:

• O conteúdo documenta software que existe no projeto Kubernetes
• O conteúdo documenta software que está fora do projeto, mas é necessário para o funcionamento do Kubernetes
• O conteúdo é canônico no kubernetes.io, ou está vinculado a conteúdo canônico em outro local

Conteúdo de terceiros

A documentação do Kubernetes contém exemplos aplicados de projetos no projeto Kubernetes — projetos que existem nas organizações kubernetes e kubernetes-sigs do GitHub.

Links para conteúdo ativo no projeto Kubernetes sempre são permitidos.

O Kubernetes requer alguns conteúdos de terceiros para funcionar. Exemplos incluem agentes de execução de contêiner (containerd, CRI-O, Docker), políticas de rede (plugins CNI), controladores Ingress, e sistemas de log.

A documentação pode conter vínculos com software de código aberto de terceiros fora do projeto Kubernetes somente quando estes projetos são necessários para o funcionamento do Kubernetes.

Conteúdo duplicado

Sempre que possível, a documentação do Kubernetes utiliza links para fontes canônicas de documentação ao invés de hospedar conteúdo duplicado.

Conteúdo duplicado requer o dobro de esforço (ou mais!) para manter e fica obsoleto mais rapidamente.

Mais informações

Se você tem dúvidas sobre o conteúdo permitido, junte-se ao canal #sig-docs do Slack do Kubernetes e faça sua pergunta!

Próximos passos

• Leia o guia de estilo.

2 - Guia de Estilo da Documentação

Esta página fornece orientações de estilo para escrita da documentação do Kubernetes. Estas são orientações, não regras. Utilize seu melhor julgamento e sinta-se livre para propor alterações neste documento através de um pull request.

Para informações adicionais sobre como criar novo conteúdo para a documentação do Kubernetes, leia o Guia de Conteúdo da Documentação.

Mudanças no guia de estilo são feitas pelo SIG Docs como um grupo. Para propor uma alteração ou adição, inclua o tópico na agenda de uma das reuniões futuras do SIG Docs, e participe da reunião para fazer parte da discussão.

Língua

A documentação do Kubernetes foi traduzida para diversas línguas (veja READMEs das Localizações).

A forma para localização de documentação em uma língua diferente está descrita em localizando a documentação do Kubernetes.

Padrões de formatação da documentação

Utilize upper camel case para objetos da API

Quando você se referir especificamente a interações com um objeto da API, utilize UpperCamelCase, também conhecido como Pascal case. Você poderá encontrar formatação de maiúsculas e minúsculas diferente, como por exemplo "configMap", na referência da API. Ao escrever documentação geral, prefira a utilização de upper camel case, chamando o objeto de "ConfigMap".

Quando você estiver discutindo um objeto da API, utilize a formatação de maiúsculas e minúsculas no estilo de sentença.

Os exemplos a seguir focam no estilo de formatação de maiúsculas e minúsculas. Para mais informações sobre como formatar nomes de objetos da API, revise a orientação relacionada no manual de estilo de código.

Utilize chevrons para espaços reservados

Utilize chevrons (< e >) para espaços reservados. Comunique ao leitor o que o espaço reservado significa. Por exemplo:

kubectl describe pod <nome-do-pod> -n <namespace>

Se o nome do namespace do Pod for default, você pode omitir o paramêtro '-n'.

Grife elementos de interface de usuário

Utilize itálico para definir ou introduzir novos termos

Utilize estilo de código para nomes de arquivos, diretórios e caminhos

Utilize o padrão internacional para pontuação dentro de aspas

Formatação de código embutido

Utilize estilo de código para código embutido, comandos e objetos da API

Para código embutido em um documento HTML, utilize a tag <code>. Em um documento Markdown, utilize os símbolos de crase (`).

Utilize estilo de código para nomes de campos de objetos e namespaces

Utilize estilo de código para ferramentas de linha de comando e nomes de componentes do Kubernetes

Iniciando sentenças com o nome de uma ferramenta de linha de comando ou de um componente

Utilize uma descrição geral no lugar de um nome de componente

Utilize estilo normal para valores de campos do tipo texto ou inteiro

Para valores de campos do tipo texto ou inteiro, utilize o estilo normal sem aspas.

Referindo-se a recursos da API do Kubernetes

Esta seção discorre sobre como referenciar recursos da API na documentação.

Clarificação sobre "recurso"

O Kubernetes utiliza a palavra "recurso" para se referir a recursos da API, como pod, deployment, e demais objetos. Também utilizamos "recurso" para falar de requisições e limites de recursos de CPU e memória. Sempre se refira a recursos da API como "recursos da API" para evitar confusão com recursos de CPU e memória.

Quando utilizar a terminologia da API do Kubernetes

As diferentes terminologias da API do Kubernetes são:

• Tipo de recurso: o nome utilizado na URL da API (como pods, namespaces)
• Recurso: uma instância única de um tipo de recurso (como pod, secret)
• Objeto: um recurso que serve como um "registro de intenção". Um objeto é um estado desejado para uma parte específica do seu cluster, que a camada de gerenciamento do Kubernetes tenta manter.

Sempre utilize "recurso" ou "objeto" ao se referir a um recurso da API em documentação. Por exemplo, utilize "um objeto Secret" ao invés de apenas "um Secret".

Nomes de recursos da API

Sempre formate nomes de recursos da API utilizando UpperCamelCase, também conhecido como PascalCase, e formatação de código.

Para código embutido em um documento HTML, utilize a tag <code>. Em um documento Markdown, utilize o sinal de crase (`).

Não separe um nome de objeto da API em palavras individuais. Por exemplo, escreva PodTemplateList no lugar de Pod Template List.

Para mais informações sobre o PascalCase e formatação de código, por favor revise as orientações relacionadas nas seções Utilize UpperCamelCase para objetos da API e Utilize estilo de código para código embutido, comandos e objetos da API.

Para mais informações sobre as terminologias da API do Kubernetes, por favor revise a orientação relacionada sobre terminologia da API do Kubernetes.

Formatação de fragmentos de código

Não inclua o prompt de comando

Separe os comandos de seus resultados

Verifique que o Pod está rodando no seu nó escolhido:

kubectl get pods --output=wide

A saída é semelhante a:

NAME     READY     STATUS    RESTARTS   AGE    IP           NODE
nginx    1/1       Running   0          13s    10.200.0.4   worker0

Exemplos de versionamento do Kubernetes

Exemplos de código e de configuração que incluem informação da versão devem ser consistentes com o texto que os acompanha.

Se a informação é específica para uma versão, a versão do Kubernetes deve ser definida na seção prerequisites dos modelos de página de tarefa ou de tutorial. Assim que a página for salva, a seção prerequisitos é exibida com o título Antes de você começar.

Para especificar uma versão do Kubernetes para uma página de tarefa ou de tutorial, inclua a chave min-kubernetes-server-version na seção de front matter.

Se o exemplo de YAML for um arquivo avulso, procure e revise os tópicos que o incluem como uma referência. Verifique que quaisquer tópicos que estejam utilizando o YAML avulso têm a informação de versão apropriada definida. Se um arquivo avulso YAML não for referenciado em nenhum tópico, considere apagá-lo ao invés de atualizá-lo.

Por exemplo, se você estiver escrevendo um tutorial que é relevante para a versão 1.8 do Kubernetes, o front matter do seu arquivo Markdown deve ser semelhante ao demonstrado abaixo:

---
title: <seu título de tutorial aqui>
min-kubernetes-server-version: v1.8
---

Nos exemplos de código e configuração, não inclua comentários sobre versões alternativas. Tenha o cuidado de não incluir afirmações incorretas em comentários nos seus exemplos, como por exemplo:

apiVersion: v1 # versões mais antigas usam...
kind: Pod
...

Kubernetes.io word list

Uma lista de termos específicos do Kubernetes para serem utilizados de forma consistente em todo o website.

Shortcodes

Os shortcodes do Hugo auxiliam na criação de diferentes níveis de atrativos retóricos. Nossa documentação suporta três diferentes shortcodes nessa categoria: Nota {{< note >}}, Cuidado {{< caution >}}, e Aviso {{< warning >}}.

1. Circunde o texto com uma abertura e um fechamento de shortcode.

2. Utilize a sintaxe abaixo para aplicar um estilo:

   {{< note >}}
   Não há necessidade de incluir um prefixo; o _shortcode_ fornece um automaticamente (Nota:, Cuidado:, etc.).
   {{< /note >}}
   

   A saída é semelhante a:

   Nota: O prefixo é gerado automaticamente com a seleção do tipo da tag.

Nota

Utilize {{< note >}} para destacar uma dica ou uma informação que pode ser útil para o leitor.

Por exemplo:

{{< note >}}
Você _ainda_ pode utilizar Markdown dentro destas seções de destaque.
{{< /note >}}

The output is:

Você pode utilizar o shortcode {{< note >}} em uma lista:

1. Utilize o _shortcode_ `note` em uma lista

1. Um segundo item em uma lista com um shortcode note embutido

    {{< note >}}
    _Shortcodes_ Aviso, Cuidado e Nota, embutidos em listas, devem ser indentados
    com quatro espaços. Veja mais em [Problemas comuns com _shortcodes_](#common-shortcode-issues).
    {{< /note >}}

1. Um terceiro item em uma lista

1. Um quarto item em uma lista

A saída é:

1. Utilize o shortcode note em uma lista

2. Um segundo item em uma lista com um shortcode note embutido

   Nota: Shortcodes Aviso, Cuidado e Nota, quando embutidos em listas, devem ser indentados com quatro espaços. Veja mais em Problemas comuns com shortcodes.

3. Um terceiro item em uma lista

4. Um quarto item em uma lista

Cuidado

Utilize {{< caution >}} para chamar a atenção a informações importantes que podem evitar problemas.

Por exemplo:

{{< caution >}}
O estilo de chamada se aplica somente à linha diretamente acima da tag.
{{< /caution >}}

A saída é:

Aviso

Utilize {{< warning >}} para indicar perigo ou uma orientação que é crucial e deve ser seguida.

Por exemplo:

{{< warning >}}
Cuidado.
{{< /warning >}}

A saída é:

Problemas comuns com shortcodes

Listas ordenadas

Shortcodes interrompem listas numeradas a não ser que estejam indentados com quatro espaços antes da nota e da tag.

Por exemplo:

1. Preaqueça o forno a 350°F.

1. Prepare a massa e a coloque na assadeira.
   `{{< note >}}Unte a assadeira para melhores resultados.{{< /note >}}`

1. Asse por 20-25 minutos, ou até que ao testar com um palito este saia limpo.

A saída é:

1. Preaqueça o forno a 350°F.

2. Prepare a massa e a coloque na assadeira.

   Nota: Unte a assadeira para melhores resultados.

3. Asse por 20-25 minutos, ou até que ao testar com um palito este saia limpo.

Cláusulas include

Shortcodes dentro de cláusulas include fazem com que o build falhe. Você deve colocá-los no documento superior, antes e depois da cláusula include. Por exemplo:

{{< note >}}
{{< include "task-tutorial-prereqs.md" >}}
{{< /note >}}

Elementos Markdown

Quebras de linha

Utilize uma única linha em branco para dividir conteúdo a nível de bloco como por exemplo cabeçalhos, listas, imagens, blocos de código, entre outros. A exceção são cabeçalhos de segundo nível, onde duas linhas em branco devem ser utilizadas. Cabeçalhos de segundo nível seguem o primeiro nível (ou o título) sem nenhum texto ou parágrafo precedente. Um espaçamento de duas linhas em branco auxilia a melhor visualização geral da estrutura do conteúdo em um editor de texto.

Cabeçalhos e títulos

Pessoas que acessam esta documentação podem estar fazendo uso de um leitor de tela ou outro tipo de tecnologia auxiliar. Leitores de tela são dispositivos de saída linear que falam de um item por vez em uma página. Se uma grande quantidade de conteúdo existe em uma página, você pode utilizar cabeçalhos para dar à página uma estrutura interna. Uma boa estrutura de página auxilia todos os leitores a navegar facilmente ou filtrar tópicos de interesse.

Parágrafos

Links

Listas

Agrupe em listas itens relacionados que devem aparecer em uma ordem específica, ou para indicar uma correlação entre vários itens. Quando um leitor de tela encontra uma lista, independentemente de ser uma lista ordenada ou não-ordenada, o leitor de tela anunciará ao usuário que há um grupo de itens em lista. O usuário pode então utilizar as teclas de seta para navegar para cima e para baixo entre os vários itens da lista. Links para navegação no website também podem ser marcados como itens de lista, pois nada mais são do que um grupo de links relacionados.

• Finalize cada item em uma lista com um ponto final se um ou mais itens na lista forem sentenças completas. Para consistência, normalmente todos os itens da lista devem ser sentenças completas, ou nenhum dos itens deve ser.

  Nota: Listas ordenadas que são parte de uma sentença introdutória incompleta podem ser mantidos em letras minúsculas e pontuados como se cada item fosse uma parte da sentença introdutória.

• Utilize o número um (1.) para listas ordenadas.

• Utilize (+), (*) ou (-) para listas não-ordenadas.

• Deixe uma linha em branco após cada lista.

• Indente listas aninhadas com quatro espaços (por exemplo, ⋅⋅⋅⋅).

• Itens de lista podem consistir de múltiplos parágrafos. Cada parágrafo subsequente em uma lista deve estar indentado em quatro espaços ou um caractere de tabulação.

Tabelas

O propósito semântico de uma tabela de dados é apresentar dados tabulados. Usuários que não fazem uso de leitores de tela podem inspecionar a tabela de forma visual rapidamente, mas um leitor de tela irá ler o conteúdo linha a linha. Uma legenda de tabela é utilizada para criar um título descritivo para uma tabela de dados. Tecnologias auxiliares utilizam o elemento HTML caption para identificar o conteúdo da tabela para o usuário dentro da estrutura da página.

• Adicione legendas às suas tabelas utilizando os shortcodes do Hugo para tabelas.

Melhores práticas de conteúdo

Esta seção contém melhores práticas sugeridas para conteúdo claro, conciso e consistente.

Utilize o tempo presente

Exceção: utilize o tempo futuro ou pretérito quando necessário para comunicar o significado correto.

Utilize voz ativa

Exceção: utilize a voz passiva se a voz ativa resultar em uma construção estranha.

Utilize linguagem simples e direta

Utilize linguagem simples e direta. Evite utilizar frases ou expressões desnecessárias, como "por favor".

Dirija-se ao leitor utilizando "você"

Evite frases em Latim

Prefira termos em inglês no lugar de abreviações em Latim.

Exceção: utilize "etc." para et cetera.

Padrões a evitar

Evite utilizar "nós"

O uso de "nós" em uma sentença pode ser confuso, pois o leitor pode não saber se é parte do "nós" que você está descrevendo.

Evite jargões e expressões idiomáticas

Alguns leitores falam inglês como segunda língua. Evite jargões e expressões idiomáticas para auxiliar na compreensão.

Evite afirmações sobre o futuro

Evite fazer promessas ou dar dicas sobre o futuro. Se você precisa falar sobre uma funcionalidade em estado alfa, coloque o texto sob um cabeçalho que classifique a informação em estado alfa.

Uma exceção a esta regra é a documentação sobre descontinuações que serão convertidas em remoções em uma versão futura. Um exemplo deste tipo de documentação é o Guia de migração de APIs descontinuadas.

Evite afirmações que ficarão desatualizadas em breve

Evite palavras como "atualmente" e "novo". Uma funcionalidade que é nova hoje pode não ser mais considerada nova em alguns meses.

Evite palavras que assumem um nível específico de conhecimento

Evite palavras como "apenas", "simplesmente", "fácil", "facilmente" ou "simples". Estas palavras não agregam valor.

Próximos passos

• Aprenda sobre como escrever um novo tópico.
• Aprenda sobre como utilizar modelos de páginas.
• Aprenda sobre como criar um pull request.