Progetto SciPy

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

Riepilogo progetto

Organizzazione open source:

SciPy

Redattore tecnico:

mkg33

Nome progetto:

Documentazione orientata agli utenti e ristrutturazione approfondita

Durata del progetto:

Durata standard (3 mesi)

Project description

Motivazione:

Ho intenzione di lavorare al refactoring della documentazione esistente, in modo che sia facilmente accessibile agli utenti con esigenze diverse. È ovvio che un ricercatore è molto probabilmente interessato a funzionalità avanzate e sofisticate, mentre un utente senza esperienza pregressa apprezza guide e diagrammi passo passo.

Mi interessa portare avanti questo progetto per motivi personali e professionali: innanzitutto, vorrei dare un contributo significativo a SciPy perché la mia ricerca ne ha beneficiato molto e, in secondo luogo, trovo spesso documentazione insufficiente (o mancante) in altri software e mi chiedo sempre quanto più velocemente (se del tutto) gli utenti potrebbero imparare a utilizzare il codice se avessero a disposizione una guida completa.

Obiettivi:

Il mio obiettivo è migliorare la documentazione esistente di SciPy sia per quanto riguarda i contenuti che le immagini. La caratteristica più importante del mio approccio a questo problema è l'implementazione e l'analisi del sondaggio degli utenti, ovvero un sondaggio conciso condotto online che consente a vari utenti di esprimere le proprie esigenze in merito alla documentazione. Sono fermamente convinto che le loro opinioni debbano essere fonte di ispirazione (in che altro modo possiamo creare una documentazione più user-friendly?).

Per quanto riguarda la realizzazione del progetto stesso, la prima fase prevede la progettazione e l'analisi del sondaggio degli utenti, nonché l'affrontare diversi problemi stilistici che ho notato nella documentazione attuale. Ad esempio, mancanza di coerenza (ad es. array 2D che si verificano insieme ad array 2D), frasi complicate che devono essere riscritte o mancanza di ordine alfabetico in determinate sottopagine. La seconda fase si concentrerà sull'introduzione di guide grafiche contenenti link ipertestuali agli argomenti pertinenti (in base ai risultati del sondaggio e ad altre richieste della community). A lungo termine, vorrei ottenere una documentazione soddisfacente, personalizzata per diversi tipi di utenti. Inoltre, cercherò di rendere i tutorial più coerenti sia dal punto di vista linguistico che strutturalmente. Infine, ho intenzione di scrivere nuovi tutorial (in base alle esigenze attuali della community).

Sondaggio tra gli utenti:

Per quanto riguarda il sondaggio degli utenti, ti propongo di utilizzare Moduli Google per diversi motivi. Innanzitutto, Moduli Google è senza costi e offre funzionalità illimitate (in termini di numero di intervistati, domande e così via), ha un aspetto visivo 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 a fini di analisi statistica. Da una ricerca online risulta che Moduli Google è, almeno per ora, il miglior strumento senza costi per condurre sondaggi. Su un tono meno serio, sarebbe un bel gesto utilizzare un prodotto Google in un'iniziativa gestita da Google.

Ho creato un sondaggio preliminare con 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 soffrano di un'elevata dispersione). Devono essere presenti al massimo due domande a risposta aperta, altrimenti i risultati saranno molto dispersi e non saranno utili. Ritengo che anche un numero molto elevato di risposte non sia problematico perché i dati possono essere facilmente esportati e analizzati in modo automatico con il software statistico. Supponendo che il numero di risposte sia effettivamente molto elevato, l'analisi delle domande a risposta aperta potrebbe richiedere un po' di tempo, ma presumo che non sarà eccessiva. Dopotutto, un utente medio non è propenso a scrivere un saggio sullo stato della documentazione. Nel peggiore dei casi, alcune risposte possono essere semplicemente memorizzate per analisi future.

Guide grafiche:

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

Per quanto riguarda i dettagli di implementazione, propongo di utilizzare il pacchetto TikZ. Innanzitutto, è uno strumento potente e non sembra essere a rischio di essere presto deprecato. Offre inoltre output di alta qualità, ha una documentazione davvero solida ed è un argomento frequente su TeX StackExchange e su altri forum mainstream. Soprattutto, l'integrazione di un file TikZ (più precisamente, i numerosi link ipertestuali al suo interno) con la documentazione HTML non sembra presentare problemi significativi grazie all'esistenza di vari pacchetti e correzioni per l'inserimento di un'immagine TikZ in HTML (ad esempio TeX4ht).

La questione della manutenzione futura delle guide in SciPy può essere facilmente risolta utilizzando, ad esempio, Overleaf (che facilita la collaborazione e offre un'anteprima istantanea) e i modelli predefiniti che fornirò. Fondamentalmente, le guide grafiche non saranno probabilmente molto diverse l'una dall'altra. La struttura, la tavolozza dei colori e le forme saranno, più o meno, invarianti, pertanto una successiva rimodellamento e un'ulteriore personalizzazione non saranno un problema.

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