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:
- 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 molti settori:
1) Non ha praticamente alcuna struttura, tutte le informazioni sono allo stesso livello.
2) Gli elementi C++ sono documentati in modo incoerente con alcuni di essi non documentati affatto. Questo è uno dei problemi principali indicati dall'organizzazione.
3) I contenuti obsoleti e ritirati vengono ancora visualizzati nell'output.
4) Il linguaggio e l'utilizzo del tagging doxygen dovrebbero essere resi più coerenti. È necessario un insieme di regole, che potrebbe essere la 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 richiesta di partecipazione alla 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 cosa contiene e per visualizzare la differenza.
Ecco in termini generali cosa comporta la gestione delle pubbliche relazioni:
1) Penso che la cosa più confusa al momento per i potenziali nuovi collaboratori e in generale per tutti coloro che visualizzano la documentazione dell'API attuale sia la mancanza di struttura. L'introduzione della documentazione API strutturata migliorerebbe la leggibilità, la rilevabilità e, di conseguenza, l'usabilità del set di documenti. Ecco perché la mia PR introduce i gruppi doxygen in tutti i file di intestazione nella cartella "common". Con questa nuova struttura, se qualcuno vuole trovare la documentazione per l'API relativa al sistema operativo (ad esempio), può trovarla facilmente nella navigazione.
2) Viene configurato un nuovo file di configurazione doxygen per consentire la compilazione della documentazione.
3) Un file "links.doxyfile" da cui tutti i link utilizzati nel set di documenti possono essere di origine singola. Un meccanismo utile quando si lavora con doxygen.
4) Un CSS doxygen modificato. Al momento, questo codice è stato preso da un altro progetto open source e rappresenta solo un punto di partenza. Idealmente, l'aspetto della pagina relativa al dossigeno dovrebbe essere più o meno coerente con la pagina web di ScummVM.
Ciò che non viene trattato dalle pubbliche relazioni, ma che deve essere necessariamente migliorato, sono i contenuti stessi. Intendendo identificare le parti essenziali del codice non documentate, quelle non sufficientemente documentate o le parti obsolete del codice che devono essere rimosse dalla documentazione. Dato che non ho mai lavorato al progetto, per raggiungere questo obiettivo sarà necessaria la guida di un mentore.
Ovviamente, l'implementazione di eventuali elementi della RP dipende dalla discussione con l'organizzazione. La mia idea era che le azioni parlano più delle parole, quindi ho deciso di mostrare cosa posso fare anziché limitarmi a descriverlo nell'applicazione.
Settimana
L'unica modifica che propongo è iniziare lavorando alla struttura, come già accennato. Questa operazione può essere eseguita nelle settimane 1 e 2, insieme alla configurazione della compilazione di Doxygen (che è già in gran parte completata) e all'aggiornamento della skin di Doxygen. Dopodiché, sono d'accordo che ha più senso esaminare le diverse aree una alla volta con il mentore per identificare i problemi e migliorare la documentazione di Doxygen.
Lo considero un progetto di durata 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 uno stile guida per la documentazione e aggiungerlo alla wiki, in modo che i collaboratori sappiano come devono documentare il codice che aggiungono.
Sarò felice di aiutarti con attività di questo tipo al termine del GSoD. Sono sicuro che ScummVM potrebbe utilizzare un Technical Writer che si assicurerà che il suo documento dell'API sia di buona qualità e di usabilità. Vedo anche che potrò aiutarti con altri progetti di documentazione in futuro, ad esempio la creazione di una guida sull'utilizzo dei plug-in.