Esta página contém os detalhes de um projeto de redação técnica aceito para a Google Season of Docs.
Resumo do projeto
- Organização de código aberto:
- Fundação de computação nativa da nuvem (CNCF, na sigla em inglês)
- Redator técnico:
- Syam Sundar K
- Nome do projeto:
- Mais e melhores exemplos de Kubectl
- Duração do projeto:
- Duração padrão (3 meses)
Project description
O objetivo deste projeto é melhorar a folha de referência e os documentos de referência do kubectl.
Estes são os objetivos finais deste projeto: • Criar mais e melhores exemplos do kubectl. • Adicionamos exemplos de kubectl à folha de referência do kubectl. • Refactorização dos documentos do kubectl para maior utilidade.
Meta I: exemplos para kubectl:
Vamos trabalhar de perto com os grupos de interesses especiais da CLI para entender e documentar o contexto e os tipos de exemplos que os usuários do Kubernetes mais querem. Isso pode variar desde a melhoria dos comandos kubectl existentes na folha de referência até a adição de novos comandos.
Meta 2: aumentar a utilidade dos documentos:
Para aumentar a utilidade dos documentos, é possível fazer o seguinte:
• Elimine as dificuldades dos iniciantes • Reorganize o comando do kubectl em uma determinada ordem para garantir a continuidade no fluxo lógico
Elimine as dificuldades dos iniciantes com explicações melhores sobre comandos e casos de uso. Isso pode parecer simples, mas pode influenciar significativamente os iniciantes a continuar ou abandonar o aprendizado. Por exemplo, quando comecei a usar o Kubernetes com o kubectl, eu não tinha certeza das diferenças entre pods e implantações. Inicialmente implantei um serviço de back-end escrito em nodejs. Depois de algumas horas, quis desativá-lo e tentei excluir o pod, mas, devido à natureza de autocorreção dos pods, eles foram criados novamente. Fiquei um pouco confuso com o que estava acontecendo e queria saber por que ele estava sendo recriado e não excluído. Depois de algumas pesquisas na Web, descobri que excluir pods não é o mesmo que excluir uma implantação. Para um olho treinado, isso pode parecer simples, mas uma explicação clara que elimina esse tipo de ambiguidade é o que distingue um bom documento de um ótimo documento.
Reorganizar o comando kubectl em uma determinada ordem para garantir a continuidade do fluxo lógico. Se você acredita muito em narrativas, provavelmente está se perguntando como incluir elementos de narrativa em uma planilha com uma lista de comandos de terminal. Tudo o que aprendemos sempre tem um fluxo lógico, um ponto inicial e um ponto final, se você quiser. O kubectl, como uma ferramenta de linha de comando, obviamente tem uma curva de aprendizado, que coincide com a curva de aprendizado do próprio Kubernetes. Como quase todo mundo começa a jornada com o Kubernetes pelo kubectl (exceto quem usa a interface da Web) e a curva de aprendizado é muito próxima da curva de aprendizado do Kubernetes, os documentos podem ser melhorados significativamente apenas mudando a ordem desses comandos e introduzindo elementos de narrativa. Por exemplo, recursos como o escalonamento automático horizontal de pods podem ser explicados depois de explicar os recursos com exemplos e ilustrações do mundo real.
Meta III: melhorias na usabilidade dos Documentos:
A migração recente do site do Kubernetes para o Docsy Hugo é incrível e uma mudança enorme na perspectiva dos documentos. Embora a migração tenha sido bem-sucedida, ainda há espaço para muitas melhorias no espaço de documentos.
Eu sugiro algumas mudanças:
• Rolagem automática no painel esquerdo para a seção ativa atualmente nos documentos principais: isso pode ser útil para acompanhar as seções atuais, futuras e passadas. • Copiar para a área de transferência: alguns comandos podem ser longos, e a funcionalidade de cópia pode ser útil ao trabalhar com esse tipo de comando. • Formatação de conteúdo de arquivos doc: após a migração, o conteúdo de algumas páginas não é formatado corretamente. Por exemplo, a seção "Tipo de recurso" na visão geral do kubectl. Isso degrada a experiência do usuário.
Essas são as mudanças que podem melhorar a experiência do usuário no site do kubernetes e aumentar a produtividade dele.