Cos’è l’approccio Document as Code (doc-as-code)

Negli ultimi anni, l’approccio Document as Code (Doc-as-Code) ha guadagnato popolarità tra i team di sviluppo software e le organizzazioni che si occupano di documentazione tecnica. Questa metodologia trasferisce i principi dello sviluppo software alla creazione e gestione della documentazione, portando con sé numerosi vantaggi in termini di efficienza, qualità e collaborazione. Ma cosa significa esattamente Document as Code?

Cercherò di spiegare questo approccio nel modo più chiaro e sintetico possibile per poi lasciarvi il bonus, ovvero, un progetto completo (out-of-the-box) di questo tipo di approccio.

1. Definizione e Principi Fondamentali

L’approccio Doc-as-Code prevede la gestione della documentazione tecnica nello stesso modo in cui si gestisce il codice sorgente. Ciò implica che i documenti siano scritti in formati testuali, abbiano una versione applicata tramite sistemi di controllo del codice sorgente come Git, e sottoposti a revisione e test automatizzati. I principi cardine di questo approccio sono indicati e descritti a seguire.

1. Tracciabilità e Versionamento: Utilizzando sistemi di controllo del codice sorgente, è possibile tracciare ogni modifica apportata alla documentazione. Questo consente di mantenere una cronologia completa delle versioni, facilitando il ritorno a una versione precedente in caso di necessità.
2. Collaborazione e Revisione: La documentazione può essere revisionata e migliorata attraverso pull request e code review, proprio come avviene per il codice sorgente. Questo processo incrementa la qualità e la precisione del contenuto.
3. Automazione: Strumenti di integrazione continua (CI) possono essere utilizzati per automatizzare la generazione, la validazione e la pubblicazione della documentazione. Questo riduce gli errori manuali e accelera il processo di aggiornamento.
4. Uniformità: Utilizzando linguaggi di markup (tra i più noti) come Markdown, AsciiDoc e reStructuredText, è possibile mantenere uno stile coerente e facilmente leggibile. Inoltre, i generatori di documentazione come Sphinx o MkDocs possono essere utilizzati per creare documenti HTML, PDF e altro ancora da sorgenti testuali.

2. Vantaggi dell’Approccio Doc-as-Code

1. Miglioramento della Qualità: La revisione paritaria e i test automatici assicurano che la documentazione sia accurata e aggiornata, riducendo il rischio di errori.
2. Efficienza: L’automazione delle operazioni di generazione e pubblicazione consente di risparmiare tempo prezioso, permettendo agli autori di concentrarsi sui contenuti piuttosto che sui dettagli tecnici.
3. Collaborazione: L’uso di strumenti comuni tra sviluppatori e scrittori tecnici facilita una collaborazione più stretta e una migliore integrazione tra codice e documentazione.
4. Flessibilità: La documentazione può essere aggiornata e distribuita rapidamente, adattandosi facilmente ai cambiamenti del software e alle esigenze degli utenti.
5. Manutenibilità: La struttura modularizzata e versionata dei documenti semplifica la gestione e l’aggiornamento continuo del materiale di documentazione.

3. Strumenti e Tecnologie

L’approccio Doc-as-Code si avvale di una serie di strumenti e tecnologie che facilitano la creazione, gestione e pubblicazione della documentazione.

• Sistemi di Controllo del Codice Sorgente: Git è il più utilizzato, permettendo di versionare la documentazione e gestire le collaborazioni.
• Linguaggi di Markup: Markdown, AsciiDoc e reStructuredText sono i più comuni, grazie alla loro semplicità e leggibilità.
• Generatori di Documentazione: Strumenti come Sphinx, MkDocs, Jekyll e Hugo trasformano i file di markup in documenti formattati e navigabili.
• CI/CD: Piattaforme come Jenkins, Travis CI e GitHub Actions possono automatizzare la generazione e la pubblicazione della documentazione.
• Editor di Testo: Visual Studio Code, Intellj IDEA e altri editor moderni supportano estensioni che migliorano la scrittura e la formattazione della documentazione.

4. Il bonus: un progetto Doc-as-Code

Ogni promessa va onorata, per cui è arrivato il momento di presentarvi il bonus, un progetto doc-as-code completo.

L’articolo Deploy di un’applicazione Quarkus su OpenShift pubblicato su TheRedCode.it, è il primo di quattro articoli che spiegano parte del progetto Quarkus Event Bus Logging Filter JAX-RS e la documentazione di quest’ultimo è stata realizzata con l’approccio doc-as-code e in particolare:

1. questo Documentazione Quarkus Event Bus Logging Filter JAX-RS è il link al repository GitHub del progetto doc-as-code;
2. questo https://amusarra.github.io/eventbus-logging-filter-jaxrs-docs/ è il link alle GitHub Pages dov’è stata pubblicata la documentazione in formato HTML;
3. cliccando qui Quarkus Event – Come sfruttarlo al massimo, utilizzi e vantaggi otterrete la documentazione in formato PDF;
4. il linguaggio di markup utilizzato è AsciiDoc;
5. AsciiDoctor è il processore di testo che supporta la sintassi AsciiDoc e produce HTML5, DocBook, PDF e altri formati;
6. per ulteriori dettagli sul progetto, fare riferimento al README.

Vi lascio altro bonus. Conoscete Mia-Platform? La documentazione è realizzata usando l’approccio doc-as-code e qui Come abbiamo implementato l’approccio Docs as Code in Mia‑Platform puoi leggere tutti i dettagli.

Con questo bonus spero che apprezziate ancora di più l’approccio doc-as-code e che in qualche modo possa servire come buon punto d’inizio per i vostri progetti doc-as-code.

Conclusioni

L’approccio Document as Code rappresenta un’evoluzione significativa nella gestione della documentazione tecnica. Adottando pratiche di sviluppo software per la creazione di documenti, le organizzazioni possono migliorare la qualità, l’efficienza e la collaborazione, offrendo agli utenti finali documentazione sempre aggiornata e accurata. In un mondo in cui il software è in continua evoluzione, avere una documentazione che può tenere il passo è essenziale per il successo di qualsiasi progetto.