La documentazione di Radical è stata finalmente migrata dal Wiki di GitHub ad uno strumento pensato per gestire la documentazione: GitBook.
Il risultato è disponibile qui: https://docs.radicalframework.com/.
I sorgenti sono invece su GitHub: https://github.com/RadicalFx/documentation.
Perché migrare.
Tre motivi principali:
- Il Wiki di GitHub è molto limitato in termini di feature, struttura della documentazione stessa e gestione degli asset
- L’aspetto collaborativo tipico di un progetto open source è monco. Ad esempio non c’è supporto per le PR, limitando quindi di fatto la possibilità che la community partecipi
- Originariamente Radical era un singolo progetto in un singolo repository e il Wiki soddisfava le necessità del tempo. Il progetto è evoluto, adesso ha la sua Organization su GitHub e il codice è stato separato in diversi repository. A questo punto ci siamo trovati in una situazione alquanto scomoda perché il repository originale non conteneva più tutto il codice ma conteneva tutta la documentazione.
La decisione è stata quindi quella di trovare una soluzione che cercasse di risolvere tutti i problemi.
Requisiti
Abbiamo quindi posto alcuni paletti:
- Il repository deve essere un repository di GitHub
- Il formato della documentazione deve essere
- markdown
- il più indipendente possibile dal tool usato per pubblicare la documentazione stessa
- Supporto per la ricerca
- Supporto per ToC
Il primo tentativo è stato fatto costruendo una roba completamente custom con Jekyll ma la ricerca e la generazione della ToC sono una rogna, insormontabile la prima, e noiosissima la seconda soprattutto considerando le limitazioni imposte dall’hosting di Jekyll nelle GitHub Pages.
Il secondo tentativo è stato Read the Docs che al primo colpo ha funzionato bene, poi le build hanno cominciato a fallire senza motivo. Il problema è che far gira tutto in locale, come ad esempio si fa con Jekyll, è abbastanza rognoso su Windows e la difficoltà di debug era tale che ho pensato di cercare altro.
Benvenuto GitBook
Alla fine devo dire che nel complesso l’esperienza GitBook è buona:
- La sorgente primaria delle informazioni è GitHub
- Tutto il flusso di GitHub è rispettato. Quindi una eventuale PR al momento della merge avvia la build della documentazione, etc
- il linguaggio è markdown senza nessuna estensione particolare
- c’è il supporto per la ricerca e la generazione della ToC
Ci sono anche dei bonus come ad esempio il fatto che GitBook abbia un editor markdown online che funziona molto bene e abbia un concetto simile a quello delle PR ma orientato ai non dev e quindi la barriera d’ingresso è inferiore. GitBook fa anche tante altre cose, che al momento a noi non servono. Ma, mai dire mai.