Esta página contém os detalhes de um projeto de escrita técnica aceito para o Temporada dos Documentos Google.
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:
- Shriti
- Nome do projeto:
- Melhoria na documentação da SMI e das redes de serviços relacionadas
- Duração do projeto:
- Duração padrão (três meses)
Project description
A tecnologia de malha de serviço tem como objetivo principal agregar valor ao número crescente de serviços, atendendo a todas as suas necessidades de segurança, gerenciamento e monitoramento. A interface de malha de serviço (SMI, na sigla em inglês) define um conjunto de APIs para os casos de uso mais comuns de malhas de serviço (política de tráfego, telemetria e deslocamento) e permite a compatibilidade entre elas, que são camadas de infraestrutura dedicadas para lidar com a comunicação de serviço a serviço em um ambiente de microsserviços. A padronização dessas interfaces vai melhorar a experiência do usuário final e, portanto, é uma meta futura para a SMI e as redes de serviços relacionadas.
Estado atual:
Guias do usuário: o SMI é um projeto de sandbox relativamente novo, doado ao CNCF em abril de 2020. Como resultado, o projeto não tem documentação para o usuário final. O Meshery é um plano de gerenciamento de serviços com comparativos de mercado de desempenho para todos os tipos de serviços, facilitando a adoção, a configuração, a operação e o gerenciamento da performance de diferentes malhas de serviço. Ele incorpora a coleta e a exibição de métricas de aplicativos executados em qualquer malha de serviço. Por isso, gostaria de começar com um guia para a Meshery, que vai servir como ponto de partida para toda a comunidade de usuários da SMI.
Tutoriais de usuário: Entre as plataformas SMI existentes: O aplicativo de exemplo, Learn Layer5, atualmente serve como um dispositivo de aprendizagem para SMI e como o aplicativo de exemplo para realizar a validação da especificação de SMI.Fora isso, os projetos SMI carecem completamente de tutoriais para o usuário final, o que é um sério obstáculo devido à natureza altamente técnica dos projetos. O Meshery é o aplicativo perfeito para mostrar os benefícios e o uso do SMI e das malhas de serviço relacionadas. É por isso que ele será usado como a ferramenta de base para mostrar os recursos do SMI.
Documentação da API: não existe no momento. A SMI e vários projetos relacionados têm os endpoints da API definidos em uma plataforma. Por exemplo, a Meshery tem os endpoints definidos em server.go (https://github.com/layer5io/meshery/blob/master/router/server.go), mas eles não são bem comentados nem documentados externamente. Isso pode ser resolvido com documentação significativa das APIs e pode ser aprimorado com a adição de maneiras para os usuários testarem seus endpoints e visualizarem seus recursos.
Análise:
Os tutoriais do usuário são criados para permitir que o usuário interaja e faça um teste do software. Eles precisam ser interativos e esteticamente atraentes para prender a atenção do usuário e, o mais importante, ser fáceis de usar.
No entanto, para escrever ou hospedar guias do usuário, um formato mais maduro é recomendável, já que os guias do usuário geralmente servem como guia de referência ou um local para corrigir problemas rapidamente. Em vez de serem interativas, elas precisam ser bem estruturadas e focadas em melhorar a clareza, a coerência e o bom fluxo do usuário.
Uma possível solução para isso seria criar tutoriais separados para usuários usando os codelabs do Google e um guia do usuário independente com a ajuda do Jekyll e, por fim, integrá-los à documentação da API para oferecer uma experiência completa ao usuário final e aos futuros colaboradores.
Público-alvo: os projetos de SMI fornecem práticas de implantação e operacionais, ambientes de aprendizagem e comparativos de desempenho para todos os projetos sob sua responsabilidade. Ele atende a indivíduos e organizações.
Guias do usuário: vou segmentar usuários iniciantes, sem supor que eles tenham conhecimento de TI. Público-alvo: usuários iniciantes Motivo: usado principalmente como um guia de referência amplo, que precisa ser atualizado com o tempo. Isso vai incluir explicações detalhadas e dicas úteis para garantir que o usuário tenha todas as informações necessárias para configurar e trabalhar com uma malha de serviço. O guia vai ficar mais interessante e fácil de usar com a adição de vídeos, imagens, capturas de tela e GIFs, sempre que necessário.
Tutoriais para usuários: Objetivo: usuários iniciantes Motivo: o foco será tornar os tutoriais envolventes e esteticamente atraentes para prender a atenção do usuário e permitir uma execução de teste do software sem problemas, o que levará a uma melhor compreensão da interface da malha de serviço.
Documentação do endpoint da API: Público-alvo: usuários avançados Motivo: esta seção se concentra no uso dos recursos mais complexos da malha de serviços, que é mais interessante para usuários avançados com um nível básico de conhecimento de TI. Os usuários avançados vão procurar tutoriais concisos que também podem ser usados como guias de referência, se necessário. A documentação do endpoint precisa ser escrita de forma que seja fácil de atualizar sem comprometer a precisão ou a consistência. De preferência, esse processo deve ser automatizado.
Recursos: Tutoriais para usuários: Codelab do Google Developers: usado para criar tutoriais interativos e abrangentes para os usuários finais. Benefícios: - Pode produzir tutoriais de sandbox. - Tem uma abordagem prática. - Escrito usando os Documentos Google e compatível com texto Markdown. - Pode ser monitorado com o Google Analytics - Fácil de observar o tráfego de usuários. - Fácil de usar. Produz tutoriais esteticamente agradáveis, permitindo que o usuário interaja diretamente com o software sem nenhum investimento direto.
Os codelabs do Google podem ser aprimorados e facilmente implantados usando o projeto CLaaT (Codelabs como uma coisa). Este é um programa que oferece uma ferramenta de linha de comando usada para converter tutoriais escritos no Documentos Google usando Markdown para o formato codelabs (HTML).
Guias do usuário: Jekyll - A documentação existente de meshery.io, que pode ser encontrada aqui, está hospedada no Jekyll e usa o tema Docsy Jekyll. Ele usa Markdown, Liquid, HTML e CSS para produzir sites estáticos e prontos para hospedar, além de ser executado em um ambiente de desenvolvimento em Ruby. Benefícios: - É possível hospedar sites diretamente nos repositórios do GitHub. - Este é um projeto bem apoiado com uma comunidade muito ativa - Os guias do usuário e os aprimoramentos podem ser adicionados à documentação existente do SMI e do Meshery, sem precisar se preocupar com a migração para outra plataforma.
Documentação da API: o Swagger (ou Swaggo) será usado para criar a documentação da API para SMI e Meshery. É uma solução elegante para escrever documentos de API. Benefícios: - Documentação do design da API: garante que a documentação seja atualizada conforme a API evolui. - Documentação do design da API: pode ser gerada automaticamente com base nas definições da API. - Manter várias versões da documentação - Designs personalizados de API
Objetivos do projeto: - Use os codelabs do Google Developers para criar tutoriais interativos para usuários finais sobre a SMI e as malhas de serviços relacionadas usando o Meshery como ferramenta. - Crie um guia do usuário final usando o Jekyll para redes de serviços. - Use o Swagger para gerar a documentação do endpoint da API para SMI. - Faça com que o projeto seja orientado pela comunidade para que os usuários ou desenvolvedores atuais e futuros possam continuar adicionando conteúdo com facilidade sob a orientação e moderação da comunidade do SMI.
Cronograma: O cronograma proposto pode ser encontrado aqui: https://docs.google.com/document/d/1If2mtBdWZer4qrh66NfXOWBx_3-tiA09jnoPMqy2lqs/edit#bookmark=kix.j1b6m64eubsl
Estrutura: a estrutura proposta para o guia do usuário pode ser encontrada aqui: https://docs.google.com/document/d/1A3YYAMUTe06MojNWo8hdF4KZbvr-qVaaA2myzWeshHQ/edit?usp=sharing
Por que este projeto? A comunidade da malha de serviço está crescendo em um ritmo acelerado graças à recente integração como um projeto de sandbox na CNCF. No entanto, o projeto está enfrentando uma grave falta de documentação, tanto para usuários finais quanto para desenvolvedores. Testei várias malhas de serviço no passado, incluindo o LinkerD com o app EmojiVoto, o Istio com o aplicativo Bookinfo e o Consul da Hashicorp. Também testei a divisão de tráfego SMI e implementei várias regras de validação na configuração da minha malha de serviço. O processo de aprendizado é fascinante, mas altamente técnico, e pode ser desanimador para novos usuários e desenvolvedores que querem dar os primeiros passos na comunidade de malhas de serviços ou usar malhas de serviços para projetos pessoais ou profissionais. Gostaria de preencher essa lacuna, o que só pode ser feito com guias e tutoriais eficientes e bem documentados.