Progetto GenPipes

Questa pagina contiene i dettagli di un progetto di scrittura tecnica accettato per la stagione dei documenti Google.

Riepilogo del progetto

Organizzazione open source:
GenPipes
Technical writer:
shaloo
Nome progetto:
Configura i documenti di GenPipes alla pagina "Read The Docs" (Leggi i documenti)
Durata del progetto:
Durata standard (3 mesi)

Project description

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

Passaggio 1: PDC

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

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

    (Nota: durante questo passaggio, potremmo anche aver bisogno di input dei mentori di GenPipes relativi a una nuova configurazione del repository GitHub in cui possono essere ospitati i documenti 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 dei repository GenPipes e linee guida per la gestione delle origini dei documenti, se necessario. Altrimenti si possono usare quelli standard, facci sapere. Inoltre, per PDC, posso eseguire la demo di una configurazione di 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 / l'indice della documentazione GenPipes proposto e presentalo sul sito di RTD

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

  • Rivedi / ottieni l'approvazione per lo scheletro essenziale TOC

    Durante la fase di valutazione di GenPipes GSoD, ho provato a creare valore per GenPipes attraverso questo campione ospitato presso RTD. Tieni presente che questi contenuti sono solo a scopo dimostrativo, per il link protetto non sono ancora disponibili pubblicamente su RTD. Questa demo può essere utilizzata per avviare le attività di RTD di GenPipes, indipendentemente dal fatto che io resti nella lista dei preferiti. Ho già controllato le sorgenti nel repository GitHub di c3g/GenPipes. Alle mentore, Rola ed Ettore, è piaciuto durante la discussione su "Condividi schermo" di Skype di prima, così ho pensato che anche GSoD Gods volesse vederlo. Per ora è uno scheletro essenziale, ma ho intenzione di aggiornarlo quando il tempo lo consente, fino al 30 luglio.

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

Passaggio 2: creazione di documenti GenPipes Doc v0.9

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

  • Converti i documenti identificati nel primo formato, se necessario, creane di nuovi ove applicabile e riutilizza qualsiasi cosa possibile / pertinente.

    • Importa questo documento iniziale impostato in ReadTheDocuments come Proof of Concept e ospitalo lì come repository protetto. Scrivi una nota in primo piano che suggerisci ai nuovi utenti di consultare la documentazione originale di GenPipes fino a quando non sarà possibile procedere con il passaggio di revisione/formale.

  • Rivedi/correggi/aggiorna il corso

Passaggio 3: perfeziona, esamina e pubblica la prima bozza durante la fase di RTD

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

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

  • Suggerisci di discutere un processo di lavoro con automazione delle parti tramite RTD (build di sphinx) su come il documento GenPipes può essere gestito, modificato dagli utenti e se C3G lo consentirà a collaboratori esterni di 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 PR nei documenti GenPipes.

Segnala

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

Altre opinioni

In futuro (oltre i 3 mesi), se applicabile, posso aiutarti a mantenere questa condizione per GenPipes a lungo termine. Oppure, se necessario, addestra altri utenti allo stesso modo. Possiamo calcolare questo valore in base ai risultati dei primi 3 mesi.

Suggerirei anche un'altra idea per la proposta di progetto: creare un briefing su GenPipes 3 che facilita l'onboarding. Oggi, un nuovo utente deve fare dei salti mortali prima di poter iniziare a utilizzare GenPipes, poiché la documentazione è buona, ma sparsa e non favorisce i nuovi utenti. Non so se questo può essere fatto entro 3 mesi, ma vorrei provare a fare un tentativo.

Puoi consultare la stessa proposta e il modo in cui è nata (cronologia) anche all'indirizzo https://drive.google.com/file/d/1oKVp_7ZeYGMxhynfc97qUUcGNh2CNbX0/view?usp=sharing