Progetto Bokeh

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

Riepilogo del progetto

Organizzazione open source:
Bokeh
Redattore tecnico:
vis_verborum
Nome del progetto:
Creazione, lettura e condivisione: ottimizzazione della documentazione di Bokeh
Durata del progetto:
Durata standard (3 mesi)

Project description

Creazione, lettura e condivisione: ottimizzazione della 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 mensili di conda, 855.000 download di PyPI) e un numero elevato di collaboratori (455 su GitHub). Non sorprende che la vasta documentazione di Bokeh sia cresciuta in modo organico. Di conseguenza, in alcuni casi, sono incoerenti, difficili da accedere e complicate.

La stagione della documentazione di Google offre un'opportunità unica per una revisione mirata 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 adatti al futuro.

Ho codificato e documentato progetti open source con Python e Sphinx (più recentemente: PyZillow e PyPresseportal). Tuttavia, ciò che mi rende un partecipante unico della Stagione dei documenti di Google è il mio background nel giornalismo: ho lavorato nelle redazioni per più di 13 anni, molti dei quali come editore e sostenitore del cambiamento digitale. Oltre ai miei doveri giornalistici, ho assunto responsabilità crescenti nella progettazione e nella documentazione di nuovi strumenti digitali e guide di stile, nonché nella formazione del personale della redazione.

Dopo un recente trasferimento dall'Europa agli Stati Uniti, ho deciso di approfondire nuovi modi per mettere insieme il mio entusiasmo per la comunicazione e la programmazione. Ho scoperto che la scrittura tecnica è la combinazione ottimale delle mie competenze ed esperienze in ambito di scrittura e tecnologia. In questa proposta, illustrerò come utilizzerò la stagione dei documenti di Google per ottimizzare la documentazione di Bokeh: rendendo più comoda la creazione e la collaborazione alla documentazione, semplificando la lettura della documentazione e facilitando la condivisione delle informazioni al suo interno con altri.

2. Situazione attuale

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

  • Documentazione descrittiva: 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 notebook Jupyter, ospitata su mybinder.org)
  • Docstring e guida ai modelli per gli IDE
  • Esempi e README nel repository del progetto

Inoltre, è disponibile una vasta gamma di informazioni sul forum di assistenza di Bokeh e su Stack Overflow, dove lo sviluppatore di Bokeh risponde attivamente alle domande degli utenti, nonché sul blog di 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, viene generata dalle docstring utilizzando estensioni come "autodoc" e "bokeh_autodoc" personalizzate. Come è nella natura della documentazione sviluppata in modo organico, contiene ridondanze e incoerenze.

Una delle prime cose che ho notato quando analizzo la documentazione esistente è stata la mancanza di linee guida di stile chiare per la stesura della documentazione. La Guida per gli sviluppatori di Bokeh contiene alcune istruzioni di base. Tuttavia, questo documento non contiene molte indicazioni sullo stile, in particolare per quanto riguarda la documentazione che va oltre i docstring. Di conseguenza, i problemi stilistici e strutturali rendono più difficile accedere 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 (nessuna menzione dell'ampia libreria di docstring e funzioni di guida dei modelli, dei forum di assistenza, delle demo o del blog di Medium). Inoltre, rende più difficile per i nuovi utenti iniziare a utilizzare Bokeh.

3. Obiettivi

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

3.1. Migliorare la creazione dei documenti

La maggior parte della documentazione di Bokeh è scritta dai collaboratori che la includono nelle richieste pull per nuove funzionalità e correzioni di bug. Anche se utilizzerò parte della fase di sviluppo della documentazione per modificare e rifare il refactoring dei documenti esistenti, darò molta importanza alla creazione di flussi di lavoro per la creazione e la gestione della documentazione in modo che siano adatti al futuro: deve essere il più semplice possibile per i collaboratori mantenere uno standard di documentazione costantemente elevato.

Lo farò con due approcci:

  • Creerò un insieme di linee guida di stile pratiche e semplici da includere nella Guida per gli sviluppatori esistente. Queste linee guida riguardano stile, grammatica e struttura. Inoltre, utilizzerò canali di comunicazione interni come Slack per assicurarmi che i collaboratori di Bokeh siano a conoscenza delle linee guida sullo stile. Offrirò anche sessioni di formazione individuali e di domande e risposte per il team.
  • Collaborerò con il team di base per trovare un insieme ottimale di strumenti per il controllo qualità della documentazione, che verrà aggiunto ai flussi di lavoro esistenti di Bokeh per le richieste pull (PR) e l'integrazione continua (CI). A seconda dei requisiti del team, potrebbe essere necessario aggiungere strumenti come pydocstyle, proselint o sphinxcontrib-spelling alla suite di test di Bokeh, alla configurazione pre-commit o alle azioni GitHub. Ho aggiunto una proof of concept funzionante alle azioni GitHub di uno dei miei progetti open source.

3.2. Migliorare la lettura della documentazione

Lo scopo di una buona documentazione è consentire agli utenti attuali e potenziali di trovare facilmente le informazioni giuste e di poterle utilizzare nel modo più efficiente possibile.

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

Mi concentrerò su entrambe le aree, con un'enfasi sull'usabilità per i nuovi utenti. Ciò includerà un'attenta revisione della documentazione descrittiva, incentrata sulla Guida dell'utente. Inoltre, modificherò la pagina di destinazione della documentazione in modo che si rivolga in modo più chiaro ai diversi segmenti di pubblico di destinazione e assicurarmi che ogni utente possa trovare rapidamente le risorse giuste.

Come per il miglioramento della creazione della documentazione descritto sopra, mi concentrerò sulla creazione di una base per i miglioramenti futuri e per standard costantemente elevati per la documentazione di Bokeh.

3.3 Migliorare la condivisione dei documenti

Le discussioni su Bokeh si stanno moltiplicando su piattaforme di terze parti. Molte di queste piattaforme utilizzano metadati come OpenGraph di Facebook per includere anteprime avanzate dei link. OpenGraph viene utilizzato da servizi come Facebook, Twitter, LinkedIn, Slack e iMessage. Anche il forum Discourse di Bokeh utilizza OpenGraph per visualizzare le anteprime dei link.

Per utilizzare questa tecnologia, aggiungerò i metadati alle pagine web generate da Sphinx di Bokeh, come descritto nel problema #9792. Il modo più efficiente è utilizzare un'estensione Sphinx dedicata. Qualche giorno fa è stata pubblicata su GitHub la prima versione di un'estensione Sphinx per i dati OpenGraph. Utilizzerò parte della fase di sviluppo della documentazione per contribuire a migliorare questa estensione per l'utilizzo 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 sotto forma di tag OpenGraph.

Un passaggio successivo nello sviluppo di questa estensione potrebbe essere l'introduzione di direttive personalizzate per definire manualmente i metadati OpenGraph (in modo simile alle direttive "meta" esistenti di docutil). I metadati generati automaticamente vengono utilizzati solo come alternativa, 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 necessario per supportare OpenGraph, al contempo, getterà le basi per il supporto dei dati strutturati.

I membri delle community Sphinx e ReadTheDocs hanno espresso il loro interesse a sviluppare estensioni per OpenGraph e dati strutturati (ad esempio nei problemi #1758 e #5208) e mi assicurerò di collaborare strettamente con loro.

4. Materiali da produrre

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

  • Linee guida sullo stile della documentazione per i collaboratori Bokeh
  • Flussi di lavoro di PR e CI rivisti per includere il controllo automatico della qualità della documentazione
  • Guida dell'utente modificata e ristrutturata
  • Pagina di destinazione della documentazione aggiornata
  • Metadati OpenGraph inclusi nelle pagine web della documentazione e un'estensione Sphinx funzionante

Inoltre, conserverò un "doclog" per documentare il mio percorso nella stagione di Documenti di Google sul mio sito web personale/Medium o sul blog di Medium di Bokeh. Questo fungerà anche da base per il report sul progetto per Google. Eseguirò tutto il lavoro in modo trasparente, sotto forma di segnalazioni e richieste di pull GitHub, ove possibile.

5. Cronologia

Prima della fase di affiatamento con la community: partecipo già attivamente a diverse discussioni sul repository GitHub di Bokeh e ho contattato Bryan Van de Ven e Pavithra Eswaramoorthy, i mentor di Bokeh per la stagione dei documenti di Google. Rimarrò attivo nella conversazione su Bokeh e mi familiarizzerò ulteriormente con Bokeh creando e pubblicando visualizzazioni.

Fase di creazione di un legame con la community (17/08 - 13/09):

  • Conosci il team di base, perfeziona il piano di progetto in collaborazione con i mentor
  • Imposta una pianificazione e canali di comunicazione per report e feedback regolari con i mentor
  • Essere attivi sul canale Slack di Bokeh per informare tutti i collaboratori di Bokeh interessati sulla stagione dei documenti di Google e sugli obiettivi della fase di sviluppo dei documenti
  • Raccogliere feedback dai collaboratori di Bokeh per perfezionare ulteriormente il piano per la fase di sviluppo della documentazione

Fase di sviluppo del documento

Settimana 1, 14/09 - 20/09:

  • Iniziare a controllare e modificare la documentazione narrativa
  • Iniziare a redigere le linee guida per lo stile

Settimana 2, 21/09 - 27/09:

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

Settimana 3, 28/09 - 04/10:

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

Settimana 4, 10/05 - 10/11:

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

Settimana 5, 12/10 - 18/10:

  • Configura una sessione di domande e risposte con i collaboratori Bokeh su Slack per discutere delle linee guida di stile, dei miglioramenti alla documentazione narrativa e dei flussi di lavoro di PR/CI
  • Iniziare a sviluppare il mio proof of concept esistente per i metadati OpenGraph in un'estensione Sphinx di cui è possibile eseguire il deployment
  • Rivedere le linee guida per lo stile in base al feedback della sessione di domande e risposte con i collaboratori di Bokeh

Settimana 6, 19/10/25 - 25/10:

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

Settimana 7, 26/10 - 01/11:

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

Settimana 8, 11/02 - 08/11:

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

Settimana 9, 9/11 - 15/11:

  • Distribuisci gli strumenti di controllo della qualità dei documenti nei flussi di lavoro PR e CI
  • Aggiornamento e pubblicazione della Guida per gli sviluppatori per includere linee guida sullo stile e aggiunte al flusso di lavoro di PR e CI

Settimana 10, 16/11 - 22/11:

  • Completa le attività rimanenti

Settimana 11, 23/11 - 29/11:

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

Fase di finalizzazione del progetto

12ª settimana, 30/11 - 05/12:

  • Finalizzare e inviare il report del progetto

Settimana 13, 12/03 - 12/10:

  • Completare e inviare la valutazione del progetto

Al termine della stagione dei documenti di Google:

  • spero di non perdere lo sviluppo di Bokeh e di continuare a lavorare alla relativa documentazione.
  • Ho intenzione di continuare lo sviluppo di un'estensione Sphinx per i metadati OpenGraph/dati strutturati.
  • Spero di utilizzare la mia esperienza nel giornalismo e la mia rete esistente per promuovere Bokeh come strumento di data journalism. Ad esempio, scrivendo di Bokeh pensando a un pubblico giornalistico o proponendo conferenze sull'utilizzo di Bokeh in contesti giornalistici.

6. Informazioni su di me

Sono un giornalista con esperienza in notizie su TV, online e radio. Il lavoro come editor e reporter per la TV e le notizie 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 che trattano di strumenti e flussi di lavoro digitali, nonché guide di stile e strategie di comunicazione per brand di notizie digitali. Ho anche formato i membri del team all'utilizzo di questi strumenti.

Sono sempre stata attratta dagli incroci tra comunicazione e tecnologia. Ho scoperto un mondo completamente nuovo quando ho imparato a programmare in Python: ad esempio, ho potuto eseguire analisi e visualizzazione dei dati per il data journalism. Imparare a programmare mi ha anche permesso di collaborare attivamente con i software engineer per sviluppare strumenti digitali per i flussi di lavoro delle redazioni.

I manuali e i documenti che ho scritto nel mio lavoro precedente purtroppo non sono pubblici. Pertanto, ora mi sto concentrando su un maggiore coinvolgimento con i progetti open source (vedi di seguito per alcuni esempi). Ho basato il mio lavoro di Technical Writer su guide di stile come la guida di stile della documentazione per gli sviluppatori di Google e la guida di stile di Microsoft. Uso regolarmente GitHub, Slack e Linux. Ho scritto documentazioni narrative, docstring e suggerimenti sul tipo di testo, utilizzando strumenti come Sphinx, Mypy e Sphinx autodoc.

Al momento lavoro come freelance. Il mio programma offre la flessibilità necessaria per lavorare alla documentazione di Bokeh per circa 25 ore a settimana durante la fase di sviluppo del documento. Lavoro nel fuso orario del Pacifico, ma sono soddisfatto degli orari e delle 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 del codice e ad agire come uno dei gestori del codice, ho scritto la documentazione completa. Ho utilizzato Sphinx per la documentazione narrativa e per il riferimento del 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 per le relazioni con gli investitori in Germania. Ad esempio, quasi tutti i corpi di polizia 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 vaste risorse di dati del sito web come oggetti Python. Ho scritto il codice e l'intera documentazione basata su Sphinx.