Docs as Code: in che modo migliora la Developer Experience?

Introduzione

Nel ciclo di vita di un prodotto software, la documentazione ricopre un ruolo di grande importanza: senza di essa gli utenti faticano ad utilizzare il software, o, nel migliore dei casi, non ne sfruttano le piene potenzialità. Gli utenti più tenaci possono, infatti, arrivare ad utilizzare le funzionalità più intuitive, ma difficilmente riusciranno a scoprire quelle più complesse, che di solito sono quelle che danno valore ad un software. Se anche riescono in questa impresa, di solito ciò avviene con procedure lunghe e faticose, con un’esperienza utente pessima, e questo può portare infine il cliente a cercare un fornitore alternativo.

Produrre una documentazione completa e facilmente fruibile previene questo scenario disastroso: se un utente è in grado di trovare in modo semplice e intuitivo le informazioni di cui ha bisogno, e sa che queste saranno esaustive e comprensibili, potrà godere di un’esperienza migliore e trarre il massimo potenziale del software. Tuttavia, una documentazione di qualità richiede un importante dispendio di tempo e risorse. Spesso le aziende più grandi e strutturate incaricano delle figure specializzate, come i Technical Writers, dedicate a tempo pieno a redigere e aggiornare la documentazione. Al contrario, in aziende di piccole/medie dimensioni che non possono permettersi un investimento di questo tipo, la stesura della documentazione rimane in carico ai team di sviluppo. 

Nella maggior parte dei casi, i developers preferiscono dedicarsi al loro lavoro principale, ovvero lo sviluppo del software, invece di occuparsi della redazione e dell’aggiornamento della documentazione. Questo avviene soprattutto perché gli strumenti utilizzati per la scrittura sono molto diversi da quelli che un developer utilizza normalmente per le sue attività. 

Per ridurre questo tipo di problematiche e per venire incontro alle esigenze dei developers è nato nel corso degli anni l’approccio Docs as Code (o Docs like Code). In questo articolo vedremo su quali pilastri si basa questo approccio e i principali benefici che porta, mostrando anche come lo abbiamo adottato all’interno di Mia‑Platform.

Cos’è l’approccio Docs as Code?

Letteralmente, Docs as Code significa Documentazione come codice. L’idea di fondo di questo approccio consiste nel trattare la documentazione come parte integrante del codice sorgente del software, e che quindi deve essere redatta e aggiornata con gli stessi strumenti e le stesse procedure che gli sviluppatori utilizzano quotidianamente per le attività legate al coding. A tutti gli effetti, questo approccio è un cambio di prospettiva radicale che mette al centro l’esperienza dei team di sviluppo. Invece di cercare di forzare i developer a usare gli strumenti e le metodologie di un technical writer, con questo approccio è la documentazione che viene adeguata agli strumenti e alle abitudini dei team.

È importante sottolineare che questo approccio non si limita ad adottare solo gli strumenti degli sviluppatori, ma abbraccia anche tutti i loro processi e le metodologie di lavoro: in particolare, permette di lavorare in Agile.

Come funziona l'approccio Docs as Code

Approfondiamo ora il funzionamento pratico dell’approccio Docs as Code, andando a vedere quali sono gli strumenti da adottare e i processi da mettere in atto per implementarlo all’interno della propria azienda. Questi processi possono essere implementati come parte di una Developer Experience Strategy vincente.

Plain text (Puro testo)

Lo strumento più utilizzato dai team di sviluppo è sicuramente l’IDE (Integrated Development Environment), quindi è importante che si continui a usarlo per la scrittura della documentazione. Per questo motivo, la documentazione deve essere redatta su file in un formato plain text, che può essere letto e modificato direttamente dall’IDE. In questo modo, i developer potranno consultare il codice all’interno dello stesso programma con cui scrivono la relativa documentazione: l’utilizzo di uno strumento unico permette di evitare, o quantomeno ridurre al minimo, un pericoloso switch of context che potrebbe distrarre e rallentare i developer.

Oltre ad essere compatibili con i diversi IDE utilizzati dai vari sviluppatori, i formati plain text possono essere facilmente letti anche da altre figure aziendali che utilizzano strumenti diversi da un IDE. Quasi tutti i sistemi operativi hanno integrati nativamente dei programmi che permettono di leggere file di questo tipo; inoltre, online si trovano molti tool gratuiti e open source facilmente utilizzabili anche da persone non tecniche.

Un altro importante vantaggio di questo tipo di file consiste nel favorire la concentrazione sul contenuto tecnico: il team incaricato della documentazione non si dovrà preoccupare dell’aspetto grafico e dell’impaginazione. Di solito i formati plain text servono principalmente per scrivere comandi destinati alle macchine, come ad esempio i file di configurazione. Tuttavia, dal momento che la documentazione è destinata ad essere letta da un pubblico umano, è consigliabile scegliere un formato plain text che permetta di gestire una formattazione di base. Le principali funzioni di formattazione richieste per una documentazione tecnica sono:

• Evidenziazione del testo (grassetto, corsivo e sottolineato);
• Link ipertestuali;
• Elenchi puntati e numerati;
• Blocchi e snippet di codice;
• Tabelle;
• Diversi livelli di intestazione.

Sfruttando queste semplici funzionalità si migliora notevolmente la leggibilità del contenuto, e al tempo stesso non si appesantisce eccessivamente l’esperienza di scrittura. 

Versionamento

Definito il tipo di file e l’editor testuale, un altro tema fondamentale dell’approccio Docs as Code riguarda il versionamento della documentazione: è infatti fondamentale tenere traccia di tutti i cambiamenti, da chi sono stati apportati e quando. Di fatto, il team di sviluppo è già abituato a questo modo di lavorare, dal momento che è prassi ben consolidata e diffusa l’utilizzo un version control system (VCS) per monitorare e versionare il codice del proprio software: per non interrompere il flusso di lavoro dei developer quando devono scrivere documentazione, è quindi sufficiente adottare il medesimo VCS che utilizzano per il codice.

Tra i VCS più famosi e gratuiti citiamo Git, Mercurial e Subversion. Tuttavia, invece di sfruttare direttamente uno di questi VCS, quasi tutte le aziende si affidano a piattaforme di hosting che sfruttano uno di questi sistemi e offrono al contempo funzionalità aggiuntive. Git ha avuto una grande fortuna e una notevole diffusione grazie alla sua relativa facilità di utilizzo e grazie al fatto che è open source: basti pensare che le piattaforme più conosciute e usate a livello mondiale, ovvero GitHub e GitLab, si basano proprio su Git. 

Secondo l’approccio Docs as Code, la documentazione deve essere salvata all’interno dello strumento di versionamento già utilizzato in azienda per la gestione del codice. Si può decidere di mantenere la documentazione all’interno di un’unica repository ad essa dedicata, oppure si può scegliere di distribuirla, ossia mantenere la documentazione di una specifica funzionalità nella stessa repository in cui è contenuto il codice di quella funzionalità. Questi sono dettagli implementativi che possono variare a seconda di tanti fattori, l’importante è che tutti i file vengano conservati e versionati all’interno dello stesso strumento tramite il quale si gestisce il codice sorgente.

Oltre a garantire il versionamento, l’adozione di GitHub, GitLab o una piattaforma alternativa favorisce la collaborazione tra sviluppatori: grazie alle Pull Request (o Merge Request; a seconda della piattaforma usata cambia il nome dell’azione, ma il funzionamento è il medesimo), ciascuno può proporre cambiamenti alla documentazione senza il rischio di impattare direttamente il file originale. Inoltre, queste funzionalità permettono di vedere precisamente i cambiamenti apportati a ciascun file e di iniziare discussioni per ciascun cambiamento. Il team responsabile della documentazione potrà poi decidere in modo granulare quali cambiamenti accettare e quali rifiutare.

Un altro grande vantaggio offerto da questi strumenti è la possibilità di lavorare in più persone in maniera asincrona sul medesimo file. Grazie alle branch, infatti, chiunque può creare una versione dei file sul proprio dispositivo, apportare le modifiche del caso e poi creare una Pull/Merge Request per rendere effettive le modifiche; tutto questo senza impattare direttamente il file originale, né le altre persone che stanno lavorando su un’altra versione dello stesso file. Le piattaforme forniscono anche un’interfaccia semplice per segnalare e risolvere facilmente eventuali conflitti (ovvero due modifiche differenti e concorrenti alla stessa sezione di un file).

Pubblicazione

Una volta che la documentazione è stata scritta, versionata e salvata, è pronta per essere resa disponibile. Il modo migliore per pubblicare file in formato plain text, che dispone già di una formattazione di base, è creare delle pagine web statiche, utilizzando quindi uno static‑site generator (SSG). Un SSG trasforma facilmente i file plain text in HTML, permette di aggiungere fogli di stile CSS per migliorarne e brandizzarne l’aspetto ed eventualmente di aggiungere anche sezioni dinamiche in JavaScript: il tutto verrà poi renderizzato lato server, fornendo quindi al client delle pagine statiche molto veloci da caricare.

Grazie ad un SSG, è possibile disaccoppiare facilmente il contenuto e la sua rappresentazione grafica finale: il team di sviluppo manterrà la responsabilità del contenuto tecnico, mentre la responsabilità sull’aspetto visivo può essere affidata ad un altro team. In questo modo i developer non dovranno preoccuparsi di selezionare il font corretto, di impaginare il contenuto, o di qualunque altra attività di questo tipo, ma soltanto di inserire direttamente nel file plain text la formattazione di base. Inoltre, in questo modo ogni cambiamento grafico potrà essere applicato a cascata su tutte le pagine, modificando soltanto un foglio di stile.

La maggior parte dei SSG offre anche diverse funzionalità aggiuntive che migliorano notevolmente la fruibilità del contenuto, senza però richiedere necessariamente un intervento manuale da parte del team di sviluppo. Esempi di queste funzionalità aggiuntive sono:

• Homepage con link alle pagine madri;
• Menu di navigazione laterali;
• Motore di ricerca;
• Anchor links alle intestazioni;
• Indici interni alle pagine;
• Sezioni separate dedicate alle Release Notes;
• Gestione di contenuti in lingue diverse;
• Visualizzazione della documentazione di versioni precedenti del software.

Si tratta di funzionalità relativamente semplici in valore assoluto, ma che unite tutte insieme rendono semplice la ricerca e la fruizione del contenuto, aiutando l’utente a trovare velocemente ciò che sta cercando.

Automazioni

Un ulteriore vantaggio dell’approccio Docs as Code è la possibilità di sfruttare le automazioni che sono solitamente implementate per il codice sorgente: in particolare, grazie a questo approccio è possibile introdurre elementi tipici del mondo DevOps, come le pratiche di CI/CD (Continuous Integration e Continuous Delivery).

Per quanto riguarda la CI si può tradurre nella creazione di test automatici che controllano il contenuto ogni volta che viene effettuata una Pull/Merge Request sul branch principale: questi test possono verificare la presenza di errori tecnici (ad esempio, link non validi, snippet di codice non validi, ecc.) o formali (come refusi, punteggiatura mancante, ecc.) all’interno della documentazione. Se i test falliscono, il team viene notificato dell’errore e può intervenire per risolverlo; se invece i test vengono superati, può partire la fase di CD.

Per fare un esempio di come si può sfruttare la CD, sarà possibile creare degli automatismi che rilevano tutti i cambiamenti all’interno del branch principale, e in automatico il nuovo contenuto viene pubblicato immediatamente. In questo modo, non sarà più necessario dedicare del tempo alla fase di pubblicazione, che tradizionalmente porta via molto tempo. A seconda delle esigenze si può decidere di implementare soltanto una delle due pratiche, ma l’adozione di entrambe garantisce di velocizzare molte procedure e di evitare errori in produzione.

Come abbiamo implementato l’approccio Docs as Code in Mia‑Platform

A questo punto, vediamo più nel dettaglio quali strumenti e metodologie abbiamo adottato in Mia‑Platform per implementare l’approccio Docs as code.

Per quanto riguarda il formato plain text dei file, abbiamo optato per il Markdown: è un linguaggio di markup molto semplice da imparare e utilizzare, e permette di gestire tutte le principali funzioni di formattazione di base. Inoltre è uno dei linguaggi più diffusi al mondo tra i developer, e per questo la maggior parte degli IDE fornisce una vasta gamma di add‑on per migliorare la visibilità della formattazione anche in fase di scrittura. Questo permette di avere un’anteprima del risultato già in fase di scrittura, aiutando così il team a vedere eventuali errori direttamente all’interno dell’editor. Riguardo l’IDE, come si è detto, non ci sono indicazioni particolari, e ciascuno è libero di utilizzare lo strumento con cui ha maggiore familiarità.

Per il versionamento abbiamo scelto la stessa piattaforma basata su Git che utilizziamo per la gestione del codice, ovvero GitLab, che è open source e fornisce anche alcuni utili strumenti di DevOps. Per semplicità, abbiamo creato una repository dedicata che contiene tutta la documentazione. Tutti all’interno dell’azienda hanno accesso a questa repository e non solo sono liberi di accedervi, ma sono anche incoraggiati a contribuire: si tratta di fatto di una trasposizione della metodologia di contribuzione in Open Source, limitata però ai dipendenti dell’azienda. 

Inoltre, GitLab ci ha permesso di implementare alcune automazioni di CD: ad esempio, ogni cambiamento sul branch principale innesca una pipeline che pubblica la documentazione su un ambiente di test, sul quale è possibile avere un’anteprima del risultato finale.

La scelta del SSG è ricaduta su Docusaurus, un tool open source pensato proprio per la documentazione di software. La particolarità di questo SSG è che crea delle single page applications invece che delle semplici pagine statiche, e sfrutta le potenzialità di React per rendere il sito interattivo. Grazie a queste caratteristiche è possibile creare dei siti molto elaborati a livello grafico.

I principali benefici dell’approccio Docs as Code

L’adozione dell’approccio Docs as Code porta diversi benefici, sia per i fruitori della documentazione ‑ che sono spesso i clienti esterni all’organizzazione ‑, sia per chi all’interno dell’azienda deve occuparsi di scriverla. Partendo dalla fruizione esterna, i contenuti saranno semplici e veloci da trovare grazie alla facilità di utilizzo del sito: questo permette agli utenti di imparare rapidamente a utilizzare correttamente il software, e a risolvere velocemente eventuali problemi.

I benefici maggiori, però, si hanno per quanto riguarda la fase di scrittura della documentazione. Vediamo di seguito quali sono:

• Velocità di scrittura: usando gli stessi strumenti utilizzati quotidianamente per la scrittura del codice, gli sviluppatori potranno focalizzarsi solo sul contenuto, producendolo più velocemente. 
• Documentatione migliore: essendo più veloci nella fase di scrittura, gli sviluppatori produrranno una documentazione più precisa, perché la fase di scrittura avverrà poco dopo lo sviluppo della funzionalità che si vuole documentare.
• Maggiore collaborazione: questi strumenti sono pensati per favorire la collaborazione, ed avendo grande familiarità con essi gli sviluppatori saranno più inclini a proporre modifiche e miglioramenti.
• Pieno controllo delle versioni: grazie agli strumenti di versionamento si potrà tracciare facilmente ogni modifica alla documentazione, e in caso di errore si potrà facilmente tornare indietro. Inoltre, il versionamento permette di controllare anche che la documentazione sia aggiornata.
• Separazione tra contenuto e la sua visualizzazione: i developer saranno responsabili solo dell’accuratezza del contenuto, mentre l’ownership della parte grafica può essere affidata ad un team dedicato.

In conclusione, l’approccio Docs as Code adatta la scrittura della documentazione agli strumenti e ai processi già utilizzati dagli sviluppatori per la scrittura del codice: in questo modo contribuisce sensibilmente a fornire una Frictionless Developer Experience, migliorando la produttività degli sviluppatori e aumentando la qualità della documentazione.

Questo articolo è stato scritto da Paolo Martinoli, Technical Writer di Mia‑Platform.

Torna all'inizio