{"id":35419,"date":"2019-10-31T22:04:14","date_gmt":"2019-10-31T19:04:14","guid":{"rendered":"https:\/\/prohoster.info\/blog\/ispolzujte-git-pri-dokumentirovanii\/"},"modified":"2019-10-31T22:04:14","modified_gmt":"2019-10-31T19:04:14","slug":"ispolzujte-git-pri-dokumentirovanii","status":"publish","type":"post","link":"https:\/\/prohoster.info\/it\/blog\/administrirovanie\/ispolzujte-git-pri-dokumentirovanii","title":{"rendered":"Utilizzare GIT per la documentazione","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

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

L'approccio qui esposto, con un esempio di implementazione concreta<\/a><\/noindex>, ha una soglia di ingresso bassa. Tecnologicamente, gi\u00e0 domani potreste iniziare a lavorare in modo nuovo.
\n<\/a><\/noindex><\/p>\n

Definizione del compito<\/h3>\n

\nDovete 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\u00f9 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 <\/p>\n

    \n
  1. questo lavoro richiede collaborazione, sforzi di un gruppo o di pi\u00f9 gruppi di dipendenti<\/li>\n
  2. 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)<\/li>\n<\/ol>\n

    \nDieci 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. <\/p>\n

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

    Esempio<\/b><\/p>\n

    Ho avvertito questa problematica piuttosto acutamente, lavorando per un grande integratore. Il processo di modifica della documentazione di progetto era il seguente:<\/p>\n

      \n
    1. l'ingegnere scarica l'ultima versione del documento MS Word (.docx)<\/li>\n
    2. cambia il nome<\/li>\n
    3. apporta modifiche in modalit\u00e0 track<\/li>\n
    4. invia il documento con le modifiche all'architetto<\/li>\n
    5. invia anche un elenco di tutte le correzioni con commenti<\/li>\n
    6. l'architetto analizza le modifiche<\/li>\n
    7. se tutto \u00e8 a posto, copia le modifiche nel file con l'ultima versione, cambia la versione e la carica su una risorsa condivisa<\/li>\n
    8. se ci sono osservazioni, viene avviata una discussione (email o riunioni)<\/li>\n
    9. si raggiunge un consenso<\/li>\n
    10. poi i punti 3 - 9<\/li>\n<\/ol>\n

      \nFinch\u00e9 il lavoro non \u00e8 stato intenso, ha funzionato in qualche modo, ma ha funzionato. Ma a un certo punto questo processo \u00e8 diventato un collo di bottiglia per l'intero progetto e ha portato a problemi. Il problema \u00e8 che tutto va male non appena le modifiche vengono apportate frequentemente e simultaneamente da pi\u00f9 team.<\/p>\n

      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\u2014quattro team diversi, ogni giorno, praticamente contemporaneamente, con discussioni. Tutte queste modifiche passavano attraverso un ingegnere\u2014architetto. 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. <\/p>\n

      In questo caso, questo approccio, l'approccio al lavoro sul documento MS Word, ha funzionato con grande fatica e ha creato problemi.<\/p><\/blockquote>\n

      <\/p>\n

      Git, Markdown<\/h3>\n

      \nAffrontando il problema descritto nell'esempio precedente, ho iniziato a esplorare questa questione.
      \nHo visto che l'uso di       Markdown<\/a><\/noindex> sta diventando sempre pi\u00f9 popolare insieme a Git<\/a><\/noindex> nella creazione di documenti.<\/p>\n

      Git \u00e8 uno strumento per lo sviluppo. Ma perch\u00e9 non usarlo anche per il processo di documentazione? In questo caso, la questione del lavoro multiutente diventa risolta. Ma per sfruttare appieno le capacit\u00e0 di Git abbiamo bisogno di un formato di documento testuale, dobbiamo trovare un altro strumento, non MS Word, e per questo scopo Markdown \u00e8 perfetto. <\/p>\n

      Markdown \u00e8 un linguaggio di markup testuale semplice. \u00c8 progettato per creare testi ben formattati in file di formato TXT normali. Se creiamo i nostri documenti in Markdown, allora la combinazione Markdown\u2014Git appare naturale.<\/p>\n

      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\u00e0 MS Word). Cio\u00e8, se abbiamo deciso di usare Markdown, dobbiamo in qualche modo trasformare questo file in un .docx del tipo richiesto.<\/p>\n

      Esistono programmi di conversione tra vari formati, ad esempio, Pandoc<\/a><\/noindex>.
      \nPuoi convertire un file Markdown in formato .docx con questo programma.
      \nTuttavia, bisogna comprendere che, prima di tutto, non tutto ci\u00f2 che \u00e8 in Markdown sar\u00e0 convertito in MS Word e, in secondo luogo, MS Word \u00e8 un intero paese rispetto a un pacchetto snello, ma pur sempre una cittadina, Markdown. Esiste un'enorme quantit\u00e0 di cose in Word che non esistono in nessun modo in Markdown. Non si pu\u00f2 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, \u00e8 necessario \"lavorare\" manualmente sul documento .docx risultante, il che pu\u00f2 anch'esso richiedere tempo e portare a errori.<\/p>\n

      Se potessimo scrivere uno script che completasse automaticamente ci\u00f2 che Pandoc non \u00e8 riuscito a gestire, sarebbe la soluzione ideale.<\/p>\n

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

      Soluzione di un compito specifico<\/h3>\n

      \nCos\u00ec, nel mio caso, dopo la conversione del file con Pandoc, ho dovuto elaborare manualmente i file, ovvero<\/p>\n