Documenti come codice a Linode

Mi chiamo Nathan e sono un membro del team di scrittura tecnica di Linode. Uno dei nostri compiti principali è quello di contribuire e mantenere la libreria di guide e tutorial di https://www.linode.com/docs, dove sono pubblicati oltre 1.400 articoli. Per mantenere la qualità dei contenuti e incoraggiare la collaborazione nel processo di scrittura, abbiamo adottato una metodologia di docs as code per il nostro flusso di lavoro di scrittura.

Docs as code è una metodologia in cui gli strumenti utilizzati per scrivere la documentazione sono gli stessi utilizzati per scrivere il software. Questo include:

• Utilizzo del software di controllo della versione
• Scrivere file di documentazione in testo semplice
• Esecuzione di test automatizzati
• Praticare l'integrazione continua e la consegna continua

Il team di scrittura tecnica di Linode ha esteso questa metodologia assumendo la responsabilità dell'infrastruttura cloud che ospita il nostro sito web di documentazione.

Perché i documenti come codice?

Seguire queste pratiche offre una serie di vantaggi:

• Lavorare con queste tecnologie aiuta a formare un legame più stretto tra il team di scrittura tecnica e i team di sviluppo e ingegneria di Linode.
  
• Altri team di Linode possono contribuire a vari aspetti del nostro processo. Ad esempio, il team di front-end può contribuire ad aggiornare il tema/la presentazione del sito web dei documenti utilizzando gli strumenti con cui già lavora, mentre un membro del team di ingegneri potrebbe scrivere nuovi test automatizzati per la libreria dei documenti.
  
• Il nostro team scrive spesso guide e tutorial sulle tecnologie utilizzate nel nostro processo. L'implementazione di queste tecnologie ci permette di comprenderle meglio, migliorando la nostra capacità di spiegarle.
  
• Dobbiamo anche documentare accuratamente i prodotti Linode, il che può comportare la revisione della base di codice di Linode. La conoscenza dei linguaggi e degli strumenti utilizzati per questi progetti può aiutarci a comprenderli meglio.

La nostra implementazione

Poiché l'implementazione di questa metodologia può variare da un'organizzazione all'altra, vorrei offrire uno schema dettagliato del nostro processo:

1. Redazione: I nostri redattori tecnici scrivono le nuove guide in Markdown. Markdown è utilizzato per rappresentare testo ricco in un file di testo semplice e può essere compilato in HTML da una serie di strumenti. Il Markdown è quasi universalmente adottato nello sviluppo del software; ad esempio, i file README di GitHub sono scritti in Markdown. Scrivere in Markdown significa anche poter utilizzare qualsiasi editor di testo semplice, dai moderni editor desktop come Visual Studio Code, a Emacs e Vim. Sappiamo che le persone hanno forti opinioni sui loro editor di testo preferiti e questa flessibilità aiuta più persone a contribuire alla nostra libreria.
   
2. Anteprime del sito locale: I file Markdown della nostra libreria sono compilati nella loro rappresentazione finale in HTML con un file generatore di siti statici. I siti statici sono raccolte di pagine precostituite che non dipendono da un database per essere rese quando vengono richieste (come nel caso di un CMS come WordPress). Per questo motivo, un sito statico è molto veloce da caricare. Un generatore di siti statici rende un sito statico combinando i file di contenuto (ad esempio, Markdown) con un tema specificato dall'utente.
   
   Il sito web dei documenti di Linode utilizza Hugo, che è una delle I generatori di siti statici più popolari:
   
   • Hugo offre metodi di installazione ben documentati su molti sistemi operativi, in modo da non avere problemi durante l'inserimento di un nuovo dipendente.
     
   • Hugo include un server web di sviluppo locale, in modo che gli autori possano visualizzare il sito sul proprio computer mentre scrivono nuove guide. Questo server verrà anche ricaricato in tempo reale ogni volta che l'autore salverà il proprio file.
     
   • Hugo è estremamente veloce, il che è un fattore significativo per una biblioteca delle nostre dimensioni: il mio Macbook Pro è in grado di compilare tutte le 1400 guide in circa 3 secondi e la funzione di caricamento in tempo reale è quasi istantanea. 
     
   • Gli shortcode di Hugo ci aiutano anche a migliorare le nostre guide con caratteristiche che Markdown non ci permette, come le note evidenziate e gli snippet di codice numerati per riga.
     
     
3. Collaborazione: La libreria di documenti è archiviata in un repository Git pubblico ospitato su GitHub, e ogni autore mantiene un fork di questo repository. Quando un autore ha finito di redigere una guida, esegue il commit delle sue modifiche, le spinge sul suo fork e poi apre una richiesta di pull contro il repository principale.
   
   Il nostro processo di scrittura prevede che due membri distinti del team eseguano una modifica tecnica e poi una modifica di copia su ogni nuova guida o aggiornamento della guida. Questi membri del team scaricano il ramo della richiesta di pull, apportano e impegnano le loro modifiche, quindi le inviano nuovamente al ramo su GitHub. Git è un altro strumento quasi universale per lo sviluppo e il suo utilizzo ci permette di sfruttare alcune best practice standard per la collaborazione, come il flusso di lavoro gitflow.
   
   Inoltre, la popolarità di GitHub significa che ha un gran numero di integrazioni utili. In particolare, usiamo Netlify per generare anteprime automatiche e accessibili al pubblico per ogni richiesta di pull. Spesso abbiamo bisogno di chiedere un feedback ai linoidi di diversi reparti, che possono visualizzare questi link condivisibili di Netlify senza dover clonare il nostro repository di documenti e installare Hugo sui loro portatili.
   
   Infine, l'hosting in un repository pubblico apre la nostra libreria a collaboratori esterni, cosa che accogliamo con piacere.
   
4. Test: Ogni volta che una richiesta di pull viene inviata o aggiornata, viene eseguita una serie di test sul contenuto della PR. Questi test vengono eseguiti con Travis CIche è un servizio di integrazione continua che offre anche l'integrazione con GitHub. Se uno di questi test fallisce, la richiesta di pull viene temporaneamente bloccata dall'unione:
   
   • Il contenuto della guida viene controllato per quanto riguarda l'ortografia e lo stile (ad esempio, la corretta capitalizzazione dei termini tecnici). Per svolgere questi compiti utilizziamo Vale, un linterno open-source progettato per lavorare sulla prosa. Quando abbiamo integrato Vale per la prima volta, ci ha segnalato oltre 500.000 errori di ortografia nella nostra biblioteca. Sebbene sia un po' imbarazzante, conoscere questo numero e poter agire di conseguenza ci ha dato una grande iniezione di fiducia nei nostri contenuti e nel nostro nuovo sistema di pubblicazione.
     
   • Verifichiamo la presenza di potenziali collegamenti interrotti tra le guide utilizzando Scrapy, un framework open source Python che esegue lo scraping dei contenuti dai siti web. Questo test è stato scritto in collaborazione con un membro del team di ingegneri di Linode. Quando abbiamo implementato Scrapy per la prima volta, abbiamo trovato una serie di collegamenti interrotti che abbiamo potuto correggere.
     
   • Un altro script di Python controlla che i metadati delle guide siano validi e privi di errori di sintassi. Una sezione di front-matter non funzionante può causare problemi durante la costruzione del sito, quindi la convalida di questa sezione significa che possiamo essere sicuri che il sito verrà visualizzato durante l'aggiornamento dei server web di produzione.
     
5. Pubblicazione e hosting: L'aggiornamento del sito web dei documenti è gestito automaticamente da una serie di script che vengono attivati da determinati eventi su GitHub:
   
   • Ogni volta che un contenuto viene unito al ramo master del repository principale dei documenti, viene inviata una notifica webhook a un server web di staging, che è un Linode. Questo server web di staging preleva quindi il ramo master da GitHub e costruisce il sito con Hugo, con la radice dei documenti del server web come target per il sito renderizzato. Visualizziamo questo sito di staging e confermiamo che i contenuti appaiono come previsto.
     
     Il server di staging non faceva inizialmente parte del nostro flusso di lavoro; è stato creato dopo un incidente che ha temporaneamente danneggiato il nostro CSS/stile durante un aggiornamento del sito di produzione. In breve, Netlify aveva renderizzato correttamente un'anteprima della nuova release del sito, ma non era riuscito a individuare un problema di stile. Ciò è avvenuto perché ha utilizzato la nostra pipeline di creazione "di sviluppo", invece di quella "di produzione" (che minifica il CSS e altre risorse). Il nuovo server di staging è impostato con la stessa configurazione del nostro server di produzione, quindi utilizza anche la pipeline di compilazione di produzione e coglie errori come questo.
     
   • Per aggiornare il sito di produzione, creiamo un nuovo tag di rilascio su GitHub. Questo attiva un'altra notifica webhook che viene inviata al server web di produzione. Questo server esegue uno script simile a quello del server di staging, ma estrae il contenuto dal tag della nuova release.
   • Il fatto che la nostra funzione di pubblicazione avvenga automaticamente riduce al minimo qualsiasi errore umano che potrebbe verificarsi se dovessimo eseguire manualmente questo processo. I server di staging e di produzione sono entrambi gestiti tramite formule di configurazione. SaltSalt è utilizzato anche da altri progetti infrastrutturali di Linode, quindi i nostri server web di documentazione possono essere gestiti insieme ad altre parti del parco macchine.

L'adozione di questa metodologia ci ha aiutato a semplificare notevolmente il nostro flusso di lavoro, ma siamo sempre al lavoro per iterare e migliorare. Se avete suggerimenti su aggiornamenti da apportare, fatecelo sapere! Sono presente sullo Slack di Write the Docs con il nome di nmelehan, così come molti altri membri del team. Se volete saperne di più sui documenti come codice, vi consiglio la guida di Eric Holscher sul sito di Write the Docs.