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:
- Il linguaggio Julia
- Redattore tecnico:
- mkg33
- Nome del progetto:
- La documentazione unificata del machine learning scientifico
- Durata del progetto:
- Lunga esecuzione (5 mesi)
Project description
Vorrei lavorare all'unificazione dell'organizzazione SciML perché in questo ambito c'è molto spazio per miglioramenti e il completamento di questo progetto offrirà senza dubbio vantaggi immediati sia ai programmatori Julia sia ai collaboratori/maintainer attivi di SciML. I pacchetti sparpagliati in SciML offrono alcuni strumenti davvero utili, ma c'è sempre il rischio che possano passare inosservati (soprattutto dai nuovi arrivati) semplicemente perché l'utente non è riuscito a scoprire il pacchetto e ad applicarlo al problema in questione.
Questo è piuttosto frustrante, dato che lo scopo principale dei pacchetti è raggiungere un pubblico ampio di programmatori (principianti ed esperti). Per evitare la situazione descritta sopra, propongo di rivedere a fondo la "home page" della documentazione di SciML e creare una sorta di hub che gli utenti possano utilizzare per sfogliare i pacchetti correlati ed esplorare l'ecosistema in crescita. Potrebbe anche fungere da punto di riferimento prezioso per gli utenti più esperti e consentire loro di lavorare in modo più efficiente.
Innanzitutto, la documentazione esistente di tutti i singoli pacchetti deve essere rivista per quanto riguarda i problemi stilistici di base (ad esempio ortografia, punteggiatura, grammatica e così via). Per garantire la coerenza stilistica, SciML deve avere una guida di stile concreta (indispensabile per apportare modifiche a posteriori e per riferimento futuro). Sarebbe uno spreco di tempo iniziare da zero. Dovrebbe invece basarsi sulle convenzioni di Julia esistenti e includere nuove voci per i problemi specifici di SciML.
Una volta completata la guida di stile, intendo rivedere la documentazione attuale nella seconda fase del progetto. La documentazione risulterà più professionale e stabile. Ho già creato diverse richieste di pull che illustrano il mio approccio a questa attività. In questa fase, intendiamo anche concepire (e implementare) un sistema di citazioni efficiente. La prima attività sarà aggiornare la pagina delle citazioni obsolete.
La terza fase, probabilmente la più importante, prevede la progettazione della roadmap di SciML, che enfatizzerà l'interazione tra i pacchetti sparsi. Maggiore è la coesione tra due pacchetti (rispetto al problema o al codice stesso), più vicini dovrebbero apparire nell'elenco "Guarda anche". Propongo di creare due chiavi per i suggerimenti: una per la somiglianza del codice e una per la somiglianza del problema. In questo modo, gli utenti potrebbero identificare altri pacchetti potenzialmente utili molto più rapidamente rispetto alla faticosa navigazione nei rispettivi repository e nella documentazione. Anziché elencare tutte le possibili connessioni tra i pacchetti, preferisco concentrarmi su quelli più grandi e cercare di presentare i loro collegamenti con pacchetti più piccoli (questo metodo verrà esteso anche all'aggiornamento dei tutorial in cui è necessario evidenziare il collegamento con un altro pacchetto). Questo approccio garantisce che gli elenchi "Guarda anche" siano informativi senza essere enumerazioni esaustive delle combinazioni di pacchetti.