{"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":"Usa GIT nella documentazione","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

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

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

Definizione del compito<\/h3>\n

\nDovete creare un documento o un insieme di documenti. Potrebbe trattarsi di documentazione di progetto o della registrazione della vostra rete, o qualcosa di pi\u00f9 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 <\/p>\n

    \n
  1. questo lavoro richiede un impegno collettivo, lo sforzo di un gruppo o di pi\u00f9 gruppi di collaboratori.<\/li>\n
  2. 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)<\/li>\n<\/ol>\n

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

    E tale approccio \u00e8 ancora valido. \u00c8 utilizzato anche da grandi integratori per la creazione di documentazione di progetto. Ma \u00e8 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 \u00e8 molto comodo.<\/p>\n

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

    Ho percepito acutamente questo problema lavorando in uno dei grandi integratori. 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 titolo<\/li>\n
    3. apporta le modifiche in modalit\u00e0 track<\/li>\n
    4. invita il documento con le modifiche all'architetto<\/li>\n
    5. invia anche l'elenco di tutte le correzioni con commenti<\/li>\n
    6. l'architetto analizza le modifiche<\/li>\n
    7. se tutto va bene, copia le modifiche dei dati nel file con l'ultima versione, aggiorna la versione e pubblica sul repository condiviso<\/li>\n
    8. se ci sono osservazioni, si avvia 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 intensivo, ha funzionato in qualche modo, ma a un certo punto questo processo \u00e8 diventato un collo di bottiglia per l'intero progetto, portando a problemi. Il punto \u00e8 che tutto va male non appena le modifiche vengono effettuate frequentemente e contemporaneamente da pi\u00f9 team.<\/p>\n

      Cos\u00ec, 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 \u2014 quattro team diversi, quotidianamente, praticamente contemporaneamente, con discussioni. Tutte queste modifiche passavano attraverso un ingegnere \u2014 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. <\/p>\n

      In questo caso, questo approccio, il lavoro con il documento MS Word, ha funzionato con grande difficolt\u00e0 e ha creato problemi.<\/p><\/blockquote>\n

      <\/p>\n

      Git, Markdown<\/h3>\n

      \nAffrontando il problema descritto nell'esempio precedente, ho iniziato a esplorare la questione.
      \nHo notato che sta diventando sempre pi\u00f9 popolare l'uso di       Markdown<\/a><\/noindex> in collaborazione con Git<\/a><\/noindex> la 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 della collaborazione diventa risolta. Tuttavia, per sfruttare appieno le potenzialit\u00e0 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 \u00e8 perfetto. <\/p>\n

      Markdown \u00e8 un semplice linguaggio di markup testuale. \u00c8 progettato per creare testi ben formattati in file di formato TXT. Se creiamo i nostri documenti in Markdown, l'accoppiata Markdown-Git appare naturale.<\/p>\n

      E tutto sarebbe a posto, e qui potremmo mettere un punto se non fosse per la nostra seconda condizione: \u00aballa fine abbiamo bisogno di un documento in un formato specifico, con attributi di corporate identity, creato seguendo un determinato modello\u00bb (e abbiamo concordato all'inizio che per chiarezza questo sar\u00e0 MS Word). Quindi, se abbiamo deciso di utilizzare Markdown, dobbiamo in qualche modo convertire questo file nel formato .docx 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.
      \nMa bisogna comunque comprendere che, innanzitutto, non tutto ci\u00f2 che esiste in Markdown sar\u00e0 convertito in MS Word e, in secondo luogo, MS Word \u00e8 un intero universo rispetto al compatto, ma pur sempre piccolo, Markdown. Ci sono enormi quantit\u00e0 di funzionalit\u00e0 presenti in Word e non in alcun modo disponibili in Markdown. Non si pu\u00f2 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, \u00e8 necessario \u00abrivedere\u00bb il documento .docx ottenuto manualmente, il che pu\u00f2 comunque richiedere tempo e portare a errori.<\/p>\n

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

      Dato che le funzionalit\u00e0 di MS Word e Markdown non sono equivalenti in generale, penso che sia impossibile risolvere questo problema, ma \u00e8 possibile farlo per situazioni specifiche e requisiti concreti? La mia esperienza ha dimostrato che s\u00ec, \u00e8 possibile e probabilmente lo \u00e8 per molte, se non per la maggior parte delle situazioni. <\/p>\n

      Soluzione a un problema specifico<\/h3>\n

      \nNel mio caso, dopo aver convertito un file utilizzando Pandoc, dovevo eseguire una lavorazione manuale dei file, in particolare<\/p>\n