Questa pagina contiene i dettagli di un progetto di scrittura tecnica accettato per Google Season of Docs.
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
Purtroppo è carente in molte aree:
1) Praticamente non ha una struttura, tutte le informazioni si trovano sullo stesso livello.
2) Gli elementi C++ sono documentati in modo incoerente con alcuni di essi 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) La lingua e l'uso del tagging del doxygen dovrebbero essere resi più coerenti. A tal fine, è necessario disporre di una serie di regole, che potrebbero essere una base per una guida di stile della documentazione futura 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 Vedi la descrizione per alcuni dettagli su ciò che contiene e per visualizzare le differenze.
Questo è più o meno ciò che il PR prevede:
1) Penso che al 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 dell'API strutturata migliorerebbe la leggibilità, la ritrovabilità e, di conseguenza, l'usabilità del set di documenti. Ecco perché il mio PR introduce gruppi di doxygen a tutti i file di intestazione nella cartella "common". Con questa nuova struttura, chi ad esempio vuole trovare documenti per le API relative al sistema operativo può trovarlo facilmente nella navigazione.
2) Viene impostato un nuovo file di configurazione doxygen per consentire la creazione di questa documentazione.
3) Un file 'links.doxyfile' da cui tutti i link utilizzati nel set di documenti possono essere ricavati da un'unica fonte. Un meccanismo utile quando si lavora con il doxygen.
4) Un CSS del doxygen modificato. Al momento proviene da un altro progetto open source ed è solo un punto di partenza. Idealmente, l'aspetto e il design della pagina di doxygen dovrebbero essere più o meno coerenti con quelli della pagina web di ScummVM.
Ciò che il PR non tratta, ma che deve essere decisamente migliorato, sono i contenuti stessi. Con questo intendo identificare le parti essenziali di codice che non sono documentate, quelle non sufficientemente documentate o le parti obsolete di codice che devono 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 parlano più forte delle parole, quindi ho deciso di spiegare cosa posso fare invece di descriverlo solo nell'applicazione.
L'organizzazione ha fornito la seguente sequenza temporale approssimativa per questo progetto: Dati grafici 1-2a settimana 1-2a settimana 1 e 14-12-22 giorni (14/21) Settimana 1, 12/3 su 3, 12/3 su 3, 3 su 3, 3 su 3, 3 su 3, 3 su 3, 3 su 3, 3 su 3, 3 su 3, 3
L'unico cambiamento che propongo è iniziare lavorando alla struttura, come già accennato. Questo può essere fatto nelle settimane 1 e 2, insieme alla configurazione di doxygen build (che è in gran parte già fatto) e al tema di aggiornamento della pelle Doxygen. Dopodiché, sono d'accordo sul fatto che abbia senso analizzare le diverse aree una alla volta con il mentore per identificare i problemi e migliorare la documentazione sul doxygen.
Vedo che questo è 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 alla documentazione e aggiungerla al wiki, in modo che i collaboratori sappiano come devono documentare il codice che stanno aggiungendo.
Sarò felice di aiutarti con attività come questa al termine di GSoD. Sicuramente ScummVM potrebbe usare un Technical Writer che si assicurerà che il documento dell'API sia di buona qualità e usabilità. Vedo anche 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.