Questa pagina contiene i dettagli di un progetto di scrittura tecnica accettato per la stagione dei documenti Google.
Riepilogo del progetto
- Organizzazione open source:
- La lingua giulia
- Technical writer:
- mkg33
- Nome progetto:
- La documentazione unificata di Scientific Machine Learning
- Durata del progetto:
- Lunga esecuzione (5 mesi)
Project description
Vorrei lavorare all'unificazione dell'organizzazione SciML perché c'è molto margine di miglioramento in quest'area e il completamento di questo progetto fornirà senza dubbio benefici immediati sia ai programmatori di Julia che ai collaboratori/gestori attivi di SciML. I pacchetti disseminati in SciML offrono strumenti davvero utili, ma c'è sempre il pericolo che passino inosservati (soprattutto ai nuovi arrivati) semplicemente perché l'utente non è riuscito a trovare il pacchetto e ad applicarlo al problema in questione.
Ciò è piuttosto frustrante poiché lo scopo principale dei pacchetti è raggiungere un vasto pubblico di programmatori (principianti ed esperti). Per evitare la situazione descritta sopra, propongo di rivedere a fondo la "prima pagina" della documentazione di SciML e di creare una sorta di hub che gli utenti possano utilizzare per sfogliare i pacchetti correlati ed esplorare l'ecosistema in continua crescita. Potrebbe anche fungere da valido punto di riferimento per gli utenti più esperti e consentire loro di lavorare in modo più efficiente.
Prima di tutto, la documentazione esistente di tutti i singoli pacchetti richiede una revisione rispetto ai problemi stilistici più basilari (come ortografia, punteggiatura, grammatica, ecc.). Per garantire coerenza stilistica, SciML deve disporre di una guida di stile concreta (indispensabile per apportare modifiche retrospettive e per riferimento futuro). Ricominciare da zero sarebbe una perdita di tempo. Dovrebbe invece basarsi sulle convenzioni di Julia esistenti e includere nuovi interi per problemi specifici di SciML.
Una volta completata la guida di stile, intendo rivedere la documentazione corrente nella seconda fase del progetto. La documentazione sembrerà più professionale e stabile. Ho già creato diverse richieste di pull che illustrano il mio approccio a questa attività. In questa fase, intendo anche ideare (e implementare) un sistema di citazione efficiente. La prima attività sarà aggiornare la pagina delle citazioni non aggiornata.
La terza fase, probabilmente la più importante, riguarderà la progettazione della roadmap SciML, che metterà in evidenza l'interazione tra i pacchetti sparsi. Maggiore è la coesione tra due pacchetti (rispetto al problema o al codice stesso), più vicini dovrebbero essere visualizzati nell'elenco "vedi anche". Propongo di creare due chiavi di suggerimento: una per la somiglianza del codice e una per la somiglianza dei problemi. In questo modo gli utenti sarebbero in grado di identificare altri pacchetti potenzialmente utili molto più velocemente rispetto alla laboriosa consultazione dei rispettivi repository e della relativa documentazione. Invece di elencare tutte le possibili connessioni tra i pacchetti, preferisco concentrarmi su quelli più grandi e provare a presentare i loro link con pacchetti più piccoli (questo metodo verrà esteso anche all'aggiornamento dei tutorial in cui va sottolineata la connessione con un altro pacchetto). Questo approccio garantisce che gli elenchi "vedi anche" saranno informativi senza essere enumerazioni esaustive delle combinazioni di pacchetti.