DEV Community

Antonio Musarra
Antonio Musarra

Posted on • Originally published at dontesta.it on

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.

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.

L'articolo Cos’è l’approccio Document as Code (doc-as-code) sembra essere il primo su Antonio Musarra's Blog.

Image of Docusign

Bring your solution into Docusign. Reach over 1.6M customers.

Docusign is now extensible. Overcome challenges with disconnected products and inaccessible data by bringing your solutions into Docusign and publishing to 1.6M customers in the App Center.

Learn more

Top comments (0)

Image of Docusign

🛠️ Bring your solution into Docusign. Reach over 1.6M customers.

Docusign is now extensible. Overcome challenges with disconnected products and inaccessible data by bringing your solutions into Docusign and publishing to 1.6M customers in the App Center.

Learn more