🥇Usa GIT per la documentazione

A volte, non solo la documentazione stessa, ma anche il processo di creazione può essere critico. Ad esempio, in progetti, gran parte del lavoro è dedicata proprio alla preparazione della documentazione; un processo errato può portare a errori e persino alla perdita di informazioni, con conseguente perdita di tempo e opportunità. Anche se questo tema non è centrale nel vostro lavoro e si trova sullo sfondo, avere un processo corretto può migliorare la qualità del documento e farvi risparmiare tempo.

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

Definizione del compito

Dovete creare un documento o un insieme di documenti. Potrebbe trattarsi di documentazione di progetto o della registrazione della vostra rete, o qualcosa di più semplice, ad esempio, descrivere i processi all'interno dell'azienda o del vostro reparto. In generale, si tratta di qualsiasi documento o insieme di documenti con testo, immagini, tabelle... Difficilitiamo la questione dato che

questo lavoro richiede un impegno collettivo, lo sforzo di un gruppo o di più gruppi di collaboratori.
alla fine desideri avere un documento in un formato specifico, con attributi di stile aziendale, creato secondo un determinato modello. Per chiarezza, considereremo che si tratti di MS Word (.docx)

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

E tale approccio è ancora valido. È utilizzato anche da grandi integratori per la creazione di documentazione di progetto. Ma è intuitivo che, se stai effettivamente lavorando in modo intenso, con molte modifiche e discussioni, per un lungo periodo di tempo su un documento, questo approccio non è molto comodo.

Esempio
Ho percepito acutamente questo problema lavorando in uno dei grandi integratori. Il processo di modifica della documentazione di progetto era il seguente:

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

cambia il titolo

apporta le modifiche in modalità track

invita il documento con le modifiche all'architetto

invia anche l'elenco di tutte le correzioni con commenti

l'architetto analizza le modifiche

se tutto va bene, copia le modifiche dei dati nel file con l'ultima versione, aggiorna la versione e pubblica sul repository condiviso

se ci sono osservazioni, si avvia una discussione (email o riunioni)

si raggiunge un consenso

poi i punti 3-9
Finché il lavoro non è stato intensivo, ha funzionato in qualche modo, ma a un certo punto questo processo è diventato un collo di bottiglia per l'intero progetto, portando a problemi. Il punto è che tutto va male non appena le modifiche vengono effettuate frequentemente e contemporaneamente da più team.
Così, quando siamo passati alla fase di test preliminari, hanno iniziato a emergere diversi problemi e, anche se erano piccole cose, era necessario aggiornare frequentemente la documentazione — quattro team diversi, quotidianamente, praticamente contemporaneamente, con discussioni. Tutte queste modifiche passavano attraverso un ingegnere — l'architetto. Il file del progetto era enorme e, di conseguenza, l'architetto era sommerso da un lavoro routinario che comportava molte copie, modifiche, e commetteva molti errori, rendendo necessario ricontrollare tutto, rinviare, e in generale ci si avvicinava al caos.
In questo caso, questo approccio, il lavoro con il documento MS Word, ha funzionato con grande difficoltà e ha creato problemi.

Git, Markdown

Affrontando il problema descritto nell'esempio precedente, ho iniziato a esplorare la questione.
Ho notato che sta diventando sempre più popolare l'uso di Markdown in collaborazione con Git la creazione di documenti.

Git è uno strumento per lo sviluppo. Ma perché non usarlo anche per il processo di documentazione? In questo caso, la questione della collaborazione diventa risolta. Tuttavia, per sfruttare appieno le potenzialità di Git abbiamo bisogno di un formato testuale per il documento, dobbiamo trovare un altro strumento che non sia MS Word, e per questi scopi Markdown è perfetto.

Markdown è un semplice linguaggio di markup testuale. È progettato per creare testi ben formattati in file di formato TXT. Se creiamo i nostri documenti in Markdown, l'accoppiata Markdown-Git appare naturale.

E tutto sarebbe a posto, e qui potremmo mettere un punto se non fosse per la nostra seconda condizione: «alla fine abbiamo bisogno di un documento in un formato specifico, con attributi di corporate identity, creato seguendo un determinato modello» (e abbiamo concordato all'inizio che per chiarezza questo sarà MS Word). Quindi, se abbiamo deciso di utilizzare Markdown, dobbiamo in qualche modo convertire questo file nel formato .docx richiesto.

Esistono programmi di conversione tra vari formati, ad esempio, Pandoc.
Puoi convertire un file Markdown in formato .docx con questo programma.
Ma bisogna comunque comprendere che, innanzitutto, non tutto ciò che esiste in Markdown sarà convertito in MS Word e, in secondo luogo, MS Word è un intero universo rispetto al compatto, ma pur sempre piccolo, Markdown. Ci sono enormi quantità di funzionalità presenti in Word e non in alcun modo disponibili in Markdown. Non si può semplicemente prendere e convertire il tuo formato Markdown nel formato desiderato di MS Word usando Pandoc con chiavi specifiche. Quindi di solito, dopo la conversione, è necessario «rivedere» il documento .docx ottenuto manualmente, il che può comunque richiedere tempo e portare a errori.

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

Dato che le funzionalità di MS Word e Markdown non sono equivalenti in generale, penso che sia impossibile risolvere questo problema, ma è possibile farlo per situazioni specifiche e requisiti concreti? La mia esperienza ha dimostrato che sì, è possibile e probabilmente lo è per molte, se non per la maggior parte delle situazioni.

Soluzione a un problema specifico

Nel mio caso, dopo aver convertito un file utilizzando Pandoc, dovevo eseguire una lavorazione manuale dei file, in particolare

aggiungere in Word i campi con numerazione automatica per i titoli (caption) di tabelle e immagini
modificare lo stile delle tabelle

Non sono riuscito a trovare un modo per farlo con strumenti standard (Pandoc) o noti. Pertanto, ho utilizzato uno script Python con pywin32 package. Di conseguenza, ho ottenuto un'automazione completa. Ora posso convertire il mio file Markdown nella forma necessaria di un documento MS Word con un solo comando.

Vedi i dettagli qui.

Nota
In questo esempio, ovviamente, trasformerò un file Markdown astratto, ma lo stesso approccio è stato applicato a un documento 'reale', e alla fine ho ottenuto praticamente lo stesso documento MS Word che prima ottenevamo tramite formattazione manuale.

In generale, con pywin32 abbiamo praticamente il controllo completo su un documento MS Word, il che consente di modificarlo e di adattarlo agli standard aziendali richiesti. Certo, sarebbe stato possibile raggiungere questi obiettivi anche con altri strumenti, come i macro VBA, ma personalmente ho trovato più comodo usare 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. Potresti avere altre preferenze, ma la cosa importante è che è possibile. E questo è il messaggio principale di questo articolo.

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

Processo

Penso che per molti la formula sopra sia sufficiente per comprendere come ora possa essere organizzato il processo di gestione della documentazione. Tuttavia, di solito mi rivolgo agli ingegneri di rete, quindi in generale mostrerò come potrebbe apparire il processo di lavoro e in che modo si differenzia dall'approccio di modifica dei file MS Word.

Per chiarezza, prendiamo GitHub come piattaforma per lavorare con Git. Dovrete quindi creare un repository e posizionare il file o i file Markdown nella branch master con cui intendete lavorare.

Esamineremo un processo semplice basato su "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. Verranno quindi create quattro branch aggiuntive, ad esempio con i nomi di queste persone. Ognuno lavora localmente, nella propria branch e apporta modifiche con tutti i comandi necessari git..

Dopo aver completato un certo lavoro, crei una pull request, avviando così la discussione sulle tue modifiche. Durante il dibattito, potrebbe emergere che devi aggiungere o modificare qualcos'altro. In tal caso, apporti le modifiche necessarie e crei un'ulteriore pull request. Alla fine, le tue modifiche vengono accettate e unite (merge) al ramo master (o vengono rifiutate).

Certo, questa è una descrizione piuttosto generale. Ti consiglio di contattare i tuoi sviluppatori o trovare persone esperte per creare un processo dettagliato. Ma voglio sottolineare che la barriera d'ingresso in Git è abbastanza bassa. Questo non significa che il protocollo sia semplice, ma puoi iniziare con qualcosa di base. Se non sai nulla, penso che dopo aver dedicato alcune ore o forse giorni allo studio e all'installazione, puoi iniziare a usarlo.

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

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

copiare un file -> creare un ramo (branch)
copiare il testo nel file finale -> unire (merge)
copia delle ultime modifiche -> git pull/fetch
discussione nella corrispondenza -> pull requests
modalità di tracciamento -> git diff
ultima versione approvata -> ramo master
backup (copia su server remoto) -> git push
…

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

A un livello più alto, questo ti permette di

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

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

Tutto ciò migliora la qualità della documentazione e riduce il tempo necessario per realizzarla. E un ulteriore vantaggio — imparerai Git, il che ti sarà utile per l'automazione della tua rete 🙂

Come passare al nuovo processo?

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

Ecco la sequenza di passaggi che probabilmente dovrai eseguire:

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

Non è necessario aspettare di avere perfezionato il meccanismo di conversione Markdown -> il formato richiesto del documento finale. Anche se non riesci a automatizzare rapidamente completamente la procedura di conversione dei tuoi file Markdown, potrai comunque farlo in qualche modo con Pandoc e poi perfezionarlo manualmente. Di solito non è necessario farlo frequentemente, ma solo al termine di determinate fasi, e questo lavoro manuale, anche se scomodo, è comunque, a mio avviso, abbastanza 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