Contribuindo para os blogs do Kubernetes

• 1: Enviando artigos para blogs do Kubernetes
• 2: Diretrizes para o blog

1 - Enviando artigos para blogs do Kubernetes

Existem dois blogs oficiais do Kubernetes, e a CNCF também possui seu próprio blog, onde você pode encontrar informações sobre Kubernetes. No blog principal do Kubernetes, nós (o projeto Kubernetes) gostamos de publicar artigos com diferentes perspectivas e focos específicos, que tenham relação com o Kubernetes.

Com apenas algumas exceções especiais, publicamos conteúdos que não tenham sido submetidos ou publicados em nenhum outro lugar.

Escrevendo para os blogs do Kubernetes

Como autor, você tem três caminhos diferentes para a publicação.

Caminho recomendado

A abordagem recomendada pelo projeto Kubernetes é: envie sua proposta de artigo entrando em contato com a equipe do blog. Você pode fazer isso pelo Slack do Kubernetes (#sig-docs-blog). Para artigos que você deseja publicar apenas no blog de contribuidores, também é possível enviar a ideia diretamente para o SIG ContribEx comms.

A menos que haja algum problema com o seu envio, a equipe do blog / SIG ContribEx irá conectar você com:

• um editor do blog
• seu parceiro de escrita (outro autor do blog)

Quando a equipe conecta você com outro autor, a ideia é que vocês se apoiem mutuamente, revisando os rascunhos um do outro. Você não precisa ser especialista no assunto; a maioria das pessoas que lerá o artigo também não será. Nós, a equipe de blog do Kubernetes, chamamos esse outro autor de parceiro de escrita.

O editor está lá para ajudar você ao longo da jornada, do rascunho até a publicação. Ele pode aprovar seu artigo diretamente para publicação ou pode organizar o processo de aprovação.

Leia escrever um artigo para blog para saber mais sobre o processo.

Começando com um pull request

O segundo caminho para escrever para nossos blogs é começar diretamente com um pull request no GitHub. A equipe do blog não recomenda essa abordagem; o GitHub é bastante útil para colaboração em código, mas não é ideal para escrita de textos longos.

É totalmente aceitável abrir um pull request inicial provisório com um commit vazio, e em seguida, trabalhar fora do GitHub antes de retornar ao PR inicial.

Assim como no caminho recomendado, tentaremos encontrar um parceiro de escrita e um editor do blog para você. Eles ajudarão você a preparar o artigo para publicação.

Processo de artigos pós lançamento de versão

O terceiro caminho é voltado para artigos sobre alterações no Kubernetes relacionadas a um lançamento de versão. Sempre que há um lançamento de versão, a equipe de Release Comms assume o controle do calendário de publicações do blog. Pessoas que adicionam funcionalidades a uma versão, ou que estão planejando outras alterações que o projeto precisa anunciar, podem entrar em contato com o Release Comms para que seu artigo seja planejado, redigido, revisado e eventualmente publicado.

Agendamento de artigos

Para o blog do Kubernetes, a equipe do blog geralmente programa publicações de artigos em dias úteis (Calendário Gregoriano, como utilizado nos EUA e em outros países). Quando é importante publicar em uma data específica que cai em um fim de semana, a equipe tenta acomodar essa necessidade.

A seção sobre escrever um artigo para blog explica o que fazer:

• inicialmente, não especifique uma data para o artigo
• porém, defina o artigo como rascunho (adicione draft: true no front matter)

Quando o bot Prow faz o merge do PR que você escreve, o artigo continua como rascunho e não é publicado. Um contribuidor do Kubernetes (você, seu parceiro de escrita ou alguém da equipe do blog) abre então um pequeno PR de acompanhamento marcando o artigo para publicação. Ao fazer o merge desse segundo PR, o artigo deixa de ser rascunho e passa a ser publicado automaticamente.

No dia em que o artigo está programado para ser publicado, a automação aciona o build do site e o artigo se torna visível.

Escrevendo um artigo

Após apresentar sua ideia, incentivamos você a usar o HackMD (um editor Markdown web) ou um documento do Google Docs para compartilhar uma versão editável do texto. Seu parceiro de escrita pode ler seu rascunho, e em seguida, fazer sugestões ou fornecer outros comentários, além de verificar se o conteúdo está alinhado com as diretrizes do blog.

Ao mesmo tempo, você normalmente será o parceiro de escrita dele e poderá seguir nosso guia sobre como apoiar o trabalho dele.

Etapas administrativas iniciais

Você deve assinar o CLA caso ainda não tenha feito isso. É recomendável iniciar esse processo cedo; se você estiver escrevendo como parte do seu trabalho, talvez precise verificar com a equipe jurídica ou com seu gestor para garantir que você está autorizado a assinar.

Rascunho inicial

A equipe do blog recomenda que você utilize o HackMD ou um documento do Google Docs, para preparar e compartilhar uma versão inicial do texto do artigo que possa ser editada em tempo real.

Seu parceiro de escrita pode comentar e / ou fornecer feedback sobre seu rascunho e irá (ou deveria) verificar se ele está de acordo com as diretrizes. Ao mesmo tempo, você será o parceiro de escrita dele e seguirá o guia que explica como você irá apoiar o trabalho dele.

Nesta fase, não se preocupe muito em acertar a formatação Markdown exatamente.

Se houver imagens, você pode colar versões bitmap para receber um feedback inicial. A equipe do blog pode ajudar você (mais tarde no processo) a preparar as ilustrações para a publicação final.

Markdown para publicação

Confira o formato Markdown de posts existentes no repositório do site no GitHub.

Se você ainda não estiver familiarizado, leia noções básicas de contribuição. Esta seção da página pressupõe que você não possui um clone local do seu fork e que você está trabalhando através da interface web do GitHub. Você precisa criar um fork remoto do repositório do site caso ainda não tenha.

No repositório do GitHub, clique no botão Criar novo arquivo. Copie o conteúdo existente do HackMD ou Google Docs e cole no editor. Mais detalhes sobre o conteúdo do arquivo serão fornecidos posteriormente nesta seção. Nomeie o arquivo de acordo com o título proposto para o post do blog, mas não inclua a data no nome do arquivo. Os revisores do blog trabalharão com você para definir o nome final do arquivo e a data que o artigo será publicado.

1. Ao salvar o arquivo, o GitHub irá guiá-lo através do processo de pull request.

2. Seu parceiro de escrita pode revisar o seu envio e trabalhar com você no feedback e detalhes finais. Um editor do blog aprova seu pull request para o merge, como um rascunho que ainda não foi agendado.

Front matter

O arquivo Markdown que você escrever deve usar o formato YAML do front matter do Hugo.

Aqui está um exemplo:

---
layout: blog
title: "Seu Título Aqui"
draft: true # será alterado para date: YYYY-MM-DD antes da publicação
slug: texto-em-minusculo-para-o-link-sem-espacos # opcional
author: >
  Autor-1 (Afiliação),
  Autor-2 (Afiliação),
  Autor-3 (Afiliação)  
---

• inicialmente, não especifique uma data para o artigo
• no entanto, defina o artigo como rascunho (adicione draft: true ao front matter do artigo)

Conteúdo do artigo

Certifique-se de usar títulos Markdown de segundo nível (## não #) como o nível de título mais alto no artigo. O title que você define no front matter se torna o título de primeiro nível da página.

Você deve seguir o guia de estilo, mas com as seguintes exceções:

• é aceitável que os autores escrevam um artigo em seu próprio estilo, desde que a maioria dos leitores compreenda o ponto que está sendo apresentado.
• é aceitável usar "nós" em um artigo do blog com múltiplos autores ou quando a introdução do artigo indica claramente que o autor está escrevendo em nome de um grupo específico. Como você notará nesta seção, embora nós evitemos usar "nós" em nossa documentação, é aceitável fazer exceções justificáveis.
• evitamos usar shortcodes do Kubernetes para chamadas (como {{< caution >}}). Isso porque as chamadas são direcionadas a leitores de documentação, e artigos de blog não são documentação.
• declarações sobre o futuro são aceitáveis, embora as usemos com cautela em anúncios oficiais em nome do Kubernetes.
• exemplos de código usados ​​em artigos de blog não precisam usar o shortcode {{< code_sample >}}, e muitas vezes é melhor (mais fácil de manter) que não o usem.

Diagramas e ilustrações

Para ilustrações, diagramas ou gráficos, utilize o shortcode figure sempre que possível. Você deve definir um atributo alt para acessibilidade.

Para ilustrações e diagramas técnicos, tente usar gráficos vetoriais. A equipe do blog recomenda SVG em vez de formatos de diagrama raster (bitmap / pixel) e também recomenda SVG em vez de Mermaid (você ainda pode capturar o código-fonte do Mermaid em um comentário). A preferência por SVG em vez de Mermaid se deve ao fato de que, quando os mantenedores atualizam o Mermaid ou fazem alterações na renderização do diagrama, eles podem não ter uma maneira fácil de entrar em contato com o autor original do artigo do blog para verificar se as alterações estão corretas.

O guia de diagramas destina-se à documentação do Kubernetes, não a artigos de blog. Ainda assim, é bom segui-lo, mas:

• não há necessidade de legendar os diagramas como Figura 1, Figura 2, etc.

A exigência de imagens escaláveis ​​(vetoriais) torna o processo mais difícil para pessoas menos familiarizadas com o assunto enviarem artigos; o Kubernetes SIG Docs continua buscando maneiras de reduzir essa barreira. Se você tiver ideias sobre como facilitar esse processo, por favor, ofereça-se para ajudar.

Para outras imagens (como fotos), a equipe do blog recomenda fortemente o uso de atributos alt. É aceitável usar um atributo alt vazio para os casos em que o software de acessibilidade não deve mencionar a imagem, mas essa é uma situação rara.

Mensagens de commit

No momento em que você marcar sua solicitação de pull request como pronta para revisão, cada mensagem de commit deve ser um breve resumo do trabalho que está sendo feito. A primeira mensagem de commit deve fazer sentido como uma descrição geral da postagem do blog.

Exemplos de uma boa mensagem de commit:

• Add blog post on the foo kubernetes feature
• blog: foobar announcement

Exemplos de mensagens ruins de commit:

• Placeholder commit for announcement about foo
• Add blog post
• asdf
• initial commit
• draft post

Squashing

Assim que você achar que o artigo está pronto para o merge, você deve fazer squash dos commits em seu pull request; se você não tiver certeza de como fazer isso, não hesite em pedir ajuda à equipe do blog.

2 - Diretrizes para o blog

Estas diretrizes abrangem o blog principal do Kubernetes e o blog de contribuidores do Kubernetes.

Todo o conteúdo do blog também deve aderir à política geral do guia de conteúdo.

Antes de você começar

Certifique-se de estar familiarizado com as seções de introdução de contribuindo para os blogs do Kubernetes, não apenas para aprender sobre os dois blogs oficiais e as diferenças entre eles, mas também para obter uma visão geral do processo.

Conteúdo original

O projeto Kubernetes aceita apenas conteúdo original, em inglês.

Essa restrição também se aplica à promoção de outros projetos da Linux Foundation e da CNCF. Muitos projetos da CNCF possuem seus próprios blogs. Estes geralmente são uma escolha melhor para publicações sobre um projeto específico, mesmo que esse projeto tenha sido criado especificamente para funcionar com Kubernetes (ou com Linux, etc.).

Conteúdo relevante

Os artigos devem conter conteúdo que se aplique de forma ampla à comunidade Kubernetes. Por exemplo, um envio deve focar no Kubernetes upstream, e não em configurações específicas de fornecedores. Para artigos enviados ao blog principal que não sejam artigos espelho, os hiperlinks no artigo devem normalmente direcionar para a documentação oficial do Kubernetes. Ao fazer referências externas, os links devem ser diversificados - por exemplo, um envio não deve conter apenas links para o blog de uma única empresa.

Os blogs oficiais do Kubernetes não são o local para propostas de fornecedores ou para artigos que promovam uma solução específica de fora do Kubernetes.

Às vezes, esse é um equilíbrio delicado. Você pode pedir orientação no Slack (#sig-docs-blog) para entender se um post é apropriado para o blog do Kubernetes e / ou para o blog de contribuidores - não hesite em entrar em contato.

O guia de conteúdo se aplica incondicionalmente a artigos de blog e aos PRs que os adicionam. Tenha em mente que algumas restrições no guia indicam que são relevantes apenas para a documentação; essas restrições marcadas não se aplicam a artigos do blog.

Localização

O site está localizado em vários idiomas; o inglês é o idioma base para todas as outras localizações. Mesmo que você fale outro idioma e fique feliz em fornecer uma localização, isso deve ser feito em um pull request separado (consulte idiomas por PR).

Direitos autorais e reutilização

Você deve escrever conteúdo original e deve ter permissão para licenciar esse conteúdo para a Cloud Native Computing Foundation (para que o projeto Kubernetes possa publicá-lo legalmente). Isso significa que não somente o plágio direto é proibido, mas também que você não pode escrever um artigo do blog se não tiver permissão para atender às condições de licenciamento de direitos autorais da CNCF (por exemplo, se o seu empregador tiver uma política de propriedade intelectual que restrinja o que você tem permissão para fazer).

A licença do blog permite o uso comercial do conteúdo para fins comerciais, mas não o contrário.

Grupos de interesse especial e grupos de trabalho

Tópicos relacionados à participação ou aos resultados das atividades dos SIGs do Kubernetes estão sempre no tópico (consulte o trabalho da Equipe de Comunicação de Contribuidores para suporte a esses posts).

O projeto normalmente espelha esses artigos em ambos os blogs.

Restrições nacionais sobre conteúdo

O site do Kubernetes possui uma licença de Provedor de Conteúdo de Internet (ICP) do governo da China. Embora seja improvável que isso seja um problema, o Kubernetes não pode publicar artigos que seriam bloqueados pela filtragem oficial de conteúdo da internet do governo chinês.

Diretrizes específicas para conteúdo de blog

Além do guia de estilo geral, os artigos de blog devem (não obrigatoriamente) se alinhar às recomendações de estilo específicas para blogs.

O restante desta página é uma orientação adicional; não são regras rígidas que os artigos devem seguir, mas os revisores provavelmente irão (e devem) solicitar ajustes em artigos que obviamente não estejam alinhados com as recomendações aqui descritas.

Diagramas e ilustrações

Para ilustrações - incluindo diagramas ou gráficos - utilize o shortcode figure sempre que possível. Você deve definir um atributo alt para acessibilidade.

Utilize imagens vetoriais para ilustrações, diagramas técnicos e gráficos similares; o formato SVG é fortemente recomendado.

Artigos que utilizam imagens rasterizadas para ilustrações são mais difíceis de manter e, em alguns casos, a equipe do blog pode solicitar que o autor revise o artigo antes da publicação.

Atemporalidade

Os posts do blog devem buscar ser à prova do futuro

• Dada a velocidade de desenvolvimento do projeto, o SIG Docs prefere uma escrita atemporal: conteúdo que não exija atualizações frequentes para se manter correto para o leitor.
• Pode ser melhor adicionar um tutorial ou atualizar a documentação oficial do que escrever uma visão geral de alto nível em um post do blog.
• Considere concentrar o conteúdo técnico mais extenso como uma "chamada para ação" do post do blog, e foque no problema ou no motivo pelo qual os leitores deveriam se importar.

Exemplos de conteúdo

Aqui estão alguns exemplos de conteúdo apropriado para o blog principal do Kubernetes:

• Anúncios sobre novos recursos do Kubernetes
• Explicações de como alcançar um determinado resultado usando Kubernetes; apresente uma abordagem de baixo esforço operacional para aprimorar uma implantação gradual.
• Comparações entre diferentes opções de software relacionadas a Kubernetes e cloud native. É aceitável incluir links para uma dessas opções, desde que você divulgue claramente qualquer conflito de interesse / relacionamento
• Relatos sobre problemas ou incidentes e como você os resolveu
• Artigos sobre a construção de plataformas cloud native para casos de uso específicos
• Sua opinião sobre pontos positivos ou negativos do Kubernetes
• Anúncios e notícias sobre componentes não centrais do Kubernetes, como a Gateway API
• Anúncios e atualizações pós-release
• Comunicados sobre vulnerabilidades de segurança importantes do Kubernetes
• Atualizações de projetos do Kubernetes
• Tutoriais e demonstrações
• Liderança de pensamento sobre Kubernetes e cloud native
• Os componentes do Kubernetes são propositalmente modulares, então textos sobre pontos de integração existentes como CNI e CSI são relevantes. Desde que você não escreva uma proposta de fornecedor, você também pode escrever sobre o que está do outro lado dessas integrações.

Aqui estão alguns exemplos de conteúdo apropriado para o blog de contribuidores do Kubernetes:

• Artigos sobre como testar suas alterações no código do Kubernetes
• Conteúdo sobre contribuições não relacionadas a código
• Discussões sobre funcionalidades em estágio alfa, cujo design ainda está em discussão
• Artigos do tipo “Conheça o time” sobre grupos de trabalho, SIGs, etc.
• Um guia sobre como escrever código seguro que fará parte do próprio Kubernetes
• Artigos sobre encontros de mantenedores e os resultados desses encontros

Exemplos de conteúdo que não será aceito

No entanto, o projeto não publicará:

• Propostas de fornecedores
• Um artigo que você já publicou em outro lugar, mesmo que apenas em seu próprio blog de baixo tráfego
• Grandes blocos de código-fonte de exemplo com apenas uma explicação mínima
• Atualizações sobre projetos externos que funcionam ou dependem do Kubernetes (esses devem ser publicados no blog do próprio projeto externo)
• Artigos sobre o uso do Kubernetes com um cloud provider específico
• Artigos que critiquem pessoas, grupos de pessoas ou empresas específicas
• Artigos que contêm erros técnicos importantes ou detalhes enganosos (por exemplo: se você recomendar desativar um importante controle de segurança em clusters de produção, porque isso pode ser inconveniente, é provável que o projeto Kubernetes rejeite o artigo)