Premesse difficili
La necessità di ottimizzare la scrittura dei documenti è nata nel caos delle attività quotidiane. Frequenti passaggi tra pipeline, monitoraggio, automatizzazione, RnD, supporto e dettagliato conteggio del tempo non permettevano di concentrarsi sulla documentazione.
Loggare la storia
Mi serviva registrare le mie azioni, arricchire i testi con immagini, link e timestamp, evitando sovrapposizioni di temi nello stesso draft. Dovevo fare in modo che, in seguito, fosse facile ricordare il percorso dei lavori.
Diverse volte il logging di Putty/Bash ha aiutato a ripristinare una sequenza confusa di lavoro in produzione. Non ignorate questa possibilità.
Pubblicazione
Successivamente volevo trasformare il draft in un documento operativo e pubblicarlo all’interno della documentazione del progetto. Alla fine, il risultato è stato un bello spostamento al di là dei confini.
L’obiettivo era creare draft con formattazione estesa e lavorare con la documentazione come con il codice.
Ciò ha permesso di risparmiare tempo sul formattaggio e sulla conversione in formato standard pubblicabile.
Formato online
Infine, il formato Markdown+Git ha permesso di generare automaticamente la documentazione online. In più, è stato disponibile un modo offline, accessibile dal cache del browser. In reti chiuse del cliente, in aereo o dove non c’è internet, questo modo è stato molto utile. I clienti ne hanno apprezzato l’utilità.
Il formato Markdown viene utilizzato da Gitlab, YouTrack, alcuni messaggistica e riconosciuto da tutte le modelli LLM.
Draft condivisi
Se il tuo lavoro non è legato ai finanziamenti, i tuoi draft non devono essere nascosti. Anzi, permetti di lavorarci insieme.
La mia volontà di rendere i draft accessibili ha dato impulso alla creazione di “documentazione come codice”. La squadra DevOps è stata liberata dai file testuali anonimi e dal problema di trovare “dove ho scritto questo?”. Qui non ci sono problemi con diverse versioni di Word, file con immagini perse o simili. Inoltre, dal draft si ottiene subito una versione online e un PDF pulito e formale.
Documentazione oggi
- Scritta in formato Markdown (editor Typora o simile con autosalvataggio + commit in IDEA/PyCharm)
- Archiviata in Gitlab (accessibile a tutti i dipendenti secondo il modello di ruolo, supporta la collaborazione multiutente)
- Compilata automaticamente in versione online nel contenitore Docsify (aggiornamento del codice ogni minuto); i siti vengono esposti in internet tramite DNS
- Facilmente esportabile in PDF con lo stesso layout Vue.js sia per il sito che per il file
- Le diagrammi sono creati nel formato Drawio (outline) e Mermaid (inline)
- Le diagrammi vengono esportate in svg (e raramente in png per piattaforme non compatibili) e includono il codice sorgente integrato
Cosa manca?
La maggioranza degli utenti non è interessata a un’unica posizione dove è archiviata la documentazione e dove è possibile modificarla in modalità multitraccia. I contributori sono pochi, mentre gli utenti semplici sono molti. Per loro è fondamentale trovare rapidamente il documento necessario nella versione attuale e condividerlo facilmente. Da ciò derivano alcuni interrogativi, come:
- Come compilare automaticamente un elenco di documentazione.
- Come ordinare i riferimenti nel testo in base all’attualità dei documenti (non in base alla presenza di modifiche recenti, ma in base al contenuto sostanziale — poiché nessuno vuole un documento in cima alla lista solo per modifiche estetiche).
- Consentire un modo per apportare piccole modifiche direttamente nel documento, senza dover lavorare con i file sorgente.
- Aggiornare la documentazione “in blocco” quando alcune sue parti sono interconnesse e parzialmente o completamente riutilizzate.
- Generare automaticamente la documentazione, dato che essa si aggiorna molto rapidamente.
- Assicurarsi che non solo la documentazione sia coerente, ma anche che si ricordi di correggere o aggiornare le relative repliche degli utenti nei canali pubblici o nella community. Infatti, l’opinione sull’autorità di un autore (cioè di chi ha relazione con la documentazione) è spesso più importante della documentazione stessa, e questo è un fatto consolidato.
Il terzo punto è già presente in alcune piattaforme, ad esempio Discourse. E l’uso dell’Intelligenza Artificiale potrà aiutare a raggiungere una documentazione strutturata.