Projeto GenPipes

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:
GenPipes
Redator técnico:
shaloo
Nome do projeto:
Configure os documentos do GenPipes em "Read The Docs"
Duração do projeto:
Duração padrão (três meses)

Project description

Estou propondo um plano de três etapas para alcançar o objetivo de configurar a documentação do GenPipes no "Read The Docs".

Etapa 1: PoC

  • Analisar a documentação atual do GenPipes como um novo usuário / pesquisador

    • Identificar informações ausentes e imprecisões
    • Sugerir novos tópicos de documentos (se necessário)
    • Esboçar um mapa de arquitetura da informação para abordar o público-alvo, com foco em novos usuários.

    Observação: durante essa etapa, também podemos precisar de informações dos mentores do GenPipes sobre a configuração de um novo repositório do GitHub, onde os documentos do GenPipes para RTD podem ser hospedados. Este repositório do GitHub pode ser usado para importar todos os documentos nos pipelines de compilação de RTD. Isso pode exigir insights sobre as regras do repositório do GenPipes e as diretrizes de gerenciamento de origem de documentos, se necessário. Caso contrário, os padrões podem ser usados. Também para a PoC, posso demonstrar uma configuração de repositório de RTD de exemplo usando minha conta do GitHub, por exemplo, https://gpdocs.readthedocs.io/en/latest/ (em inglês). Esse é um exemplo que criei para essa proposta.

  • Com base na revisão e análise da etapa anterior, criar um esqueleto básico de proposta de estrutura / índice de documentação do GenPipes e colocá-lo no site da RTD

    • Isso envolve a criação de repositórios do GitHub (com ferramentas Sphinx, por exemplo) e arquivos de documentação básicos.
    • Isso também envolve a criação de um novo TOC que leva em consideração os novos usuários e os usuários experientes em várias seções / fluxos de informações.

  • Revisar / receber aprovação no esqueleto de TOC do barebones

    Durante a fase de avaliação do GSoD do GenPipes, tentei criar valor para o GenPipes usando este exemplo hospedado no RTD. Este é um link protegido para fins de demonstração, que ainda não está listado publicamente no RTD. Independentemente de eu ser incluído na lista selecionada, esta demonstração pode ser usada para impulsionar a iniciativa GenPipes RTD. Já verifiquei as origens no repositório do GitHub c3g/GenPipes. Os mentores, Rola e Hector, gostaram da discussão anterior sobre o "compartilhamento de tela" do Skype, então achei que os deuses do GSoD também gostariam de ver. Por enquanto, é um esqueleto básico, mas pretendo atualizar até 30 de julho.

https://genpipes.readthedocs.io/en/latest/

Etapa 2: criação do conjunto de documentos do GenPipes Doc v0.9

  • Identifique quais documentos atuais ou existentes do GenPipes podem ser importados, vinculados ou convertidos para a documentação baseada na Sphinx/rst para hospedagem em RTD, tendo em mente os cronogramas do GSoD.

  • Converta os documentos identificados para o primeiro formato, se necessário, crie novos quando aplicável e reutilize o que for possível / relevante.

    • Importe esse conjunto inicial de documentos para o ReadTheDocs como prova de conceito e hospede-o como um repositório protegido. Faça uma observação sugerindo que novos usuários acessem a documentação original do GenPipes até que a revisão/alteração formal seja aprovada.

  • Revisão/correção de curso/atualização

Etapa 3: refinar, revisar e publicar o primeiro rascunho no RTD

  • Preencha os detalhes da nova estrutura de documentos proposta para o sumário do GenPipes. Adicione outros documentos além dos primeiros (GenPipes Readme), conceitos, tutoriais etc.

  • Adicionar uma demarcação clara no índice para abordar novos usuários, usuários experientes do GenPipes, desenvolvedores do GenPipes etc.

  • Sugerir e discutir um processo de trabalho com automação parcial usando o RTD (builds do Sphinx) sobre como o conjunto de documentos do GenPipes pode ser mantido e editado pelos usuários e se o C3G permite isso para colaboradores externos de documentos. Isso pode exigir a criação de algumas diretrizes para atualizações de documentos semelhantes às diretrizes de programação. Pode exigir mais etapas secundárias. Por exemplo, automatize a verificação ortográfica antes da aprovação de RP em documentos do GenPipes.

Denunciar

Por fim, crie um relatório para o GSoD com base nas experiências, registros e feedback dos mentores.

Outros pensamentos

No futuro (além de três meses), se aplicável, posso ajudar a manter isso para GenPipes em longo prazo. Ou treine outras pessoas, se necessário. Podemos descobrir isso com base no resultado desses três meses.

Além disso, sugiro outra ideia de proposta de projeto: a criação de um resumo de três páginas do GenPipes que ajuda na integração. Hoje, um novo usuário precisa passar por muitas etapas antes de começar a usar o GenPipes, porque a documentação é boa, mas está espalhada e não é adequada para novos usuários. Não sei se isso pode ser feito em três meses, mas gostaria de tentar.

Essa mesma proposta e como ela surgiu (histórico) também podem ser visualizadas em https://drive.google.com/file/d/1oKVp_7ZeYGMxhynfc97qUUcGNh2CNbX0/view?usp=sharing