Progetto SciPy

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

Riepilogo del progetto

Organizzazione open source:

SciPy

Technical writer:

mkg33

Nome progetto:

Documentazione orientata all'utente e completa ristrutturazione

Durata del progetto:

Durata standard (3 mesi)

Project description

Motivazione:

Intendo lavorare al refactoring della documentazione esistente, in modo che sia facilmente accessibile da utenti con esigenze diverse. Inutile dire che un ricercatore è molto probabilmente interessato a funzioni avanzate e discrete, mentre un utente senza esperienza predilige le guide e i diagrammi passo passo.

Sono interessato a portare avanti questo progetto per motivi personali e professionali: prima di tutto, vorrei contribuire in modo significativo a SciPy perché la mia ricerca ne ha tratto enorme vantaggio e in secondo luogo, troppo spesso, mi imbatto in una documentazione insufficiente (o assente) in altri software e mi chiedo sempre quanto gli utenti possano imparare a utilizzare il codice molto più velocemente se avessero ricevuto una guida completa.

Obiettivi:

Il mio obiettivo è migliorare la documentazione esistente di SciPy sia a livello di contenuti che di grafica. La caratteristica più importante del mio approccio a questo problema è l'implementazione e l'analisi del sondaggio tra gli utenti, ovvero un conciso sondaggio online che consente a vari utenti di esprimere le proprie esigenze in merito alla documentazione. Credo fermamente che le loro opinioni debbano essere fonte di ispirazione (in quale altro modo possiamo creare una documentazione più facile da usare?).

Per quanto riguarda la realizzazione del progetto stesso, la prima fase comporterà la progettazione e l'analisi del sondaggio per gli utenti, oltre ad affrontare diversi problemi stilistici che ho notato nella documentazione attuale. Ad esempio, mancanza di coerenza (ad esempio, array bidimensionali presenti insieme a matrici bidimensionali), frasi contorte che andrebbero riscritte o mancanza di ordine alfabetico in alcune sottopagine. La seconda fase sarà incentrata sull'introduzione di guide grafiche contenenti link ipertestuali agli argomenti pertinenti (basati sui risultati del sondaggio e su altre richieste della community). Nel lungo periodo, vorrei ottenere una documentazione soddisfacente, fatta su misura per diversi tipi di utenti. Inoltre, cercherò di rendere i tutorial più coerenti sia linguistici che strutturali. Ultimo ma non meno importante, il mio obiettivo è scrivere nuovi tutorial (in base alle attuali esigenze della community).

Sondaggio per gli utenti:

Per quanto riguarda il sondaggio, propongo di usare Moduli Google per diversi motivi. Innanzitutto, Moduli Google è senza costi e offre funzionalità illimitate (in termini di numero di partecipanti, domande ecc.), ha una forma visiva accattivante, le opzioni di sondaggio più utili (ad esempio la scala lineare personalizzabile, le caselle di controllo e la scelta multipla) e, soprattutto, i risultati possono essere facilmente esportati ai fini dell'analisi statistica. Sulla base di ricerche online, sembra che Moduli Google sia, almeno per il momento, il migliore strumento senza costi per condurre sondaggi. Nota meno seria, sarebbe un bel gesto utilizzare un prodotto Google nell'ambito di un'iniziativa gestita da Google.

Ho creato un sondaggio preliminare con alcune domande di esempio (puoi accedervi all'indirizzo https://docs.google.com/forms/d/e/1FAIpQLSeBAO0UFKDZyKpg2XzRslsLJVHU61ugjc18-2PVEabTQg2_6g/viewform). Un numero ragionevole di domande nella versione finale dovrebbe essere compreso tra dieci e quindici. Per ottenere risultati concreti, suggerisco di utilizzare principalmente domande a scelta multipla, una scala lineare e alcune caselle di controllo. Tuttavia, la scala lineare non deve assomigliare a uno spettro completo (causa solo confusione ed è probabile che i risultati risentano di un'elevata dispersione). Dovrebbero esserci al massimo due domande a risposta aperta, altrimenti i risultati saranno molto distribuiti e per niente utili. Ritengo che anche un numero molto elevato di risposte non sarebbe problematico perché i dati possono essere facilmente esportati e analizzati automaticamente con software statistici. Supponendo che il numero di risposte sia, in effetti, molto alto, l'analisi delle domande aperte potrebbe richiedere un po' di tempo, ma presumo che non sarà eccessivo. Dopotutto, è improbabile che un utente medio scriva un saggio sullo stato della documentazione. Nel peggiore dei casi, alcune risposte possono essere semplicemente memorizzate per un'analisi futura.

Guide grafiche:

La mia visione delle guide grafiche (intese a fungere da strumenti di navigazione) si basa su una premessa popolare secondo cui gli esseri umani (la maggior parte) sono più bravi nell'elaborare strutture visive semplici piuttosto che puramente testuali. Inoltre, un diagramma tematico con linee che collegano argomenti di interesse simili è senza dubbio una risorsa preziosa per gli utenti meno esperti (e non solo).

Per quanto riguarda i dettagli di implementazione, propongo di utilizzare il pacchetto TikZ. Innanzitutto, si tratta di uno strumento potente e non sembra rischiare di essere ritirato a breve. Offre inoltre output di alta qualità, ha una documentazione davvero solida ed è un argomento frequente su TeX StackExchange e altri forum mainstream. Ancora più importante, l'integrazione di un file TikZ (più precisamente, i numerosi collegamenti ipertestuali presenti al suo interno) con la documentazione HTML non sembra porre problemi significativi dovuti all'esistenza di vari pacchetti e correzioni per incorporare un'immagine TikZ in HTML (ad esempio, TeX4ht).

La questione della futura manutenzione delle guide all'interno di SciPy può essere facilmente risolta utilizzando, ad esempio, Overleaf (favorisce la collaborazione e offre un'anteprima istantanea) e i modelli predefiniti che fornirò. In sostanza, le guide grafiche non sono molto diverse tra loro. La struttura, la tavolozza dei colori e le forme saranno più o meno invarianti, pertanto la successiva ristrutturazione e l'ulteriore personalizzazione non saranno un problema.

Puoi consultare la versione completa della proposta, disponibile nella cartella GSoD condivisa.