Questa pagina contiene i dettagli di un progetto di scrittura tecnica accettato per la stagione dei documenti Google.
Riepilogo del progetto
- Organizzazione open source:
- ScummVM
- Technical writer:
- b-gent
- Nome progetto:
- Migliora la documentazione del codice sorgente tramite Doxygen
- Durata del progetto:
- Durata standard (3 mesi)
Project description
La documentazione attuale dell'API ScummVM (codice sorgente) è pubblicata qui: https://doxygen.scummvm.org/modules.html
Sfortunatamente, manca in molte aree:
1) Praticamente non ha una struttura, tutte le informazioni fluttuano sullo stesso livello.
2) Gli elementi C++ sono documentati in modo incoerente con alcuni di loro non affatto documentati. Questo è un aspetto che l'organizzazione menziona come uno dei problemi principali.
3) I contenuti obsoleti e deprecati vengono ancora visualizzati nell'output.
4) Il linguaggio e l'uso della codifica del doxygen dovrebbero essere resi più coerenti. È necessario un insieme di regole, che potrebbe essere una base per una futura guida di stile della documentazione per questo progetto.
5) Il CSS di doxygen utilizzato in questa pagina potrebbe essere migliorato per renderlo più simile al sito web di ScummVM: https://www.scummvm.org
Tutti questi problemi possono essere affrontati durante il progetto Season of Docs.
Questa applicazione per la stagione dei documenti è accompagnata da una bozza di PR che ho aperto nel progetto per dimostrare alcuni potenziali miglioramenti che propongo: https://github.com/scummvm/scummvm/pull/2361 Leggi la descrizione per alcuni dettagli su ciò che contiene e per visualizzare le differenze.
Questo è approssimativamente ciò che comporta il PR:
1) Penso che in questo momento ciò che più confonde i potenziali nuovi collaboratori, e in generale chiunque visualizzi l'attuale documento dell'API, sia la mancanza di struttura. L'introduzione della documentazione strutturata dell'API migliorerebbe la leggibilità, la trovabilità e, di conseguenza, l'usabilità del set di documenti. Ecco perché il mio PR introduce gruppi doxygen a tutti i file di intestazione nella cartella "common". Con questa nuova struttura, se qualcuno vuole trovare documenti per l'API relativa al sistema operativo (ad esempio), può trovarli facilmente nella navigazione.
2) È stato impostato un nuovo file di configurazione doxygen per consentire la creazione di questa documentazione.
3) Un file "links.doxyfile" da cui possono essere recuperati tutti i link utilizzati nel set di documenti. Un meccanismo utile quando si lavora con il doxygen.
4) Un CSS di ossigeno modificato. Al momento viene recuperato da un altro progetto open source ed è solo un punto di partenza. Idealmente, l'aspetto della pagina doxygen dovrebbe essere più o meno coerente con quello della pagina web di ScummVM.
Quello che il PR non tratta, ma che deve assolutamente essere lavorato sono i contenuti stessi. Intendo identificare le parti essenziali del codice che non sono documentate, quelle non sufficientemente documentate o le parti obsolete di codice che dovrebbero essere rimosse dalla documentazione. Dato che non ho mai lavorato nel progetto, per raggiungere questo obiettivo sarà necessaria la guida di un mentore.
Naturalmente, se implementiamo qualcosa dal PR dipende dalla discussione con l'organizzazione. La mia idea era che le azioni fossero più forti delle parole, quindi ho deciso di mostrare cosa posso fare invece di descriverlo solo nell'applicazione.
L'organizzazione ha fornito la seguente sequenza temporale approssimativa per questo progetto: Attività principale della settimana - Settimana 0 (prima del 14/9) Discussione e revisioni della proposta Settimana 1 (9/14) Configurazione della build Doxygen Settimana 2 (9/21) Aggiornamento di skin Doxygen (priorità bassa) Settimana 3 (9/28) Settimane comuni - Invio del codice della settimana 0 Settimana 3 (9/28) Settimane comuni - Settimane 0
L'unica modifica che vorrei proporre è iniziare lavorando alla struttura, come già accennato. Questo può essere fatto nelle settimane 1 e 2, insieme alla configurazione della compilazione del doxygen (che è in gran parte già effettuata) e al rinfrescamento della pelle Doxygen. Dopodiché, sono d'accordo sul fatto che abbia più senso passare in rassegna le diverse aree una alla volta con il tutor per identificare i problemi e migliorare la documentazione del doxygen.
Ritengo che questo sia un progetto di lunghezza standard, ma sono sicuro che ci sono altri miglioramenti relativi alla documentazione dell'API che possono essere apportati al termine del progetto GSoD. Ad esempio, creare una guida di stile per la documentazione e aggiungerla al wiki, in modo che i collaboratori siano consapevoli di come documentare il codice che stanno aggiungendo.
Sarò felice di aiutarti con attività come questa al termine di GSoD. Sicuramente ScummVM potrebbe avvalersi di un Technical Writer che si assicurerà che la documentazione relativa all'API sia di buona qualità e usabilità. Posso anche vedere che ci sono altri progetti futuri per i documenti con cui potrei aiutarti, come la creazione di una guida su come utilizzare i plug-in.