L’obiettivo è di essere in grado di esporre le cose che faccio per condividerle. Per questo, aprire semplicemente un archivio GitHub non basta. Serve uno spazio web per esporre e illustrare quanto si è fatto, altrimenti non c'è comunicazione.
Al momento sono impegnato in un’impresa piuttosto difficile e noiosa, per illustrare il progetto mastroPiano. Altre cose saranno disponibili col tempo, come ad esempio la pagina Blink, che si propone di spiegare alcuni concetti di programmazione complessi partento dal classico esempio, in apparenza banale, per accendere e spegnere un LED. Oppure altre storie, che parleranno di come sia possibile ottenere una pagina HTML (oppure un intero sito) da uno o più file di testo e come utilizzare certi strumenti software per semplificare, anziché complicare la propria vita e il proprio lavoro.
Comunicare
Comunicare significa condividere la conoscenza, quindi, se comunico, condivido. Una parola! Ma come? Dicono che un’immagine vale mille parole, ma senza una breve spiegazione l’immagine mantiene la sua efficacia?
Mi serve uno strumento per mettere insieme e mostrare in una forma gradevole e comprensibile testi e immagini. Già utilizzo per questo l’applicativo LibreOffice, ma per produrre materiale cartaceo. Quello che mi serve adesso è qualcosa che mi permetta di produrre pagine HTML, come questa.
GitHub
Dal momento che gran parte del materiale sarebbe in forma di codice sorgente, la scelta di un archivio strutturato gestito da Git soddisferebbe anche altre necessità per il mantenimento del codice, soprattutto per gli sviluppi successivi.
Tuttavia, Git così da solo, non mi permette di pubblicare e rendere disponibile il codice su Internet. Per questo c'è GitHub, che incidentalmente comprende alcune funzionalità per gestire anche la documentazione. Tra queste, quella che più mi interesserebbe è GitHub Pages, che consente la pubblicazione di pagine web all’interno dell’archivio gestendo allo stesso modo anche i file sorgenti delle pagine.
Spazio web statico o dinamico
Quando ho aperto il mio profilo su GitHub e ho iniziato cercare di capire coe funziona e che cosa ci si può fare, ho iniziato a considerare l’opportunità di usa asccidoc come linguaggio di marcatura per la documentazione.
Dopo un po' di tempo mi sono reso conto di alcuni dettagli che mi avrebbero permesso di creare non una sola pagina, ma più di una con un solo comando. In sostanza stavo iniziando ad usare asciidoc come un generatore di siti statici.
Alla base di questo passaggio sta un file make che controlla da solo lo stato delle varie pagine ed esegue la compilazione quando è necessario.