🥇Usa GIT per la documentazione

A volte non solo la documentazione stessa, ma anche il processo di lavoro su di essa può essere critico. Ad esempio, nel caso di progetti la maggior parte del lavoro è legata proprio alla preparazione della documentazione, e un processo errato può portare a errori e persino alla perdita di informazioni, e quindi alla perdita di tempo e guadagni. Ma anche se questo tema non è centrale nel vostro lavoro e si trova in periferia, un processo corretto può comunque migliorare la qualità del documento e farvi risparmiare tempo.

L'approccio qui esposto, con un esempio di implementazione concreta, ha una soglia di ingresso bassa. Tecnologicamente, già domani potreste iniziare a lavorare in modo nuovo.

Definizione del compito

Dovete creare un certo documento o un insieme di documenti. Potrebbe trattarsi di documentazione di progetto o di registrazione della vostra rete, o di qualcosa di più semplice, ad esempio, dovete descrivere i processi nella vostra azienda o nel vostro dipartimento. In generale, si parla di qualsiasi documento o insieme di documenti con testi, immagini, tabelle... Diciamo che

questo lavoro richiede collaborazione, sforzi di un gruppo o di più gruppi di dipendenti
e il risultato finale deve essere un documento in un formato specifico, con attributi di stile aziendale, realizzato secondo un certo modello. Per chiarezza, considereremo che si tratti di MS Word (.docx)

Dieci anni fa, l'approccio sarebbe stato univoco: avremmo creato un documento o documenti MS Word e in qualche modo avremmo organizzato il lavoro di modifica.

E tale approccio è ancora valido. Viene utilizzato anche da grandi integratori nella creazione di documentazione di progetto. Ma è intuitivamente chiaro che, se lavorate intensamente su un documento con molte modifiche e discussioni per un lungo periodo, questo approccio non è molto conveniente.

Esempio
Ho avvertito questa problematica piuttosto acutamente, lavorando per un grande integratore. Il processo di modifica della documentazione di progetto era il seguente:

l'ingegnere scarica l'ultima versione del documento MS Word (.docx)

cambia il nome

apporta modifiche in modalità track

invia il documento con le modifiche all'architetto

invia anche un elenco di tutte le correzioni con commenti

l'architetto analizza le modifiche

se tutto è a posto, copia le modifiche nel file con l'ultima versione, cambia la versione e la carica su una risorsa condivisa

se ci sono osservazioni, viene avviata una discussione (email o riunioni)

si raggiunge un consenso

poi i punti 3 - 9
Finché il lavoro non è stato intenso, ha funzionato in qualche modo, ma ha funzionato. Ma a un certo punto questo processo è diventato un collo di bottiglia per l'intero progetto e ha portato a problemi. Il problema è che tutto va male non appena le modifiche vengono apportate frequentemente e simultaneamente da più team.
Quindi, quando siamo passati alla fase di test preliminare, hanno iniziato a emergere vari piccoli problemi e, sebbene fosse una questione di dettaglio, era necessario modificare frequentemente la documentazione—quattro team diversi, ogni giorno, praticamente contemporaneamente, con discussioni. Tutte queste modifiche passavano attraverso un ingegnere—architetto. Il file del progetto era enorme e, di conseguenza, l'architetto era sommerso da un lavoro di routine legato a un gran numero di copiature, modifiche, commetteva molti errori, doveva ricontrollare tutto, rinviare tutto, e in generale era vicino al caos.
In questo caso, questo approccio, l'approccio al lavoro sul documento MS Word, ha funzionato con grande fatica e ha creato problemi.

Git, Markdown

Affrontando il problema descritto nell'esempio precedente, ho iniziato a esplorare questa questione.
Ho visto che l'uso di Markdown sta diventando sempre più popolare insieme a Git nella creazione di documenti.

Git è uno strumento per lo sviluppo. Ma perché non usarlo anche per il processo di documentazione? In questo caso, la questione del lavoro multiutente diventa risolta. Ma per sfruttare appieno le capacità di Git abbiamo bisogno di un formato di documento testuale, dobbiamo trovare un altro strumento, non MS Word, e per questo scopo Markdown è perfetto.

Markdown è un linguaggio di markup testuale semplice. È progettato per creare testi ben formattati in file di formato TXT normali. Se creiamo i nostri documenti in Markdown, allora la combinazione Markdown—Git appare naturale.

E tutto potrebbe andare bene, e in questo luogo si potrebbe mettere un punto, se non fosse per la nostra seconda condizione: "al termine abbiamo bisogno di un documento in un formato specifico, con gli attributi del corporate style, creato secondo un certo template" (e ci siamo accordati all'inizio che, per essere chiari, questo sarà MS Word). Cioè, se abbiamo deciso di usare Markdown, dobbiamo in qualche modo trasformare questo file in un .docx del tipo richiesto.

Esistono programmi di conversione tra vari formati, ad esempio, Pandoc.
Puoi convertire un file Markdown in formato .docx con questo programma.
Tuttavia, bisogna comprendere che, prima di tutto, non tutto ciò che è in Markdown sarà convertito in MS Word e, in secondo luogo, MS Word è un intero paese rispetto a un pacchetto snello, ma pur sempre una cittadina, Markdown. Esiste un'enorme quantità di cose in Word che non esistono in nessun modo in Markdown. Non si può semplicemente prendere e con determinati parametri convertire il tuo formato Markdown nel formato desiderato di MS Word con Pandoc. Quindi, di solito, dopo la conversione, è necessario "lavorare" manualmente sul documento .docx risultante, il che può anch'esso richiedere tempo e portare a errori.

Se potessimo scrivere uno script che completasse automaticamente ciò che Pandoc non è riuscito a gestire, sarebbe la soluzione ideale.

A causa della non corrispondenza delle funzionalità di MS Word e Markdown in generale, penso che sia impossibile risolvere questo compito, ma è possibile farlo riguardo a situazioni specifiche, requisiti specifici? La mia esperienza ha dimostrato che sì, è possibile e probabilmente è fattibile per molti, o forse addirittura per la maggior parte delle situazioni.

Soluzione di un compito specifico

Così, nel mio caso, dopo la conversione del file con Pandoc, ho dovuto elaborare manualmente i file, ovvero

aggiungere in Word dei campi con numerazione automatica delle intestazioni (caption) delle tabelle e delle immagini
cambiare lo stile per le tabelle

Non ho trovato come farlo con mezzi standard (Pandoc) o conosciuti. Quindi ho applicato uno script python con pywin32 pacchetto. Di conseguenza, ho ottenuto un'automazione completa. Ora posso convertire il mio file Markdown nella forma richiesta di un documento MS Word con un solo comando.

Guarda i dettagli qui.

Nota
In questo esempio, certamente, sto convertendo un file Markdown astratto, ma lo stesso approccio è stato applicato a un documento 'di lavoro', e come risultato ho ottenuto praticamente lo stesso documento MS Word che prima ottenevamo con la formattazione manuale.

In generale, con pywin32 otteniamo praticamente un controllo completo sul documento MS Word, il che ci consente di modificarlo e di portarlo allo stato richiesto dal vostro standard aziendale. Naturalmente, questi stessi obiettivi avrebbero potuto essere raggiunti anche utilizzando altri strumenti, come ad esempio i macro VBA, ma per me è stato più comodo utilizzare Python.

La formula breve di questo approccio è:

Markdown + Git -- (qualcosa) --> MS Word

Non è così importante cosa sia 'qualcosa'. Nel mio caso, era Pandoc e Python con pywin32. Potreste avere altre preferenze, ma l'importante è che sia possibile. Ed è questo il messaggio principale di questo articolo.

In sintesi, l'idea è che con questo approccio lavorate solo con il file Markdown e usate Git per organizzare la collaborazione e il controllo delle versioni, e solo se necessario (ad esempio, per fornire documentazione al cliente) create automaticamente un file nel formato richiesto (ad esempio, MS Word).

Processo

Penso che per molti la formula sopra sia sufficiente per capire come può ora essere organizzato il processo di lavoro con la documentazione. Tuttavia, di solito mi concentro sugli ingegneri di rete, quindi in generale mostrerò come può ora apparire il processo di lavoro e come differisce dall'approccio con la modifica dei file MS Word.

Per chiarezza, scegliamo GitHub come piattaforma di lavoro con Git. Dovete quindi creare un repository e posizionare il file o i file Markdown con cui intendete lavorare nel ramo master.

Esamineremo un semplice processo basato sul 'github flow'. La sua descrizione può essere trovata sia su Internet che su Habr.

Supponiamo che quattro persone stiano lavorando sulla documentazione e voi siate uno di loro. Vengono quindi create quattro rami aggiuntivi, ad esempio, con i nomi di queste persone. Ognuno lavora localmente, nel proprio ramo, e apporta modifiche con tutti i necessari comandi git.

Completando un determinato pezzo di lavoro, si crea una pull request, avviando così una discussione sulle proprie modifiche. Durante il processo di discussione, potrebbe emergere che è necessario aggiungere o modificare qualcos'altro. In questo caso, si apportano le modifiche necessarie e si crea una pull request aggiuntiva. Alla fine, le proprie modifiche vengono accettate e unite (merge) al branch master (o rifiutate).

Certo, questa è una descrizione piuttosto generale. Suggerisco di contattare i vostri sviluppatori o trovare persone esperte per creare un processo dettagliato. Ma voglio sottolineare che la barriera di ingresso a Git è piuttosto bassa. Questo non significa che il protocollo sia semplice, ma si può iniziare con qualcosa di elementare. Se non sapete proprio nulla, penso che dedicando alcune ore o forse giorni all'apprendimento e all'installazione, possiate iniziare a utilizzarlo.

Qual è il vantaggio di questo approccio rispetto, ad esempio, al processo descritto nell'esempio precedente?

In realtà, i processi sono abbastanza simili, hai solo sostituito

copiare un file -> creare un branch
copiare testo nel file finale -> unione (merge)
copiare le ultime modifiche a te stesso -> git pull/fetch
discussione tramite messaggi -> pull requests
track mode -> git diff
versione finale approvata -> branch master
backup (copia su server remoto) -> git push
…

In questo modo hai automatizzato tutto ciò che dovevi già fare, ma manualmente.

A un livello più alto, questo ti permette di

creare un processo chiaro, semplice e controllato per le modifiche alla documentazione
poiché il documento finale (nel nostro esempio MS Word) viene generato automaticamente, riduce la probabilità di errori legati alla formattazione.

Nota
Alla luce di quanto detto sopra, penso sia ovvio che, anche se lavori alla documentazione da solo, l'uso di Git può semplificare notevolmente il tuo lavoro.

Tutto ciò aumenta la qualità della documentazione e riduce il tempo necessario per crearla. E un ulteriore piccolo bonus: imparerai Git, il che ti aiuterà nell'automazione della tua rete 🙂

Come passare a un nuovo processo?

All'inizio dell'articolo ho scritto che già domani puoi iniziare a lavorare in un modo nuovo. Come puoi indirizzare il tuo lavoro verso una nuova direzione?

Ecco la sequenza di passaggi che probabilmente dovrai seguire:

se il tuo documento è molto grande, dividilo in parti
converti ogni parte in Markdown (ad esempio utilizzando Pandoc)
installa uno dei editor Markdown (io utilizzo Typora)
probabilmente dovrai sistemare la formattazione dei documenti Markdown creati
inizia a applicare il processo descritto nel capitolo precedente
contemporaneamente inizia a modificare lo script di conversione per il tuo compito (o crea qualcosa di tuo)

Non è necessario aspettare di aver creato e perfezionato alla perfezione il meccanismo di conversione Markdown -> il formato richiesto del documento finale. Infatti, anche se non riesci a automatizzare completamente e in modo rapido la procedura di conversione dei tuoi file Markdown, potrai comunque farlo in qualche forma usando Pandoc e poi portarlo alla forma finale manualmente. Di solito non è qualcosa che devi fare spesso, ma solo alla fine di determinati passaggi, e questo lavoro manuale, sebbene scomodo, è comunque, a mio avviso, del tutto accettabile nella fase di debugging e non dovrebbe rallentare troppo il processo.

Tutto il resto (Markdown, Git, Pandoc, Typora) è già pronto e non richiede sforzi o tempo particolari per iniziare a lavorarci.

Fonte: habr.com