Contribuidores da documentação do Kubernetes podem:
Melhorar o conteúdo existente
Criar novo conteúdo
Traduzir a documentação
Gerenciar e publicar a documentação como parte do ciclo de lançamento do Kubernetes
Começando
Qualquer pessoa pode abrir uma issue sobre a documentação, ou contribuir com uma mudança por meio de um pull request (PR) para o repositório do Github kubernetes/website.
É recomendável que você se sinta confortável com git e
Github para trabalhar efetivamente na comunidade Kubernetes.
Algumas tarefas requerem mais confiança e mais acessos na organização do Kubernetes.
Veja Participando no SIG Docs para mais detalhes
sobre funções e permissões.
O SIG Docs é um grupo de contribuidores que publica e mantém
a documentação e o site do Kubernetes. Se envolver com o SIG Docs é uma ótima forma de contribuidores Kubernetes (pessoas desenvolvedoras de features ou outros) terem um grande impacto dentro do projeto Kubernetes.
A comunicação do SIG Docs é feita de diferentes formas:
Para contribuir com a comunidade Kubernetes por meio de fóruns on-line, como Twitter ou Stack Overflow, ou aprender sobre encontros locais e eventos do Kubernetes, visite a area de comunidade Kubernetes.
Para contribuir com o desenvolvimento de novas funcionalidades, leia o cheatsheet do colaborador para começar.
Leia o cheatsheet de contribuidor para saber mais sobre as funcionalidades de desenvolvimento do Kubernetes.
Qualquer pessoa pode revisar um pull request da documentação.
Visite a seção pull requests no repositório do site Kubernetes para ver os pull requests abertos.
Revisar os pull requests da documentação é uma ótima maneira de se apresentar à comunidade Kubernetes.
Isso ajuda você a aprender a base de código e construir a confiança com outros colaboradores.
Comente os aspectos positivos dos PRs, bem como mudanças.
Seja empático e cuidadoso, observe como sua avaliação pode ser recebida.
Assuma boas intenções e faça perguntas esclarecedoras.
Colaboradores experientes, considere trabalhar em par com os novos colaboradores cujo trabalho requer grandes mudanças.
Processo de revisão
Em geral, revise os pull requests de conteúdo e estilo em inglês.
A Figura 1 descreve as etapas para o processo de revisão.
Seguem os detalhes para cada etapa.
Filtre os PRs abertos usando um ou todos os labels seguintes:
cncf-cla: yes (Recomendado): PRs enviados por colaboradores que não assinaram o CLA não podem ser feito o merge. Consulte Assinar o CLA para obter mais informações.
language/pt (Recomendado): Filtro para PRs em português.
size/<size>: Filtro para PRs com um determinado tamanho. Se você é novo, comece com PRs menores.
Além disso, certifique-se que o PR não esteja marcado como work in progress. Os PRs que usam o labelwork in progress ainda não estão prontos para revisão.
Depois de selecionar um PR para revisar, entenda a mudança:
Lendo a descrição do PR para entender as alterações feitas e ler quaisquer issues vinculadas
Lendo quaisquer comentários de outros revisores
Clicando na aba Files changed para ver os arquivos e linhas alteradas
Pré-visualizar as alterações ambiente de pré-visualização do Netlify, rolando até a seção PR's build check na parte inferior da aba Conversation.
Aqui está uma captura da tela (isso mostra a área de trabalho do site GitHub; se você estiver revisando em um tablet ou smartphone, a interface web do usuário GitHub será um pouco diferente):
Para abrir a visualização, selecione o link Details da linha deploy/netlify na lista de verificações.
Vá para a aba Files changed para iniciar sua revisão.
Clique no símbolo + ao lado da linha que você deseja comentar.
Preencha com todos os comentários que você tenha sobre a linha e clique em Add single comment (se você tiver apenas um comentário para fazer) ou Start a review (se você tiver vários comentários para fazer)
Quando terminar, clique em Review changes na parte superior da página.
Aqui, você pode adicionar um resumo da sua revisão (e deixar alguns comentários positivos para o colaborador!).
Por favor, sempre use o "Comentário"
Evite clicar no botão "Request changes" ao concluir sua revisão.
Se você quiser bloquear o merge do PR antes que outras alterações sejam realizadas, você pode deixar um comentário "/hold".
Mencione por que você está definindo o bloqueio e, opcionalmente, especifique as condições sob as quais o bloqueio pode ser removido por você ou por outros revisores.
Evite clicar no botão "Approve" ao concluir sua revisão.
Deixar um comentário "/approve" é recomendado na maioria dos casos.
Checklist para revisão
Ao revisar, use como ponto de partida o seguinte.
Linguagem e gramática
Existe algum erro óbvio na linguagem ou gramática? Existe uma maneira melhor de expressar algo?
Concentre-se na linguagem e na gramática nas partes que o autor está mudando na página.
A menos que o autor esteja claramente com o objetivo de atualizar a página inteira, ele não tem obrigação de corrigir todos os problemas na página.
Quando um PR atualiza uma página existente, você deve se concentrar em revisar as partes que estão sendo atualizadas na página.
Esse conteúdo alterado deve ser revisado quanto à correção técnica e editorial.
Se você encontrar erros na página que não se relacionam diretamente com o que o autor do PR está tentando resolver, ele deve ser tratado em uma issue separada (primeiro, verifique se não existe uma issue existente sobre isso).
Cuidado com os pull requests que movem conteúdo.
Se um autor renomear uma página ou combinar duas páginas, nós (Kubernetes SIG Docs) geralmente evitamos pedir a esse autor que corrija todas as questões gramaticais ou ortográficas que poderíamos identificar dentro desse conteúdo movido.
Existem palavras complicadas ou arcaicas que podem ser substituídas por uma palavra mais simples?
Existem palavras, termos ou frases em uso que podem ser substituídos por uma alternativa não discriminatória?
A escolha da palavra e sua capitalização seguem o guia de estilo?
Existem frases longas que podem ser mais curtas ou menos complexas?
Existem parágrafos longos que podem funcionar melhor como uma lista ou tabela?
Conteúdo
Existe conteúdo semelhante em outro lugar no site Kubernetes?
O conteúdo está excessivamente vinculado a uma documentação externa, de um fornecedor individual ou de um código não aberto?
Website
Esse PR alterou ou removeu um título da página, slug/alias ou link?
Em caso afirmativo, existem links quebrados como resultado deste PR?
Existe outra opção, como alterar o título da página sem alterar o slug?
O PR apresenta uma nova página? Caso afirmativo:
A página está usando corretamente o tipo de conteúdo e os códigos relacionados ao Hugo?
A página aparece corretamente na navegação da seção (ou em geral)?
As alterações aparecem na visualização do Netlify? Esteja particularmente atento a listas, blocos de código, tabelas, notas e imagens.
Outro
Cuidado com as edições triviais;
se você observar uma mudança que entender ser uma edição trivial, por favor, marque essa política (ainda não há problema em aceitar a alteração se for genuinamente uma melhoria).
Incentive os autores que estão fazendo correções de espaço em branco a fazê-lo no primeiro commit de seu PR e, em seguida, adicione outras alterações além disso.
Isso facilita as revisões e o merge.
Cuidado especialmente com uma mudança trivial que aconteça em um único commit, juntamente com uma grande quantidade de limpeza dos espaços em branco (e se você observar isso, incentive o autor a corrigi-lo).
Como revisor, se você identificar pequenos problemas com um PR que não são essenciais para o significado, como erros de digitação ou espaços em branco incorretos, sinalize seus comentários com nit:.
Isso permite que o autor saiba que esta parte do seu feedback não é uma crítica.
Se você estiver considerando um pull request e todo o feedback restante estiver marcado como um nit, você pode realizar o merge do PR de qualquer maneira.
Nesse caso, muitas vezes é útil abrir uma issue sobre os nits restantes.
Considere se você é capaz de atender aos requisitos para marcar esse nova issue como uma Good First Issue; se você puder, esses são uma boa fonte.
2 - Visão geral do estilo da documentação
Os tópicos desta seção fornecem orientações gerais para o estilo de escrita,
formatação e organização do conteúdo, e como utilizar as customizações do Hugo
específicas para a documentação do Kubernetes.
2.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.
Nota: Se você é um mantenedor e precisa de auxílio para hospedar sua própria
documentação, solicite ajuda no canal
#sig-docs do Slack do Kubernetes.
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!
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.
Nota: A documentação do Kubernetes utiliza o
processador de markdown Goldmark com alguns
ajustes, bem como alguns shortcodes do Hugo
para suportar entradas de glossário, tabulações e representação do estado das
funcionalidades.
Língua
A documentação do Kubernetes foi traduzida para diversas línguas (veja
READMEs das Localizações).
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".
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.
Faça e não faça - Utilizando _Pascal case_ para objetos da API
Faça
Não faça
O recurso HorizontalPodAutoscaler é responsável por ...
O Horizontal pod autoscaler é responsável por ...
Um objeto PodList é uma lista de Pods.
Um objeto Pod List é uma lista de Pods.
O objeto Volume contém um campo hostPath.
O objeto volume contém um campo hostPath.
Cada objeto ConfigMap é parte de um namespace.
Cada objeto configMap é parte de um namespace.
Para o gerenciamento de dados confidenciais, considere utilizar a API de Secrets.
Para o gerenciamento de dados confidenciais, considere utilizar a API de segredos.
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
Faça e não faça - grife elementos da interface do usuário
Faça
Não faça
Clique em Fork.
Clique em "Fork".
Selecione Other.
Selecione "Other".
Utilize itálico para definir ou introduzir novos termos
Faça e não faça - Utilize itálico para novos termos
Faça
Não faça
Um cluster é um conjunto de nós ...
Um "cluster" é um conjunto de nós ...
Estes componentes formam a camada de gerenciamento.
Estes componentes formam a camada de gerenciamento.
Utilize estilo de código para nomes de arquivos, diretórios e caminhos
Faça e não faça - Utilize estilo de código para nomes de arquivos, diretórios e caminhos
Faça
Não faça
Abra o arquivo envars.yaml.
Abra o arquivo envars.yaml.
Navegue até o diretório /docs/tutorials.
Navegue até o diretório /docs/tutorials.
Abra o arquivo /_data/concepts.yaml.
Abra o arquivo /_data/concepts.yaml.
Utilize o padrão internacional para pontuação dentro de aspas
Faça e não faça - Utilize o padrão internacional para pontuação dentro de aspas
Faça
Não faça
eventos são registrados com um "estágio associado".
eventos são registrados com um "estágio associado."
A cópia é chamada de "fork".
A cópia é chamada de "fork."
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 (`).
Faça e não faça - Utilize estilo de código para código embutido, comandos e objetos da API
Faça
Não faça
O comando kubectl run cria um Pod.
O comando "kubectl run" cria um pod.
O kubelet em cada nó obtém um Lease ...
O kubelet em cada nó obtem um lease...
Um PersistentVolume representa armazenamento durável ...
Um PersistentVolume representa armazenamento durável ...
Para gerenciamento declarativo, utilize kubectl apply.
Para gerenciamento declarativo, utilize "kubectl apply".
Circunde exemplos de código com três símbolos de crase. (```)
Circunde exemplos de código com quaisquer outras sintaxes.
Utilize um único símbolo de crase para circundar código embutido. Por exemplo, var example = true.
Utilize dois asteriscos (**) ou um subtraço (_) para circundar código embutido. Por exemplo, var example = true.
Utilize três símbolos de crase antes e depois de um bloco de código de múltiplas linhas para blocos de código cercados.
Utilize blocos de código de múltiplas linhas para criar diagramas, fluxogramas, ou outras ilustrações.
Utilize nomes de variáveis significativos que possuem um contexto.
Utilize nomes de variáveis como 'foo', 'bar' e 'baz' que não são significativos e não possuem contexto.
Remova espaços em branco em final de linha no código.
Adicione espaços em branco no código, onde estes são importantes, pois os leitores de tela lerão os espaços em branco também.
Nota: Este website suporta destaque de sintaxe para exemplos de código, mas a especificação
de uma linguagem é opcional. Destaque de sintaxe nos blocos de código devem estar
de acordo com as orientações de contraste.
Utilize estilo de código para nomes de campos de objetos e namespaces
Faça e não faça - Utilize estilo de código para nomes de campos de objetos
Faça
Não faça
Especifique o valor do campo replicas no arquivo de configuração.
Especifique o valor do campo "replicas" no arquivo de configuração.
O valor do campo exec é um objeto do tipo ExecAction.
O valor do campo "exec" é um objeto do tipo ExecAction.
Execute o processo como um DaemonSet no namespace kube-system.
Execute o processo como um DaemonSet no namespace kube-system.
Utilize estilo de código para ferramentas de linha de comando e nomes de componentes do Kubernetes
Faça e não faça - Utilize estilo de código para ferramentas de linha de comando e componentes do Kubernetes
Faça
Não faça
O kubelet preserva a estabilidade do nó.
O kubelet preserva a estabilidade do nó.
O kubectl gerencia a busca e a autenticação com o servidor da API.
O kubectl gerencia a busca e a autenticação com o servidor da API.
Execute o processo com o certificado, kube-apiserver --client-ca-file=FILENAME.
Execute o processo com o certificado, kube-apiserver --client-ca-file=FILENAME.
Iniciando sentenças com o nome de uma ferramenta de linha de comando ou de um componente
Faça e não faça - Iniciando sentenças com o nome de uma ferramenta de linha de comando ou de um componente
Faça
Não faça
A ferramenta kubeadm inicializa e provisiona máquinas em um cluster.
kubeadm inicializa e provisiona ferramentas em um cluster.
O kube-scheduler é o escalonador padrão para o Kubernetes.
kube-scheduler é o escalonador padrão para o Kubernetes.
Utilize uma descrição geral no lugar de um nome de componente
Faça e não faça - Utilize uma descrição geral no lugar de um nome de componente
Faça
Não faça
O servidor da API do Kubernetes oferece uma especificação OpenAPI.
O apiserver oferece uma especificação OpenAPI.
APIs agregadas são servidores de API subordinados.
APIs agregadas são APIServers subordinados.
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.
Faça e não faça - Utilize o estilo normal para valores de campo do tipo texto ou inteiro
Faça
Não faça
Especifique o valor Always para o campo imagePullPolicy.
Especifique o valor "Always" para o campo imagePullPolicy.
Especifique o valor nginx:1.16 para o campo image.
Especifique o valor nginx:1.16 para o campo image.
Especifique o valor 2 para o campo replicas.
Especifique o valor 2 para o campo replicas.
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 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
Faça e não faça - Não inclua o prompt de comando
Faça
Não faça
kubectl get pods
$ kubectl get pods
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.
Lista de palavras do Kubernetes.io
Term
Usage
Kubernetes
Kubernetes deve sempre ser escrito com K maiúsculo.
Docker
Docker deve sempre ser escrito com D maiúsculo.
SIG Docs
Escreva SIG Docs ao invés de SIG-DOCS ou outras variantes.
On-premises
Escreva On-premises ou On-prem ao invés de On-premise ou outras variantes.
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 >}}.
Circunde o texto com uma abertura e um fechamento de shortcode.
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:
Nota: Você ainda pode utilizar Markdown dentro destas seções de destaque.
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 é:
Utilize o shortcodenote em uma lista
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.
Um terceiro item em uma lista
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 é:
Cuidado: O estilo de chamada se aplica somente à linha diretamente acima da tag.
Aviso
Utilize {{< warning >}} para indicar perigo ou uma orientação que é crucial
e deve ser seguida.
Por exemplo:
{{< warning >}}
Cuidado.
{{< /warning >}}
A saída é:
Aviso: Cuidado.
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 é:
Preaqueça o forno a 350°F.
Prepare a massa e a coloque na assadeira.
Nota: Unte a assadeira para melhores resultados.
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.
Faça e não faça - Cabeçalhos
Faça
Não faça
Atualize o título no front matter da página ou postagem de blog.
Utilize cabeçalho de primeiro nível, pois o Hugo automaticamente converte o título do front matter para um cabeçalho de primeiro nível.
Utilize cabeçalhos ordenados para fornecer um resumo de alto nível do seu conteúdo.
Utilize cabeçalhos de nível 4 a 6, a menos que seja absolutamente necessário. Se o seu conteúdo é detalhado a este nível, pode ser que ele precise ser dividido em artigos separados.
Utilize o sinal numérico ou cerquilha (#) para conteúdo que não seja postagem de blog.
Utilize traços ou sinais de igual (--- ou ===) para designar cabeçalhos de primeiro nível.
Utilize formatação de maiúsculas e minúsculas de sentença para cabeçalhos no corpo da página. Por exemplo, Estenda o kubectl com plugins
Utilize formatação de maiúsculas e minúsculas de título para cabeçalhos no corpo da página. Por exemplo, Estenda o Kubectl com Plugins
Utilize formatação de maiúsculas e minúsculas de título para o título da página no front matter. Por exemplo, title: Riscos do Contorno do Servidor da API do Kubernetes
Utilize formatação de maiúsculas e minúsculas de sentença para títulos de página no front matter. Por exemplo, não utilize title: Riscos do contorno do servidor da API do Kubernetes
Parágrafos
Faça e não faça - Parágrafos
Faça
Não faça
Tente manter os parágrafos abaixo de 6 sentenças.
Indente o primeiro parágrafo com caracteres de espaço. Por exemplo, ⋅⋅⋅Três espaços antes de um parágrafo o indenta.
Utilize três hífens (---) para criar uma régua horizontal. Utilize réguas horizontais para quebras no conteúdo do parágrafo. Por exemplo, uma mudança de cena em uma história, ou uma mudança de tópico dentro de uma seção.
Utilize réguas horizontais para decoração.
Links
Faça e não faça - Links
Faça
Não faça
Crie hiperlinks que forneçam o contexto para o conteúdo para o qual eles apontam. Por exemplo: certas portas estão abertas em suas máquinas. Veja Verifique portas necessárias para mais detalhes.
Utilize termos ambíguos, como "clique aqui". Por exemplo: certas portas estão abertas em suas máquinas. Veja aqui para mais detalhes.
Crie hiperlinks no estilo de Markdown: [texto do link](URL). Por exemplo: [_Shortcodes_ do Hugo](/docs/contribute/style/hugo-shortcodes/#table-captions), cuja saída é Shortcodes do Hugo.
Crie links no estilo de HTML: <a href="/media/examples/link-element-example.css" target="_blank">Visite nosso tutorial!</a>, ou crie links que abrem em novas abas ou janelas. Por exemplo: [website de exemplo](https://example.com){target="_blank"}
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
Faça e não faça - Utilize o tempo presente
Faça
Não faça
Este comando inicializa um proxy.
Este comando irá iniciar um proxy.
Exceção: utilize o tempo futuro ou pretérito quando necessário para comunicar o
significado correto.
Utilize voz ativa
Faça e não faça - Utilize voz ativa
Faça
Não faça
Você pode explorar a API utilizando um navegador.
A API pode ser explorada utilizando um navegador.
O arquivo YAML especifica o número de réplicas.
O número de réplicas é especificado no arquivo YAML.
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".
Faça e não faça - Utilize linguagem simples e direta
Faça
Não faça
Para criar um ReplicaSet, ...
A fim de criar um ReplicaSet, ...
Veja o arquivo de configuração.
Por favor, veja o arquivo de configuração.
Veja os Pods.
Com este próximo comando veremos os Pods.
Dirija-se ao leitor utilizando "você"
Faça e não faça - Dirigindo-se ao leitor
Faça
Não faça
Você pode criar um Deployment através ...
Criaremos um Deployment através ...
Na saída acima, você pode ver ...
Na saída acima, vimos que ...
Evite frases em Latim
Prefira termos em inglês no lugar de abreviações em Latim.
Faça e não faça - Evite frases em Latim
Faça
Não faça
For example, ...
e.g., ...
That is, ...
i.e., ...
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.
Faça e não faça - Padrões a evitar
Faça
Não faça
A versão 1.4 inclui ...
Na versão 1.4, adicionamos ...
O Kubernetes fornece uma nova funcionalidade para ...
Nós fornecemos uma nova funcionalidade para ...
Esta página ensina sobre como você pode utilizar Pods.
Nesta página, iremos aprender sobre Pods.
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.
Faça e não faça - Evite jargões e expressões idiomáticas
Faça
Não faça
Internally, ...
Under the hood, ...
Create a new cluster.
Turn up a new cluster.
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.
Faça e não faça - Evite afirmações que ficarão desatualizadas em breve
Faça
Não faça
Na versão 1.4, ...
Na versão atual, ...
A funcionalidade de Federação fornece ...
A nova funcionalidade de Federação fornece ...
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.
Essa página contém informações sobre a dashboard de analystics do kubernetes.io.
Essa dashboard foi feita usando
o Google Data Studio e possui informações coletadas do
kubernetes.io usando o Google Analytics.
Usando a dashboard
Por padrão, a dashboard mostra todos os analytics coletados nos últimos 30 dias. Use o seletor de data
para ver dados de outros intervalos de data. Outras
opções de filtros permitem que você veja dados baseados
em localização do usuário para acessar o site, a tradução
da documentação usada e outros.
Se você identificar um problema com essa dashboard ou quer solicitar qualquer melhoria, abra uma issue no repositório.