{"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\/da\/blog\/administrirovanie\/ispolzujte-git-pri-dokumentirovanii","title":{"rendered":"Brug GIT i dokumentationen","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

Nogle gange kan ikke kun dokumentationen selv, men ogs\u00e5 processen med at arbejde med den v\u00e6re kritisk. For eksempel, i tilf\u00e6lde af projekter er en stor del af arbejdet forbundet med forberedelsen af dokumentationen, og en forkert proces kan f\u00f8re til fejl og endda tab af information, og dermed ogs\u00e5 tab af tid og gevinst. Men selv hvis dette emne ikke er centralt for dit arbejde og ligger p\u00e5 periferien, kan den rigtige proces stadig forbedre kvaliteten af dokumentet og spare dig tid.<\/p>\n

Den pr\u00e6senterede tilgang, med eksemplet p\u00e5 en konkret implementering<\/a><\/noindex>, har en lav indgangsbarriere. Teknisk set kan du allerede i morgen begynde at arbejde anderledes.
\n<\/a><\/noindex><\/p>\n

Problemformulering<\/h3>\n

\nDu skal oprette et eller andet dokument eller en r\u00e6kke dokumenter. Det kan v\u00e6re projektdokumentation eller protokollering af dit netv\u00e6rk, eller noget mere simpelt, som at du skal beskrive processer i virksomheden eller i din afdeling. Kort sagt handler det om ethvert dokument eller s\u00e6t af dokumenter med tekst, billeder, tabeller... Lad os g\u00f8re opgaven sv\u00e6rere, da <\/p>\n

    \n
  1. dette arbejde foruds\u00e6tter f\u00e6lles indsats, teamarbejde eller fra flere grupper af medarbejdere<\/li>\n
  2. og du \u00f8nsker at have et dokument i et bestemt format, med corporate style attributter, lavet efter en specifik skabelon. For tydelighedens skyld antager vi, at det er MS Word (.docx)<\/li>\n<\/ol>\n

    \nFor 10 \u00e5r siden ville tilgangen have v\u00e6ret entydig: vi ville have oprettet MS Word-dokument eller dokumenter og p\u00e5 en eller anden m\u00e5de organiseret arbejdet med \u00e6ndringer. <\/p>\n

    Og denne tilgang er stadig g\u00e6ldende. Den anvendes ogs\u00e5 af store integratorer til at oprette projektdokumentation. Men det er intuitivt klart, at hvis du virkelig arbejder intensivt, med mange rettelser og diskussioner, over en l\u00e6ngere periode p\u00e5 et dokument, er denne tilgang ikke s\u00e6rlig praktisk.<\/p>\n

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

    Jeg m\u00e6rkede skarpt dette problem, mens jeg arbejdede i en stor integrator. Processen for \u00e6ndringer i projektdokumentationen var som f\u00f8lger:<\/p>\n

      \n
    1. ingeni\u00f8ren downloader den seneste version af MS Word (.docx) dokumentet<\/li>\n
    2. \u00e6ndrer titlen<\/li>\n
    3. foretager \u00e6ndringer i track mode<\/li>\n
    4. sender dokumentet med \u00e6ndringer til arkitekten<\/li>\n
    5. sender ogs\u00e5 en liste over alle rettelser med kommentarer<\/li>\n
    6. arkitekten analyserer \u00e6ndringerne<\/li>\n
    7. hvis alt ser godt ud, kopierer han de \u00e6ndringer til filen med den seneste version, \u00e6ndrer versionen, og uploader den til den f\u00e6lles ressource<\/li>\n
    8. hvis der er bem\u00e6rkninger, initieres en diskussion (email eller m\u00f8der)<\/li>\n
    9. der opn\u00e5s enighed<\/li>\n
    10. herefter punkterne 3 - 9<\/li>\n<\/ol>\n

      \nIndtil arbejdet blev intensivt, fungerede det nogenlunde, men det virkede stadig. Men p\u00e5 et tidspunkt blev denne proces et flaskehals for hele projektet og f\u00f8rte til problemer. Problemet er, at alt bliver d\u00e5rligt, s\u00e5 snart \u00e6ndringer foretages ofte og samtidig af flere teams.<\/p>\n

      Da vi gik ind i fasen for pr\u00e6-testning, begyndte forskellige problemer at vise sig, og selvom de var sm\u00e5, var det n\u00f8dvendigt at \u00e6ndre dokumentationen ofte - fire forskellige teams, dagligt, n\u00e6sten samtidig, med diskussioner. Alle disse \u00e6ndringer gik gennem \u00e9n ingeni\u00f8r - arkitekten. Filen med designet var k\u00e6mpestor, og som f\u00f8lge deraf var arkitekten overbebyrdet med rutinearbejde, der involverede meget kopiering og redigering, lavede mange fejl, det skulle kontrolleres, genfremsendes, og det hele var t\u00e6t p\u00e5 kaos. <\/p>\n

      I dette tilf\u00e6lde fungerede denne metode, MS Word dokumentarbejdsmetoden, med stor besv\u00e6r og skabte problemer.<\/p><\/blockquote>\n

      <\/p>\n

      Git, Markdown<\/h3>\n

      \nDa jeg st\u00f8dte p\u00e5 problemet beskrevet i det ovenst\u00e5ende eksempel, begyndte jeg at unders\u00f8ge dette emne.
      \nJeg s\u00e5, at det bliver mere og mere popul\u00e6rt at bruge       Markdown<\/a><\/noindex> sammen med Git<\/a><\/noindex> til at oprette dokumenter.<\/p>\n

      Git er et udviklingsv\u00e6rkt\u00f8j. Men hvorfor ikke bruge det til dokumentationsprocessen? I s\u00e5 fald bliver sp\u00f8rgsm\u00e5let om flerbrugerarbejde l\u00f8st. Men for at kunne udnytte Gits muligheder fuldt ud har vi brug for et tekstformatdokument, vi skal finde et andet v\u00e6rkt\u00f8j, ikke MS Word, og til disse form\u00e5l passer Markdown perfekt. <\/p>\n

      Markdown er et simpelt tekstmarkup-sprog. Det er designet til at skabe smukt formaterede tekster i almindelige TXT-filer. Hvis vi opretter vores dokumenter i Markdown, ser kombinationen Markdown - Git naturlig ud.<\/p>\n

      Altogether, this situation could have been resolved if it weren\u2019t for our second condition: 'we need a document in a specific format, with corporate style attributes, created according to a certain template' (and we agreed at the beginning that to be specific, this would be MS Word). In other words, if we decided to use Markdown, we need some way to convert this file to .docx in the required format.<\/p>\n

      There are conversion programs between various formats, such as Pandoc<\/a><\/noindex>.
      \nYou can convert a Markdown file to .docx format using this program.
      \nHowever, it is important to understand that, firstly, not everything present in Markdown will be converted to MS Word, and secondly, MS Word is a whole country compared to the well-structured, yet small town of Markdown. There is a huge amount of content available in Word that is absent in Markdown. You cannot simply convert your Markdown format to the desired MS Word format using specific keys in Pandoc. So typically, after conversion, one has to 'refine' the resulting .docx document manually, which can again be time-consuming and lead to errors.<\/p>\n

      If we could write a script that would automatically 'finish' what Pandoc couldn\u2019t handle\u2014this would be the ideal solution.<\/p>\n

      Due to the non-equivalence of the functionalities of MS Word and Markdown in general, I believe it is impossible to solve this task; however, can it be done in specific situations with concrete requirements? My experience has shown that yes, it is possible and likely achievable for many, if not most, situations. <\/p>\n

      Solving a specific issue<\/h3>\n

      \nThus, in my case, after converting the file using Pandoc, I had to manually perform additional processing on the files, namely,<\/p>\n