Progetto GenPipes

Questa pagina contiene i dettagli di un progetto di documentazione tecnica accettato per la stagione della documentazione di Google.

Riepilogo progetto

Organizzazione open source:
GenPipes
Redattore tecnico:
shaloo
Nome progetto:
Configurare la documentazione di GenPipes su "Read The Docs"
Durata del progetto:
Durata standard (3 mesi)

Project description

Sto proponendo un piano in tre fasi per raggiungere l'obiettivo di impostare la documentazione di GenPipes su "Leggi la documentazione".

Passaggio 1: PoC

  • Esamina la documentazione esistente di GenPipes come nuovo utente / ricercatore

    • Identificare le informazioni mancanti o le inesattezze
    • Suggerire nuovi argomenti per i documenti (se necessario)
    • Mappa di architettura delle informazioni in anteprima per rivolgersi al pubblico di destinazione, con particolare attenzione ai nuovi utenti.

    (Nota: durante questo passaggio, potremmo aver bisogno anche del contributo dei mentori di GenPipes in merito a una nuova configurazione del repository GitHub in cui è possibile ospitare documenti di Genpipes per RTD. Questo repository GitHub può essere utilizzato per importare tutti i documenti nelle pipeline di compilazione RTD. Potrebbero essere necessari approfondimenti sulle regole del repository GenPipes e sulle linee guida per la gestione delle origini dei documenti, se necessario. In caso contrario, puoi utilizzare quelli standard, a quanto mi risulta. Inoltre, per la PoC, posso dimostrare la configurazione di un repository RTD di esempio utilizzando il mio account GitHub, ad esempio https://gpdocs.readthedocs.io/en/latest/, un sampler che ho creato per questa proposta.

  • Sulla base dei controlli e delle analisi nella fase precedente, crea uno scheletro semplice della struttura / indice della documentazione GenPipes e collocalo sul sito di RTD

    • Ciò include la creazione del repository GitHub (ad esempio con gli strumenti Sphinx) e i file di documentazione di base
    • Ciò comporta anche la creazione di un nuovo sommario che tenga conto sia dei nuovi utenti sia di quelli esperti per le varie sezioni / flussi di informazioni.

  • Esamina / ottieni l'approvazione del TOC scheletro di base

    Durante la fase di valutazione GSoD di GenPipes, ho cercato di creare valore per GenPipes tramite questo sample ospitato in RTD. Nota: questo è solo a scopo dimostrativo, link protetto, non ancora elencato pubblicamente su RTD. Indipendentemente dal fatto che venga selezionato o meno, questa demo può essere utilizzata per dare impulso all'impegno di ricerca e sviluppo di GenPipes. Ho già controllato le origini nel repository GitHub di c3g/GenPipes. I mentori, Rola ed Ettore hanno apprezzato la conversazione sulla "condivisione dello schermo" su Skype di prima, quindi ho pensato che anche GSoD Gods potrebbe volerla vedere. Per il momento è uno scheletro essenziale, ma ho intenzione di aggiornarlo, se il tempo lo consente, entro il 30 luglio.

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

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

  • Identificare quali documenti GenPipes attuali o esistenti possono essere importati, collegati o convertiti nella documentazione basata su Sphinx o sul primo per l'hosting su RTD tenendo presenti le tempistiche di GSoD

  • Converti i documenti identificati in formato RST, se necessario, creane di nuovi, se applicabile, riutilizza tutto ciò che è possibile / pertinente.

    • Importa questo set iniziale di documenti in ReadTheDocs come Proof of Concept e ospitalo lì come repository protetto. Inserisci una nota iniziale che suggerisca ai nuovi utenti di consultare la documentazione originale di GenPipes fino a quando non viene dato il via libera per la revisione/il passaggio formale.

  • Review/course-correct/update

Passaggio 3: perfeziona, rivedi e pubblica la prima bozza in RTD

  • Compila i dettagli della nuova struttura del documento GenPipes proposta nell'indice di GenPipes: aggiungi altri documenti oltre ai primi (GenPipes Readme), Concetti, Tutorial e così via.

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

  • Suggerite, discuti di un processo di lavoro con l'automazione delle parti tramite RTD (sphinx build) su come è possibile mantenere e modificare i documenti GenPipes dagli utenti e se C3G lo consentirà ai collaboratori esterni. Ciò potrebbe richiedere la creazione di alcune linee guida per gli aggiornamenti dei documenti, simili a quelle per la codifica. Potrebbero essere necessari ulteriori passaggi secondari. Ad esempio, automatizza la correzione ortografica prima dell'approvazione della RP nei documenti di GenPipes.

Segnala

Infine, crea un report per GSoD in base a esperienze, log e feedback dei mentor.

Altri pensieri

In futuro (oltre 3 mesi), se possibile, posso aiutarti a gestire la disponibilità per GenPipes a lungo termine. In alternativa, addestra altre persone, se necessario, allo stesso modo. Possiamo capirlo in base al risultato dei primi 3 mesi.

Inoltre, ti suggerisco un'idea aggiuntiva per la proposta di progetto: la creazione di un brief di GenPipes di 3 pagine che aiuti a semplificare l'onboarding. Oggi, un nuovo utente deve fare molte cose prima di poter iniziare a utilizzare GenPipes, poiché la documentazione è buona ma dispersa e non favorisce l'acquisizione di nuovi utenti. Non so se sarà possibile farlo entro tre mesi, ma vorrei provare a fare un tentativo.

Questa stessa proposta e la sua origine (storia) possono essere visualizzate anche all'indirizzo https://drive.google.com/file/d/1oKVp_7ZeYGMxhynfc97qUUcGNh2CNbX0/view?usp=sharing