Projeto GenPipes

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

Project description

Estou propondo um plano de 3 etapas para atingir o objetivo de configurar a documentação do GenPipes em 'Ler os documentos'.

Etapa 1: PoC

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

    • Identificar informações ausentes ou imprecisões
    • Sugira novos temas para documentos (se necessário)
    • Elaborar um mapa da arquitetura da informação para atender ao público-alvo, com foco nos novos usuários.

    Observação: durante esta etapa, talvez precisemos de entradas de mentores do GenPipes sobre uma nova configuração do repositório do GitHub em que documentos do Genpipes para RTD possam ser hospedados. Este repositório do GitHub pode ser usado para importar todos os documentos em pipelines de build RTD. Isso pode exigir insights sobre as regras do repositório do GenPipes e as diretrizes de gerenciamento de fontes de documentos, se necessário. Caso contrário, os padrão podem ser usados, afaik. Além disso, para o PoC, posso demonstrar um exemplo de configuração do repositório RTD usando minha conta do GitHub (por exemplo, https://gpdocs.readthedocs.io/en/latest/ – este é um exemplo que criei para esta proposta)

  • Com base na revisão e análise da etapa anterior, crie um esqueleto básico da estrutura / índice proposto da Documentação do GenPipes e coloque-o no local do RTD

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

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

    Durante a fase de avaliação do GSoD do GenPipes, tentei gerar valor para o GenPipes com esta amostra hospedada no RTD. Esse recurso é apenas para fins de demonstração, é um link protegido e ainda não está listado publicamente no RTD. Essa demonstração pode ser usada para dar início aos esforços de RTD do GenPipes, mesmo que eu não seja incluído na lista selecionada. Já verifiquei as fontes no repositório c3g/GenPipes do GitHub. Os mentores, Rola e Hector gostaram da discussão de "compartilhamento de tela" do Skype mais cedo, e achei que os deuses do GSoD também queriam ver. Está tudo pronto por enquanto, mas pretendo atualizá-lo quando houver tempo até 30 de julho.

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

Etapa 2: criar um conjunto de documentos do GenPipes Doc v0.9

  • Identifique quais documentos atuais ou existentes do GenPipes podem ser importados, vinculados ou convertidos à documentação baseada no Sphinx/primeiro para hospedagem em RTD, mantendo os cronogramas de GSoD em mente

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

    • Importe este documento inicial definido em ReadTheDocs como prova de conceito. Hospede-o como um repositório protegido. Faça uma observação antecipadamente sugerindo que os novos usuários acessem a documentação original do GenPipes até que a revisão/mudança formal seja aprovada.

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

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

  • Preencha os detalhes da nova estrutura de documento proposta do GenPipes no TOC do GenPipes. Adicione outros documentos além dos primeiros (GenPipes Readme), Concepts, tutoriais etc.

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

  • Sugira e discuta um processo de trabalho com automação parcial por RTD (builds da sphinx) sobre como o conjunto de documentos do GenPipes pode ser mantido, editado pelos usuários e se a C3G permitirá 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 nos documentos do GenPipes.

Relatório

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

Outras ideias

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

Além disso, eu sugiro outra ideia de proposta de projeto: a criação de um resumo de páginas do GenPipes 3 que facilita a integração. Hoje, os novos usuários precisam se preocupar muito antes de começar a usar o GenPipes, já que a documentação é boa, mas esparsa e não é adequada para os novos usuários. Não sei se isso pode ser feito em três meses, mas gostaria de tentar.

Confira essa mesma proposta e como ela surgiu (histórico) em https://drive.google.com/file/d/1oKVp_7ZeYGMxhynfc97qUUcGNh2CNbX0/view?usp=sharing