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:
- Gateway gRPC
- Redator técnico:
- iamrajiv
- Nome do projeto:
- Como refatorar o site de documentos atual do gRPC-Gateway
- Duração do projeto:
- Duração padrão (três meses)
Project description
RESUMO:
O site de documentos do usuário foi desenvolvido para ajudar os usuários finais a usar um produto ou serviço. Um bom site de documentos do usuário é muito importante porque oferece uma maneira de os usuários aprenderem a usar o software, seus recursos, dicas, truques e também resolver problemas comuns encontrados ao usar o software. Ele também reduz o custo de suporte e faz parte da identidade corporativa do produto. Um site de boas documentações do usuário é um sinal de saúde do produto e da equipe de desenvolvimento. Sem um bom site de documentos do usuário, o usuário pode não saber como fazer as coisas acima de maneira eficaz e eficiente. O site de documentos do usuário pode ter um papel fundamental no sucesso de um produto, porque uma boa comunicação é e sempre será o centro de qualquer empresa ou produto. Uma boa documentação apenas leva essa comunicação para um modelo gerenciável que todos podem acessar para ter sucesso.
No momento em que este artigo foi escrito, o repositório gRPC-Gateway foi bifurcado por cerca de 1.200 vezes, e 184 pessoas contribuíram para esse repositório. Isso mostra que muitas pessoas do mundo todo usam o gRPC-Gateway e podem querer ler a documentação do usuário para obter orientações sobre como usar o gRPC-Gateway. No entanto, a documentação do usuário e o site de documentos do gRPC-Gateway estão desatualizados e incompletos. A comunidade do gRPC-Gateway quer usar esse projeto para refatorar o site de documentos atual e melhorar a experiência dos usuários finais ao usar o gRPC-Gateway.
ESTADO ATUAL:
Atualmente, o site de documentos do gRPC-Gateway tem dois problemas principais:
• O primeiro problema é um site de documentos ruim e desatualizado, ou seja, o estilo e a estrutura do site e do tema usados são obsoletos, incompletos, difíceis de navegar ou encontrar informações, não abrangem muitos recursos de um bom site de documentos. A refatoração do site de documentos existente do gRPC-Gateway vai incluir o estilo do site, a adição de recursos como a pesquisa de documentos etc., a melhoria da interface do site, a organização de tutoriais e exemplos em uma barra lateral adequada e a atualização dos fluxogramas e imagens existentes com a criação de um novo, etc. Essa será minha meta principal, e meu trabalho será mais baseado no estilo e na reestruturação do site de documentos atual.
• O segundo problema é a necessidade de refazer a documentação, tutoriais e exemplos existentes do gRPC-Gateway, o que pode ser feito removendo erros ortográficos e gramaticais nos arquivos, fazendo o alinhamento adequado dos snippets de Go e refatorando snippets de Go de acordo com os formatos Gofmt. Além disso, se for o caso, podemos adicionar mais documentação, tutoriais e exemplos, se necessário, ou reutilizar os arquivos existentes após a refatoração. Essa é minha meta secundária, e vou fazer isso depois de concluir minha meta principal, ou seja, estilizar e reestruturar o site de documentos atual.
WHY IS MY PROPOSED DOCS SITE AN IMPROVEMENT OVER THE CURRENT ONE?
O site de documentos do usuário proposto será estruturado para melhorar e garantir a eficiência, a consistência e a tranquilidade do usuário final. Ele vai melhorar a aparência e a interface com seções e recursos bem estilizados, além de guias escritos e fluxogramas e imagens associados.
A documentação do gRPC-Gateway fornece uma boa descrição do método e do exemplo. Mas ele ainda usa o tema antigo do Jekyll, e hoje temos temas do Jekyll melhores para o SSG (gerador de sites estáticos). Além disso, é necessário reestruturar as páginas e torná-las mais úteis para os usuários, adicionando novos exemplos e tutoriais e atualizando e reescrevendo o conteúdo anterior.
ESTRUTURA E MAPA DO CAMINHO DAS METAS E IDEIAS PROPOSTAS:
OBJETIVO PRINCIPAL DESTE PROJETO:-
As metas e ideias acima podem ser implementadas das seguintes maneiras:
Mudar o tema atual do Jekyll para um tema melhor e mais robusto. O motivo para usar os temas do Jekyll novamente é que será fácil para os mantenedores contribuírem e entenderem o fluxo de trabalho do projeto, já que eles já conhecem o framework e o tema do Jekyll, que é semelhante ao novo tema do Jekyll.
Depois de analisar diferentes temas do Jekyll na Internet, encontrei esta suíte de temas https://idratherbewriting.com/documentation-theme-jekyll/ que é melhor para o site de documentos do gRPC-Gateway devido ao seguinte recurso:
• Markdown:- Para que os redatores técnicos não precisem se preocupar com a instalação. Eles podem escrever simplesmente no arquivo .md. Qualquer pessoa pode clicar no botão de edição mostrado no site (novo recurso) e contribuir (editar/sugerir mudanças na página no GitHub) para melhorar. Isso vai incentivar os usuários a adicionar ou editar conteúdo para melhorá-lo.
• Pesquisa de documentação: o usuário precisa ter uma caixa de pesquisa para encontrar conteúdo relevante com facilidade e rapidez.
• Seção de comentários: o usuário pode ter a opção de comentar e compartilhar as próprias opiniões sobre postagens e tutoriais. Eles podem ler as visualizações de outras pessoas na documentação do projeto.
• Novas notas da versão e blogs: o site precisa ser atualizado com novas postagens do blog e notícias sobre o desenvolvimento e o roadmap atuais. Esse tipo de blog precisa estar presente na página de destino.
• Desenvolvimento rápido: a maioria dos frameworks de SSG (gerador de sites estáticos) são executados no servidor, e as mudanças no arquivo são refletidas imediatamente na interface. Além disso, o processo de implantação e criação precisa ser fácil. No futuro, se quisermos mudar o framework, usaremos. Então deve ser fácil. A maioria dos frameworks oferece suporte à escrita em Markdown. Portanto, basta mover os arquivos .md e fazer algumas mudanças.
Aqui estou dividindo as páginas do site em novas seções e páginas :
• Página de destino:
A página de destino precisa apontar os principais recursos do gRPC-Gateway.
- Introdução ao gRPC-Gateway (redirecionamento para o guia do usuário)
- Instruções simples de instalação (comandos breves)
- Por que usar o gRPC-Gateway
- Projeto que usa o gRPC-Gateway
A ideia básica é, em vez de escrever uma descrição longa, mostrar os principais pontos na página de destino e fornecer o link para acessar os detalhes.
• Página do guia do usuário do gRPC-Gateway:-
- Guia de instalação.
- Guia de início rápido do gRPC-Gateway.
• Página do guia para desenvolvedores do gRPC-Gateway:-
O guia de desenvolvimento, o guia de contribuição, a configuração do Git, o código de conduta, a configuração da documentação, o fluxo de trabalho de desenvolvimento etc. apontam para páginas semelhantes. Portanto, é necessário refatorar e reorganizar todos os arquivos. A página de desenvolvimento principal precisa conter todas essas páginas, e o hiperlink será criado em cada etapa.
• Sobre a página do gateway gRPC:-
A lista de todos os colaboradores precisa estar presente nas seções de equipe Links rápidos e notas de lançamento, os blogs mais recentes serão adicionados para engajar o usuário e fazer com que ele leia as notícias atuais do gRPC-Gateway.
• Página de blogs, notas de lançamento e tutoriais:
Acho que o site precisa ter uma opção de blog. Assim, as notícias e lançamentos podem ser comunicados com facilidade. A página do tutorial contém algumas apresentações e artigos populares que esclarecem os conceitos e APIs do gRPC-Gateway. Os colaboradores podem adicionar links para os tutoriais na página do tutorial.
Depois de concluir a tarefa acima, atualize as mesmas mudanças na ramificação v2 e faça isso mesmo com a ramificação mestre do gRPC-Gateway.
OBJETIVO SECUNDÁRIO DESTE PROJETO:-
Outras mudanças precisam ser feitas para tornar a documentação do gRPC-Gateway mais robusta e legível:
• Correção de erros gramaticais e tipográficos, além de organização e alinhamento de links e postagens no site em todos os arquivos existentes do gRPC-Gateway.
• Adicionar mais documentação e conteúdo, se necessário, no gRPC-Gateway, já que a maioria dos recursos tem uma documentação muito curta, como na seção "Documentação" do site na AWS, em "Contexto" e "Uso", etc.
• Refactoring Go snippets gRPC-Gateway de acordo com os formatos Gofmt
Depois de concluir a tarefa acima, atualize as mesmas mudanças na ramificação v2 e faça isso mesmo com a ramificação mestre do gRPC-Gateway.
POR QUE EU SOU A PESSOA CERTA PARA ESTE PROJETO:
Acredito que sou a pessoa certa para este projeto porque:-
• Tenho experiência anterior na melhoria da documentação de organizações e posso usar qualquer sistema de controle de versões. Portanto, executar comandos no GitHub não será um problema. • Além disso, o que me motiva é trabalhar em projetos que geram valor para as pessoas. Eu acredito que se você quer que alguém faça algo da maneira mais eficiente possível, você documenta isso. Ao documentar seus processos, você garante eficiência, consistência e tranquilidade para todos os envolvidos. • Estou familiarizado com o fluxo de trabalho e a base de código do gRPC-Gateway, já que estou contribuindo para o gRPC-Gateway nos últimos dois meses e fiz a mesclagem de 11 PRs.