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:
- Gateway do gRPC
- Redator técnico:
- iamrajiv (em dinamarquês)
- Nome do projeto:
- Refatoração do site do Documentos Google do gRPC-Gateway
- Duração do projeto:
- Duração padrão (3 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. O bom site de documentos do usuário é muito importante porque fornece um caminho para os usuários aprenderem como usar o software, seus recursos, dicas, truques e também resolver problemas comuns encontrados ao usar o software. Isso também reduz o custo de suporte e faz parte da identidade corporativa do produto. Um bom site de documentos do usuário é um sinal de integridade do produto, a equipe de desenvolvedores. Sem um bom site de documentação, um usuário pode não saber como fazer as coisas acima de forma eficaz e eficiente. Um site de documentos do usuário pode desempenhar um papel essencial para garantir o sucesso de um produto, pois uma boa comunicação é e sempre será o centro de qualquer negócio ou produto, e uma ótima documentação apenas usa essa comunicação e a coloca em uma estrutura gerenciável que todos podem acessar para o sucesso.
No momento da elaboração deste artigo, o repositório gRPC-Gateway foi bifurcado cerca de 1.200 vezes, e 184 pessoas contribuíram com ele. Isso mostra que muitas pessoas no mundo todo usam o gRPC-Gateway e talvez queiram ler a documentação do usuário para receber 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, e a comunidade gRPC-Gateway quer usar esse projeto para refatorar o site de documentos existente e melhorar seu site de documentos para permitir que os usuários finais tenham uma experiência perfeita 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 que apresenta estilo e estrutura do site e tema usado obsoleto, incompleto, difícil de navegar ou encontrar informações e não abrange muitos recursos do site de bons documentos. A refatoração do site do Google Docs existente do gRPC-Gateway incluirá o estilo do site, a adição de recursos como 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 das imagens existentes criando um novo etc. Esse será meu objetivo principal, e meu trabalho será mais baseado no estilo e na reestruturação de sites do Documentos.
• O segundo problema é a necessidade de refatorar a documentação, os tutoriais, os exemplos etc. do gRPC-Gateway. Isso pode ser feito removendo erros tipográficos e gramaticais dos arquivos, fazendo o alinhamento adequado dos snippets Go e refatorando os snippets de Go de acordo com os formatos do 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. Esta é minha meta secundária e farei isso depois que eu concluir minha meta principal, ou seja, estilizar e reestruturar o site do Documentos Google.
POR QUE MEU SITE DE DOCUMENTOS PROPOSTO É UMA AUMENTO EM RELAÇÃO AO ATUAL?
O site dos documentos do usuário proposto será estruturado para melhorar e garantir eficiência, consistência e tranquilidade para o usuário final. Ele terá uma aparência melhor e a interface do usuário com seções e recursos bem estilizados contêm guias escritos e seus fluxogramas e imagens associados.
A documentação do gRPC-Gateway fornece uma boa descrição do método e do exemplo. No entanto, ele ainda usa o tema antigo do Jekyll, e os temas atuais do modelo SSG são melhores do que o gerador de sites estáticos (SSG, na sigla em inglês). 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 ROTEIRO DOS METAS E IDEIAS PROPOSTAS:
OBJETIVO PRINCIPAL ESTE PROJETO:
As metas e ideias acima podem ser implementadas das seguintes maneiras:-
Mudando o tema de Jekyll atual para um tema melhor e mais robusto. O motivo para usar os temas Jekyll novamente é que será fácil para os mantenedores contribuir e entender o fluxo de trabalho do projeto, já que eles já estão cientes da estrutura e do tema do Jekyll existentes, que são semelhantes ao novo tema do Jekyll.
Depois de analisar diferentes temas Jekyll pela Internet, achei este https://idimprovebewriting.com/document-theme-jekyll/ pacote de temas melhor para o site de documentos do gRPC-Gateway por causa do 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 para a página no GitHub) para melhorar. Isso incentiva os usuários a adicionar novos conteúdos ou editar para fazer melhorias.
• Pesquisa de documentação: o usuário deve ter uma caixa de pesquisa para encontrar conteúdo relevante de maneira fácil e rápida.
• Seção de comentários:- O usuário pode comentar e compartilhar opiniões em postagens e tutoriais. Eles podem ler as opiniões de outras pessoas sobre a documentação do projeto.
• Novas notas de versão e blogs:- O site deve ser atualizado com novas postagens de blog e notícias sobre o desenvolvimento e o roteiro atuais. Então, o tipo de blog deve estar presente na página de destino.
• Desenvolvimento rápido: a maioria dos frameworks do gerador estático de sites (SSG, na sigla em inglês) é executada 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 deve ser fácil. No futuro, se quisermos mudar a estrutura, vamos usar. Depois, deve ser fácil. A maioria das estruturas oferece suporte à gravação em Markdown, portanto, apenas mover os arquivos .md e poucas alterações devem ser suficientes.
Aqui, estou dividindo as páginas do site existentes em novas seções e páginas :
• Página de destino:-
A página de destino deve destacar os principais recursos do gRPC-Gateway.
- Primeiros passos com o gRPC-Gateway (redirecionamento para o guia do usuário)
- Instruções simples de instalação (comandos breves)
- Por que usar o gRPC-Gateway
- Projeto usando gRPC-Gateway
Portanto, a ideia básica é, em vez de escrever uma descrição longa, mostrar os pontos principais na página de destino e fornecer o link para mais detalhes.
• Página do guia do usuário do gRPC-Gateway:-
- Guia de instalação.
- Guia de início rápido sobre o gRPC-Gateway.
• Página do guia do desenvolvedor gRPC-Gateway:-
guia de desenvolvimento, guia de contribuição, configuração do Git, código de conduta, configuração de documentação, fluxo de trabalho de desenvolvimento etc. estão apontando para páginas semelhantes. Portanto, é necessário refatorar e reorganizar todos os arquivos. A página de desenvolvimento principal deve conter todas essas páginas e o hiperlink será criado em cada etapa.
• Sobre a página gRPC-Gateway:-
A lista de todos os colaboradores deve estar presente nas seções da equipe Links rápidos e notas da versão, os blogs mais recentes serão adicionados para envolver o usuário e fazer com que ele leia sobre as notícias atuais do gRPC-Gateway.
• Blogs, notas de versão e página de tutoriais:-
Acho que o site deveria ter uma opção de blog. Assim, notícias e lançamentos podem ser facilmente comunicados. A página do tutorial conterá algumas palestras e artigos mais acessados que esclarecem os conceitos e as APIs gRPC-Gateway. Os colaboradores podem adicionar os links deles à página do tutorial.
Depois de concluir a tarefa acima, atualize as mesmas alterações na ramificação v2 e faça mesmo com a ramificação mestre do gRPC-Gateway.
OBJETIVO SECUNDÁRIO DESTE PROJETO:
Outras alterações precisam ser feitas para tornar a documentação do gateway do gRPC mais robusta e legível:
• Corrigir erros gramaticais e tipográficos, além de organizar e alinhar 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 documentação muito curta, como na seção de documentação do site sobre AWS, segundo plano e uso etc.
• Refatoração de snippets Go no gRPC-Gateway de acordo com os formatos do Gofmt
Depois de concluir a tarefa acima, atualize as mesmas alterações na ramificação v2 e faça mesmo com a ramificação mestre do gRPC-Gateway.
POR QUE SOU A PESSOA CERTA PARA ESTE PROJETO:
Acredito que sou a pessoa certa para este projeto porque:-
• Tenho experiência anterior em melhoria da documentação de organizações e posso usar qualquer sistema de controle de versão. Portanto, executar comandos no GitHub não será um problema. • Além disso, o que me move é trabalhar em projetos que criam valor para as pessoas. Acredito que se você quer que alguém faça algo da maneira mais eficiente possível, 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, pois contribuo com o gRPC-Gateway dos últimos dois meses e 11 RP mesclados.