{"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\/no\/blog\/administrirovanie\/ispolzujte-git-pri-dokumentirovanii","title":{"rendered":"Bruk GIT ved dokumentasjon","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

Noen ganger kan ikke bare dokumentasjonen, men ogs\u00e5 arbeidsprosessen v\u00e6re kritisk. For eksempel, i prosjekt er en stor del av arbeidet knyttet til forberedelse av dokumentasjon, og en feil prosess kan f\u00f8re til feil og til og med tap av informasjon, og dermed ogs\u00e5 tap av tid og gevinst. Men selv om dette temaet kanskje ikke er sentralt i arbeidet ditt og ligger p\u00e5 periferien, kan en riktig prosess fremdeles forbedre kvaliteten p\u00e5 dokumentet og spare deg for tid.<\/p>\n

Tiln\u00e6rmingen som er beskrevet her, med et eksempel p\u00e5 konkret implementering<\/a><\/noindex>, har lav terskel for inngang. Teknisk sett kan du begynne \u00e5 jobbe p\u00e5 en ny m\u00e5te allerede i morgen.
\n<\/a><\/noindex><\/p>\n

Definering av oppgaven<\/h3>\n

\nDu m\u00e5 lage et visst dokument eller et sett med dokumenter. Det kan v\u00e6re prosjektstyringsdokumentasjon eller logging av nettverket ditt, eller noe enklere, for eksempel at du m\u00e5 beskrive prosesser i firmaet eller i avdelingen din. Generelt handler det om hvilket som helst dokument eller sett med dokumenter med tekst, bilder, tabeller\u2026 Vi kompliserer oppgaven ved at <\/p>\n

    \n
  1. dette arbeidet forutsetter samarbeid, innsats fra en gruppe eller flere grupper ansatte<\/li>\n
  2. og p\u00e5 utgangen vil du ha et dokument i et bestemt format, med egenskaper for bedriftsstil, laget etter en bestemt mal. For klarhetens skyld vil vi anta at dette er MS Word (.docx)<\/li>\n<\/ol>\n

    \nFor 10 \u00e5r siden ville tiln\u00e6rmingen v\u00e6rt entydig: vi ville laget et MS Word-dokument eller dokumenter og p\u00e5 en eller annen m\u00e5te organisert arbeidet med endringer. <\/p>\n

    Og denne tiln\u00e6rmingen er fortsatt i bruk. Den benyttes ogs\u00e5 av store integratorer n\u00e5r de lager prosjekt-dokumentasjon. Men det er intuitivt forst\u00e5tt at hvis du virkelig jobber intensivt, med mange endringer og diskusjoner, over en lengre periode med et dokument, er denne tiln\u00e6rmingen ikke s\u00e6rlig praktisk.<\/p>\n

    Eksempel<\/b><\/p>\n

    Jeg opplevde dette problemet ganske sterkt da jeg jobbet hos en stor integrator. Prosessen med \u00e5 endre prosjekt-dokumentasjonen var som f\u00f8lger:<\/p>\n

      \n
    1. ingeni\u00f8ren laster ned den nyeste versjonen av MS Word (.docx) dokumentet<\/li>\n
    2. ender navnet<\/li>\n
    3. gj\u00f8r endringer i sporingsmodus<\/li>\n
    4. sender dokumentet med endringene til arkitekten<\/li>\n
    5. sender ogs\u00e5 en liste over alle korrigeringer med kommentarer<\/li>\n
    6. arkitekten analyserer endringene<\/li>\n
    7. hvis alt ser bra ut, kopierer han disse endringene til filen med den nyeste versjonen, endrer versjonen og legger den ut p\u00e5 fellesressursen<\/li>\n
    8. hvis det er kommentarer, s\u00e5 settes det i gang en diskusjon (e-post eller m\u00f8ter)<\/li>\n
    9. det oppn\u00e5s enighet<\/li>\n
    10. videre punkt 3 \u2014 9<\/li>\n<\/ol>\n

      \nS\u00e5 lenge arbeidet ikke var intensivt, fungerte det i det minste s\u00e5nn noenlunde. Men p\u00e5 et tidspunkt ble denne prosessen et flaskehals for hele prosjektet og f\u00f8rte til problemer. Problemet er at alt blir vanskelig s\u00e5 snart endringer skjer ofte og samtidig av flere team.<\/p>\n

      Da vi kom til stadiet for forh\u00e5ndstesting, begynte det \u00e5 dukke opp forskjellige problemer, og selv om de var sm\u00e5, m\u00e5tte dokumentasjonen ofte oppdateres \u2014 fire forskjellige team, daglig, nesten samtidig, med diskusjoner. Alle disse endringene ble h\u00e5ndtert av \u00e9n ingeni\u00f8r \u2014 arkitekten. Prosjektdokumentet var enormt, og som et resultat var arkitekten overveldet med rutinearbeid, med mye kopiering, redigering, han gjorde mange feil, m\u00e5tte sjekke alt p\u00e5 nytt, resendte det, og generelt var det n\u00e6r kaos. <\/p>\n

      I dette tilfellet fungerte denne tiln\u00e6rmingen, tiln\u00e6rmingen til \u00e5 jobbe med MS Word-dokumentet, med stor motstand og skapte problemer.<\/p><\/blockquote>\n

      <\/p>\n

      Git, Markdown<\/h3>\n

      \nN\u00e5r jeg m\u00f8tte problemet beskrevet i eksempelet ovenfor, begynte jeg \u00e5 unders\u00f8ke dette sp\u00f8rsm\u00e5let.
      \nJeg la merke til at det blir mer og mer popul\u00e6rt \u00e5 bruke       Markdown<\/a><\/noindex> sammen med Git<\/a><\/noindex> for \u00e5 lage dokumenter.<\/p>\n

      Git er et utviklingsverkt\u00f8y. Men hvorfor ikke bruke det til dokumentasjonsprosessen? I s\u00e5 fall blir sp\u00f8rsm\u00e5let om flerbrukerarbeid l\u00f8st. Men for \u00e5 fullt ut utnytte Git sine muligheter trenger vi et tekstformat for dokumentet, vi m\u00e5 finne et annet verkt\u00f8y, ikke MS Word, og for disse form\u00e5lene passer Markdown utmerket. <\/p>\n

      Markdown er et enkelt tekstmerkingsspr\u00e5k. Det er designet for \u00e5 lage pent formaterte tekster i vanlige TXT-filer. Hvis vi lager dokumentene v\u00e5re i Markdown, ser samspillet mellom Markdown og Git naturlig ut.<\/p>\n

      Alt er bra, og p\u00e5 dette punktet kunne vi hatt en avslutning, hvis det ikke hadde v\u00e6rt for v\u00e5rt andre vilk\u00e5r: \u00abVi trenger et dokument i et bestemt format, med attributter for bedriftsstil, laget etter en spesifikk mal\u00bb (og vi ble enige i starten om at dette skulle v\u00e6re MS Word). Med andre ord, hvis vi bestemte oss for \u00e5 bruke Markdown, m\u00e5 vi p\u00e5 en eller annen m\u00e5te konvertere denne filen til .docx i \u00f8nsket format.<\/p>\n

      Det finnes programmer for konvertering mellom ulike formater, for eksempel, Pandoc<\/a><\/noindex>.
      \nDu kan konvertere Markdown-filen til .docx-format med dette programmet.
      \nMen man m\u00e5 likevel forst\u00e5 at, f\u00f8rst og fremst, ikke alt i Markdown vil bli konvertert til MS Word og, for det andre, MS Word er et helt landskap sammenlignet med den stramme, men dog lille byen, Markdown. Det er en enorm mengde funksjoner i Word som ikke eksisterer i markdown. Man kan ikke bare ta og konvertere formatet ditt fra Markdown til det \u00f8nskede utseendet i MS Word med spesifikke n\u00f8kler fra Pandoc. S\u00e5 vanligvis, etter konvertering, m\u00e5 man \u00abferdigstille\u00bb den produserte .docx-filen manuelt, noe som igjen kan v\u00e6re tidkrevende og f\u00f8re til feil.<\/p>\n

      Hvis vi kunne skrevet et skript som automatisk \u00abferdigstilte\u00bb det som Pandoc ikke klarte \u2014 det ville v\u00e6rt den ideelle l\u00f8sningen.<\/p>\n

      P\u00e5 grunn av ulikheten i funksjonaliteten mellom MS Word og Markdown generelt, tror jeg det er umulig \u00e5 l\u00f8se denne oppgaven, men kan dette gj\u00f8res med hensyn til spesifikke situasjoner og krav? Min erfaring har vist at ja, det kan gj\u00f8res, og det er sannsynligvis mulig for mange, eller kanskje selv de fleste situasjoner. <\/p>\n

      L\u00f8sningen p\u00e5 et spesifikt problem<\/h3>\n

      \nS\u00e5, i mitt tilfelle, etter \u00e5 ha konvertert filen med Pandoc, m\u00e5tte jeg manuelt utf\u00f8re ytterligere behandling av filene, nemlig<\/p>\n