Progetto Bokeh

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

Riepilogo del progetto

Organizzazione open source:
Bokeh
Technical writer:
vis_verborum
Nome progetto:
Creare, leggere, condividere: ottimizzare la documentazione di Bokeh
Durata del progetto:
Durata standard (3 mesi)

Project description

Creare, leggere, condividere: ottimizzare la documentazione di Bokeh

1. Abstract

Bokeh è uno strumento estremamente potente per creare visualizzazioni interattive basate su browser con Python. Ha una base utenti considerevole (502.000 download di conda mensili, 855.000 download di PyPi) e un gran numero di collaboratori (455 su GitHub). Non sorprende che l'ampia documentazione di Bokeh sia cresciuta in modo organico. Quindi, in alcuni punti è incoerente, difficile da accedere e contorto.

La stagione dei documenti di Google offre un'opportunità unica per una revisione e una revisione focalizzata della struttura e dei contenuti della documentazione di Bokeh, e per assicurarsi che la documentazione e gli strumenti e i flussi di lavoro associati siano a prova di futuro.

Ho codificato e documentato progetti open source con Python e Sphinx (più recentemente: PyZillow e PyPresseportal). Ma ciò che mi rende un partecipante unico della stagione dei documenti di Google è la mia formazione nel giornalismo: ho lavorato nelle redazioni per più di 13 anni, e molti anni come caporedattore e sostenitore del cambiamento digitale. Oltre alle mie mansioni giornalistiche, avevo crescenti responsabilità nella progettazione e nella documentazione di nuovi strumenti digitali e guide di stile, oltre a formare il personale della redazione.

Dopo un recente trasferimento dall'Europa agli Stati Uniti, ho deciso di esplorare nuovi modi di unire il mio entusiasmo per la comunicazione e la programmazione. Ritengo che la scrittura tecnica sia la combinazione ottimale delle mie competenze ed esperienze in scrittura e tecnologia. In questa proposta spiegherò come userò la Stagione dei documenti di Google per ottimizzare la documentazione di Bokeh: rendendo più comoda la creazione e il contributo alla documentazione, rendendo più semplice la leggere alla documentazione e semplificando la condivisione delle informazioni nella documentazione con altri utenti.

2. Situazione attuale

La documentazione ufficiale di Bokeh è costituita dalle seguenti unità principali:

  • Documentazione narrativa: guida all'installazione, guida dell'utente, guida per gli sviluppatori, note di rilascio
  • Galleria e demo (esempi interattivi con il relativo codice sorgente)
  • Guida di riferimento (documentazione basata sulle docstring)
  • Tutorial (ampia raccolta di blocchi note Jupyter, ospitata su mybinder.org)
  • Docstring e guida ai modelli per gli IDE
  • Esempi e file README nel repository del progetto

Inoltre, è disponibile un'ampia gamma di informazioni sul forum di assistenza di Bokeh e su Stack Overflow, dove gli sviluppatori di Bokeh rispondono attivamente alle domande degli utenti, nonché sul blog Medium di Bokeh.

La maggior parte delle pagine web della documentazione viene creata con Sphinx, utilizzando diverse estensioni Sphinx standard e personalizzate. La Guida di riferimento, ad esempio, è generata da docstring utilizzando estensioni come "autodoc" e "bokeh_autodoc" personalizzato. Come è la natura della documentazione generata in modo organico, contiene ridondanze e incongruenze.

Una delle prime cose che ho notato durante l'analisi della documentazione esistente è stata la mancanza di linee guida di stile chiare per la scrittura della documentazione. La guida per gli sviluppatori di Bokeh contiene alcune istruzioni di base. Tuttavia, il presente documento non contiene molte indicazioni sullo stile, in particolare per quanto riguarda la documentazione che va oltre le docstring. Di conseguenza, problemi stilistici e strutturali rendono più difficile l'accesso alle informazioni nei documenti, soprattutto per i nuovi arrivati.

Ad esempio:

La pagina di destinazione della documentazione di Bokeh è piuttosto breve e non include informazioni su tutte le risorse disponibili (non si fa menzione dell'ampia libreria di docstring e delle funzioni di assistenza del modello, dei forum di assistenza, delle demo o del blog di Medium). Inoltre, per i nuovi utenti sarà più difficile iniziare a utilizzare Bokeh.

3. Gol

Per utilizzare in modo più efficiente la fase di sviluppo del documento di undici settimane, mi concentrerò su tre elementi chiave:

3.1. Migliora la creazione dei documenti

Gran parte della documentazione di Bokeh è scritta da collaboratori che includono la documentazione come parte delle richieste di pull per nuove funzionalità e correzioni di bug. Anche se utilizzerò parte della fase di sviluppo del documento per modificare e ridefinire i documenti esistenti, mi soffermerò a rendere i flussi di lavoro per la creazione e il mantenimento della documentazione a prova di futuro: per i collaboratori dovrebbe essere il più semplice possibile mantenere uno standard costantemente elevato di documentazione.

Mi assicurerò che questo accada con due approcci:

  • Creerò una serie di linee guida sullo stile semplici e pratiche da includere nella Guida per gli sviluppatori esistente. Queste linee guida tratteranno di stile, grammatica e struttura. Inoltre, userò canali di comunicazione interni come Slack per assicurarmi che i collaboratori di Bokeh conoscano le linee guida relative allo stile. Inoltre, terrò conto di una formazione individuale e di sessioni di domande e risposte per il team.
  • Collaborerò con il team principale per trovare un set ottimale di strumenti per il controllo della qualità della documentazione, che verrà aggiunto ai flussi di lavoro esistenti di Bokeh per PR (richieste di pull) e CI (integrazione continua). A seconda dei requisiti del team, ciò potrebbe significare l'aggiunta di strumenti come il controllo ortografico pydocstyle, proselint o sphinxcontrib-spelling alla suite di test di Bokeh, alla configurazione del pre-commit o ad azioni GitHub. Ho aggiunto un proof of concept funzionante alle azioni GitHub di uno dei miei progetti open source.

3.2. Migliora la lettura della documentazione

L'obiettivo di una buona documentazione è permettere agli utenti attuali e potenziali di trovare facilmente le informazioni giuste e utilizzarle nel modo più efficiente possibile.

I fattori chiave per l'usabilità di un testo sono il suo stile e la sua struttura: scrivere documentazione in uno stile chiaro e coerente consente ai lettori di raccogliere rapidamente le informazioni, senza distrazioni e linguaggio superfluo. Una struttura semplice e trasparente della documentazione consente di trovare facilmente e rapidamente le informazioni pertinenti.

Analizzerò entrambe le aree, con particolare attenzione all'usabilità per i nuovi utenti. Includerà un esame approfondito della documentazione narrativa, incentrata sulla Guida dell'utente. Inoltre, modificherò la pagina di destinazione della documentazione per rivolgere più chiaramente i diversi segmenti di pubblico di destinazione e assicurarmi che ogni utente possa trovare rapidamente le risorse giuste.

Proprio come per il miglioramento della creazione dei documenti di cui sopra, mi concentrerò su come gettare le basi per miglioramenti futuri e continui standard elevati per la documentazione di Bokeh.

3.3. Migliora la condivisione dei documenti

Sono in corso un numero sempre maggiore di discussioni su Bokeh su piattaforme di terze parti. Molte di queste piattaforme utilizzano metadati come Open Graph di Facebook per includere anteprime estese dei link. Open Graph è utilizzato da servizi come Facebook, Twitter, LinkedIn, Slack e iMessage. Anche il forum Discourse di Bokeh utilizza Open Graph per visualizzare le anteprime dei link.

Per poter usare questa tecnologia, aggiungerò metadati alle pagine web generate dalla Sphinx di Bokeh, come descritto nel numero #9792. Il modo più efficiente sarebbe utilizzare un'estensione Sphinx dedicata. Alcuni giorni fa è stata pubblicata su GitHub una prima versione di un'estensione Sphinx per i dati di Open Graph. Utilizzerò alcune fasi della fase di sviluppo dei documenti per migliorare l'estensione da usare con la documentazione di Bokeh.

Ho anche creato una proof of concept che sto utilizzando con successo in uno dei miei progetti open source, PyPresseportal. Questa estensione raccoglie automaticamente informazioni pertinenti, come titolo, descrizione, immagine e URL. Quindi inserisce queste informazioni nel codice HTML generato da Sphinx come tag OpenGraph.

Un passo successivo nello sviluppo di questa estensione sarebbe l'introduzione di istruzioni personalizzate per definire manualmente i metadati Open Graph (simili alle direttive "meta" esistenti di docutil). I metadati generati automaticamente verranno utilizzati solo come riserva, nel caso in cui non siano disponibili dati inseriti manualmente.

Il supporto dei dati strutturati è molto più complesso, quindi mi concentrerò principalmente sull'inclusione di metadati Open Graph di alta qualità per la documentazione di Bokeh. Tutto il lavoro relativo al supporto di Open Graph, allo stesso tempo, getterà le basi per il supporto dei dati strutturati.

I membri delle community Sphinx e ReadTheDocs hanno espresso interesse nello sviluppo di estensioni per Open Graph e i dati strutturati (ad esempio nei problemi #1758 e #5208) e mi assicurerò di collaborare a stretto contatto con loro.

4. Materiali da produrre

Per riassumere, questi sono i risultati finali che mi aspetto di ottenere dalla Stagione di Documenti:

  • Linee guida relative allo stile della documentazione per i collaboratori di Bokeh
  • Flussi di lavoro di PR e CI rivisti per includere il controllo automatizzato della qualità della documentazione
  • Guida dell'utente modificata e ristrutturata
  • Pagina di destinazione della documentazione rivista
  • Metadati Open Graph inclusi nelle pagine web della documentazione e un'estensione Sphinx funzionante

Inoltre, terrò un "documento" per documentare il mio percorso attraverso la stagione dei documenti di Google sul mio sito web personale/mezzo o sul blog Medium di Bokeh. che fungerà anche da base per il report sul progetto per Google. Farò il possibile in modo trasparente, sotto forma di problemi relativi a GitHub e di richiesta di pull, ove possibile.

5. Sequenza

Prima della fase di legame tra comunità: sto già partecipando attivamente a diverse discussioni sul repository GitHub di Bokeh e sono in contatto con Bryan Van de Ven e Pavithra Eswaramoorthy, mentori di Bokeh per la Stagione dei Documenti di Google. Rimango attivo nella conversazione su Bokeh e acquisirò ulteriormente familiarità con Bokeh creando e pubblicando visualizzazioni.

Fase di svincolo comunitario (17/08 - 13/09):

  • Impara a conoscere il team principale, perfeziona il piano di progetto in cambio di mentori
  • Imposta una pianificazione e canali di comunicazione per report e feedback regolari con i mentori
  • Essere attivi su Slack di Bokeh per informare tutti i collaboratori Bokeh interessati sulla stagione dei documenti di Google e sugli obiettivi per la fase di sviluppo dei documenti
  • Raccogli il feedback dei collaboratori di Bokeh per perfezionare ulteriormente il piano per la fase di sviluppo dei documenti

Fase di sviluppo del documento

Settimana 1, 14/09 - 20/09:

  • Inizia il controllo e la modifica della documentazione narrativa
  • Inizia a stilare le linee guida relative allo stile

Settimana 2, 21/09 - 27/09:

  • Continua a lavorare sulle linee guida relative allo stile
  • Continua a modificare la documentazione narrativa
  • Inizia a rivedere la pagina di destinazione della documentazione

Settimana 3, 28/09 - 04/10:

  • Finalizza le linee guida per lo stile
  • Finalizza la pagina di destinazione della documentazione

Settimana 4, 05/10 - 11/10:

  • Finalizza la modifica della documentazione narrativa
  • Discuti con il team centrale di Bokeh l'integrazione degli strumenti per il controllo della qualità dei documenti nei flussi di lavoro PR/CI

Settimana 5, 12/10 - 18/10:

  • Organizza una sessione di domande e risposte con i collaboratori di Bokeh su Slack per discutere delle linee guida relative allo stile, dei miglioramenti alla documentazione narrativa e dei flussi di lavoro di PR/CI
  • Inizia a sviluppare il mio proof of concept esistente per i metadati Open Graph in un'estensione Sphinx di cui è possibile eseguire il deployment
  • Rivedi le linee guida relative allo stile in base al feedback ricevuto dalla sessione di domande e risposte con i collaboratori di Bokeh

Settimana 6, dal 19/10 al 25/10:

  • Inizia a testare gli strumenti per il controllo della qualità dei documenti nei flussi di lavoro di PR e CI
  • Continua lo sviluppo dell'estensione Sphinx per i metadati

Settimana 7, dal 26/10 all'01/11:

  • Test dell'estensione Sphinx
  • Seconda sessione di domande e risposte con i collaboratori Bokeh su Slack
  • Rivedere i risultati finali in base ai feedback della seconda sessione di domande e risposte

Settimana 8, 02/11 - 08/11:

  • Esegui il deployment dell'estensione Sphinx e pubblica documentazione narrativa migliorata e pagina di destinazione della documentazione

Settimana 9, 09/11 - 15/11:

  • Esegui il deployment degli strumenti di controllo della qualità dei documenti nei flussi di lavoro di PR e CI
  • Aggiorna e pubblica la Guida per gli sviluppatori per includere linee guida sullo stile e aggiunte ai flussi di lavoro PR e CI

Settimana 10, 16/11 - 22/11:

  • Finalizza le attività rimanenti

Settimana 11, dal 23/11 al 29/11:

  • Inizia a scrivere il report sul progetto
  • Inizia a scrivere la valutazione del progetto

Fase di finalizzazione del progetto

Settimana 12, 30/11 - 05/12:

  • Finalizza e invia il report sul progetto

Settimana 13, 03/12 - 10/12:

  • Finalizza e invia la valutazione del progetto

Dopo la conclusione della stagione dei documenti di Google:

  • Spero di continuare a partecipare allo sviluppo di Bokeh e di continuare a lavorare alla documentazione di Bokeh.
  • Prevedo di continuare a sviluppare un'estensione Sphinx per i metadati di Open Graph/dati strutturati.
  • Spero di poter usare le mie competenze nel giornalismo e la mia rete esistente per promuovere Bokeh come strumento nel giornalismo di precisione. Ad esempio, puoi scrivere su Bokeh pensando a un pubblico giornalistico o proporre conferenze sull'utilizzo di Bokeh in ambito giornalistico.

6. Informazioni personali

In origine sono una giornalista e sono specializzata in notizie in TV, online e radio. Lavorare come caporedattore e reporter nel settore dei notiziari televisivi e digitali mi ha dato anni di esperienza nella scrittura e nell'editing. Allo stesso tempo, ho lavorato a diversi progetti che promuovevano la trasformazione digitale e l'automazione. Ho scritto numerosi manuali riguardanti flussi di lavoro e strumenti digitali, oltre a guide di stile e strategie di comunicazione per i brand di notizie digitali. Ho anche formato i membri del team all'uso di questi strumenti.

Sono sempre stata attratta dalle intersezioni tra comunicazione e tecnologia. Mi si è aperto un mondo completamente nuovo quando ho imparato a programmare in Python: sono stato in grado di fare analisi e visualizzazione dei dati per il giornalismo di precisione, ad esempio. Imparare a programmare mi ha anche permesso di collaborare attivamente con gli ingegneri del software per sviluppare strumenti digitali per i flussi di lavoro delle redazioni.

Purtroppo i manuali e i documenti che ho scritto nel mio lavoro precedente non sono pubblici. Pertanto, ora mi sto concentrando su un coinvolgimento maggiore con i progetti open source (vedi di seguito per alcuni esempi). Ho basato il mio lavoro per la scrittura tecnica su guide di stile come la guida di stile della documentazione per gli sviluppatori di Google e la guida di stile Microsoft. Utilizzo regolarmente GitHub, Slack e Linux. Ho scritto documenti narrativi, docstring e suggerimenti di digitazione, utilizzando strumenti come Sphinx, Mypy e Sphinx autodoc.

Attualmente lavoro come freelance. Il mio programma offre la flessibilità necessaria per lavorare sulla documentazione di Bokeh per circa 25 ore alla settimana durante la fase di sviluppo dei documenti. Lavoro nel fuso orario del Pacifico, ma sono felice di soddisfare i programmi e le esigenze del team.

7. Esempi di documentazione open source recenti

  • PyZillow: PyZillow è un wrapper Python per l'API del sito web immobiliare Zillow.com. Oltre a fornire codice e agire in qualità di responsabile della manutenzione del codice, ho scritto la documentazione completa. Ho usato Sphinx per la documentazione narrativa e per i riferimenti al modulo. Ho creato il riferimento al modulo con l'estensione Sphinx autodoc, in base alle docstring che ho aggiunto al codice.

  • PyPresseportal: PyPresseportal è un wrapper Python per l'API del sito web presseportal.de. Il sito web presseportal.de è uno dei maggiori distributori di comunicati stampa e annunci di investitori in Germania. Ad esempio, quasi tutte le forze dell'ordine e i vigili del fuoco utilizzano questo servizio per distribuire i propri comunicati stampa. Dopo aver utilizzato l'API per molti anni come giornalista, ho deciso di sviluppare un'interfaccia Python per accedere alle ampie risorse di dati del sito web come oggetti Python. Ho scritto il codice e l'intera documentazione basata su Sphinx.