Esta página contém os detalhes de um projeto de escrita técnica aceito para a temporada de documentos do Google.
Resumo do projeto
- Organização de código aberto:
- Cloud Native Computing Foundation (CNCF)
- Redator técnico:
- Shrita
- Nome do projeto:
- Melhoria na documentação de SMI e malhas de serviço relacionadas
- Duração do projeto:
- Duração padrão (3 meses)
Project description
A tecnologia de malha de serviço tem o objetivo essencial de agregar valor ao aumento do número de serviços, atendendo a todas as necessidades de segurança, gerenciamento e monitoramento. A interface da malha de serviço (SMI, na sigla em inglês) define um conjunto de APIs para os casos de uso mais comuns (política de tráfego, telemetria e mudança) e permite a compatibilidade entre as malhas de serviço, que são camadas de infraestrutura dedicadas para lidar com a comunicação entre serviços em um ambiente de microsserviços. A padronização dessas interfaces vai proporcionar uma experiência aprimorada para o usuário final e, portanto, é um dos objetivos futuros do SMI e das malhas de serviço relacionadas.
Situação atual:
Guias do usuário: O SMI é um projeto de sandbox relativamente novo, doado à CNCF em abril de 2020. Como resultado, o projeto não tem a documentação do usuário final. O Meshery é um plano de gerenciamento de serviços com comparativo de desempenho para todos os tipos de serviço que facilita a adoção, configuração, operação e gerenciamento do desempenho 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. Sendo assim, gostaria de começar com um guia para o Meshery, que servirá como ponto de partida para toda a comunidade de usuários SMI.
Tutoriais de usuários: entre as plataformas SMI existentes: o aplicativo de exemplo Learn Layer5, atualmente funciona como um dispositivo de aprendizado para SMI e como aplicativo de exemplo para validar a especificação do SMI.Mas, caso contrário, os projetos SMI não têm 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, vou usá-lo como a ferramenta básica para exibir os recursos do SMI.
Documentação da API: inexistente no momento. O SMI e vários projetos relacionados têm endpoints de API definidos em uma plataforma. Por exemplo, o 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 a documentação relevante da API e pode ser aprimorado adicionando 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 teste o software. Eles precisam ser interativos e esteticamente atraentes para prender a atenção do usuário e, o mais importante, fáceis de usar.
No entanto, para escrever ou hospedar Guias do usuário, é recomendável usar um formato mais maduro, já que os guias do usuário geralmente servem como um guia de referência ou um local para solucionar problemas rapidamente. Em vez de serem interativos, eles precisam ser bem estruturados e se concentrar em melhorar a clareza, a coerência e o bom fluxo do usuário.
Uma possível solução para isso seria fazer tutoriais de usuário separados usando o Google Codelabs e um Guia do usuário independente com a ajuda do Jekyll e, por fim, integrá-los com a documentação da API para proporcionar uma experiência completa para o usuário final e futuros colaboradores.
Público-alvo: projetos SMI fornecem práticas operacionais e de implantação, ambientes de aprendizado e comparativos de mercado de desempenho para todos os projetos dentro deles. Ela atende a indivíduos e organizações.
Guias do usuário: Vou segmentar usuários iniciantes, sem suposições de conhecimento de TI pré-existente por parte do usuário. Objetivo: usuários iniciantes Motivo: usado principalmente como um guia de referência amplo, que precisará 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 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: Público-alvo: 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 um melhor entendimento da interface da malha de serviço.
Documentação do endpoint de API: Destino: usuários avançados Motivo: esta seção se concentra no uso dos recursos mais complexos da malha de serviço, que são mais indicados para usuários avançados com um nível básico de conhecimento em TI. Os usuários avançados procuram 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 maneira a facilitar a atualização sem comprometer a precisão ou consistência. De preferência, esse processo deve ser automatizado.
Recursos: Tutoriais de usuários: Codelab do Google Developers – usado para criar tutoriais interativos e abrangentes para os usuários finais. Vantagens: - Pode produzir tutoriais de sandbox. - Tem uma abordagem prática. - Escrita no Documentos Google e compatível com texto Markdown. - Podem ser monitoradas usando o Google Analytics - Fácil de observar o tráfego dos usuários. - Fácil de usar. Produz tutoriais esteticamente agradáveis que permitem ao usuário interagir diretamente com o software sem qualquer investimento direto.
Os Google Codelabs podem ser aprimorados e facilmente implantados usando o projeto CLaaT (Codelabs as a Thing). Esse programa oferece uma ferramenta de linha de comando usada para converter tutoriais escritos em Documentos Google usando Markdown para o formato de codelabs (HTML).
Guias do usuário: Jekyll - A documentação existente para meshery.io, disponível aqui, está hospedada no Jekyll e usa o tema Documentosy Jekyll. Ela usa Markdown, líquido, HTML e CSS para produzir sites estáticos prontos para hospedagem e executados em um ambiente de desenvolvimento em Ruby. Benefícios: - Pode hospedar sites diretamente dos repositórios do GitHub. - Este é um projeto bem apoiado e com uma comunidade muito ativa. - Os guias do usuário e as melhorias podem ser simplesmente adicionados à documentação atual do SMI e do Meshery, sem que você precise se preocupar em migrar para outra plataforma.
Documentação da API: o Swagger (como o 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 sua documentação permaneça atualizada à medida que sua API evolui. - Documentação do design da API: pode ser gerada automaticamente a partir de definições de API. - Manter várias versões de documentação - Projetos de API personalizados
Metas do projeto: - usar o Google Developers Codelabs para criar tutoriais interativos de usuário final para SMI e malhas de serviço relacionadas usando o Meshery como ferramenta. - Criar um guia para o usuário final usando o Jekyll para malhas de serviço. - Usar o Swagger para gerar a documentação do endpoint da API para o SMI. - Direcionar a comunidade do projeto para que usuários ou desenvolvedores futuros e atuais possam facilmente continuar fazendo adições a ela sob a orientação e moderação da comunidade 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 está disponível aqui: https://docs.google.com/document/d/1A3YYAMUTe06MojNWo8hdF4KZbvr-qVaaA2myzWeshHQ/edit?usp=sharing
Por que este Projeto? A comunidade de malha de serviço está crescendo em ritmo muito rápido, graças à recente integração como um projeto de sandbox à CNCF. No entanto, o projeto testemunhou uma séria escassez de documentação, tanto para usuários finais quanto para desenvolvedores. Já usei 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 tentei 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 desmotivar novos usuários e desenvolvedores que querem dar os primeiros passos na comunidade da malha de serviço ou usá-las em projetos pessoais ou profissionais. Eu gostaria de preencher essa lacuna, o que só pode ser feito com guias e tutoriais eficientes e bem documentados.