Progetto GenPipes

Questa pagina contiene i dettagli di un progetto di scrittura tecnica accettato per Google Season of Docs.

Riepilogo del progetto

Organizzazione open source:
GenPipes
Technical writer:
shaloo
Nome progetto:
Configura i documenti di GenPipes in "Leggi i documenti"
Durata del progetto:
Durata standard (3 mesi)

Project description

Propongo un piano in tre passaggi per raggiungere l'obiettivo di configurare la documentazione di GenPipes su "Leggi i documenti".

Passaggio 1: PDC

  • Esamina la documentazione esistente di GenPipes in qualità di nuovo utente / ricercatore

    • Identificare le informazioni mancanti, inesattezze
    • Suggerisci nuovi argomenti per i documenti (se necessario)
    • Prepara una mappa dell'architettura di informazioni per rivolgerti al pubblico di destinazione, con particolare attenzione ai nuovi utenti.

    (Nota: durante questo passaggio, potremmo anche aver bisogno di input dei mentori di GenPipes in merito a una nuova configurazione del repository GitHub in cui è possibile ospitare i documenti di genpipes per RTD. Questo repository GitHub può essere utilizzato per importare tutti i documenti nelle pipeline di build RTD. Ciò potrebbe richiedere insight sulle regole repository GenPipes e linee guida per la gestione dei documenti sorgente, se è necessario rispettare. Altrimenti, si possono usare quelli standard, afaik. Inoltre, per PDC, posso dimostrare la configurazione di un repository RTD di esempio utilizzando il mio account GitHub, ad esempio https://gpdocs.readthedocs.io/en/latest/.Questo è un esempio che ho creato per questa proposta.

  • In base alla revisione e all'analisi del passaggio precedente, crea uno scheletro essenziale della struttura / indice di documentazione GenPipes proposta e pubblicalo sul sito di RTD

    • Ciò comporta la creazione di repository GitHub (ad esempio con gli strumenti Sphinx) e file della documentazione di base
    • Ciò comporta anche la creazione di un nuovo sommario che tenga a mente sia i nuovi utenti che gli utilizzi più esperti per varie sezioni / flussi di informazioni.

  • Rivedi / richiedi l'approvazione del TOC sullo scheletro essenziale

    Durante la fase di valutazione di GenPipes GSoD, ho provato a creare un valore per GenPipes attraverso questo campione ospitato presso RTD. Tieni presente che questo è solo a scopo dimostrativo, link protetto e non ancora disponibile pubblicamente su RTD. Indipendentemente dal fatto che io venga selezionato, questa demo può essere utilizzata per dare slancio alle attività di RTD di GenPipes. Ho già controllato le origini nel repository GitHub di c3g/GenPipes. Ai mentori, Rola ed Ettore, è piaciuto durante la discussione di "Condividi schermo" di Skype in precedenza e così ho pensato che anche GSoD Gods potesse volerlo vedere. Per ora è essenziale, ma ho intenzione di aggiornarlo quando il tempo lo permetterà fino al 30 luglio.

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

Passaggio 2: creazione del set di documenti GenPipes v0.9

  • Identifica quali documenti GenPipes attuali o esistenti possono essere importati, collegati o convertiti in documentazione basata su Sphinx/rst per l'hosting su RTD, tenendo a mente le tempistiche di GSoD

  • Converti i documenti identificati nel primo formato, se necessario, creane di nuovi ove applicabile e riutilizza tutti i documenti possibili / pertinenti.

    • Importa questo set di documenti iniziale in ReadTheDocs come Proof of Concept e ospitalo lì come un repository protetto. Scrivi una nota in anticipo per suggerire ai nuovi utenti di accedere alla documentazione originale di GenPipes fino a quando non sarà possibile procedere con il passaggio di revisione/formale.

  • Rivedi/correggi/aggiorna/aggiorna il corso

Passaggio 3: perfeziona, rivedi e pubblica la prima bozza durante la fase di preparazione al test

  • Compila i dettagli della nuova struttura di documenti di GenPipes proposta nel sommario di GenPipes: aggiungi ulteriori documenti oltre ai primi (Leggimi di GenPipes), Concetti, Tutorial e così via.

  • Aggiungi una chiara demarcazione nel sommario per rivolgerti a nuovi utenti, utenti esperti di GenPipes, sviluppatori di GenPipes e così via.

  • Suggerite di discutere di un processo di lavoro con automazione delle parti tramite RTD (build Sphinx) su come i documenti GenPipes possono essere gestiti, modificati dagli utenti e se C3G lo consentirà ai collaboratori esterni dei documenti. Ciò potrebbe richiedere la creazione di alcune linee guida per gli aggiornamenti dei documenti, simili a quelle sulla programmazione. Potrebbe richiedere più passaggi secondari. Ad esempio, automatizza il controllo ortografico prima dell'approvazione di PR nei documenti di GenPipes.

Segnalazione

Infine, crea un report per GSoD basato su esperienze, registri e feedback dei mentori.

Altre opinioni

In futuro (oltre i tre mesi), se applicabile, posso aiutarti a mantenere questa condizione per GenPipes a lungo termine. In alternativa, addestra altri utenti a utilizzare la stessa soluzione. Possiamo determinarlo in base ai risultati dei primi 3 mesi.

Inoltre, ti suggerisco un'altra idea per la proposta di progetto: creare un briefing di GenPipes 3 su una pagina che facilita l'onboarding. Oggi, un nuovo utente deve fare molte cose prima di poter iniziare a utilizzare GenPipes, poiché la documentazione è valida ma è sparsa e non favorisce i nuovi utenti. Non so se si può fare entro 3 mesi, ma vorrei provare a fare un tentativo.

La stessa proposta e come è nata (cronologia) sono disponibili anche all'indirizzo https://drive.google.com/file/d/1oKVp_7ZeYGMxhynfc97qUUcGNh2CNbX0/view?usp=sharing