{"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\/sv\/blog\/administrirovanie\/ispolzujte-git-pri-dokumentirovanii","title":{"rendered":"Anv\u00e4nd GIT vid dokumentation","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

Ibland \u00e4r det inte bara sj\u00e4lva dokumentationen som \u00e4r kritisk, utan \u00e4ven processen att arbeta med den. Till exempel, i projekten utg\u00f6r en stor del av arbetet sj\u00e4lva f\u00f6rberedelsen av dokumentationen och en felaktig process kan leda till misstag och till och med f\u00f6rlust av information, vilket i sin tur kan leda till f\u00f6rlust av tid och vinster. Men \u00e4ven om detta tema inte \u00e4r centralt i ditt arbete och ligger p\u00e5 periferin, kan r\u00e4tt process fortfarande f\u00f6rb\u00e4ttra kvaliteten p\u00e5 dokumentet och spara tid.<\/p>\n

Den h\u00e4r metoden, med ett exempel p\u00e5 specifik implementering<\/a><\/noindex>, har en l\u00e5g tr\u00f6skel f\u00f6r intr\u00e4de. Tekniskt sett kan du b\u00f6rja arbeta p\u00e5 ett nytt s\u00e4tt redan imorgon.
\n<\/a><\/noindex><\/p>\n

Uppgiftsst\u00e4llande<\/h3>\n

\nDu beh\u00f6ver skapa n\u00e5got dokument eller en upps\u00e4ttning dokument. Kanske handlar det om projektdokumentation eller loggning av ditt n\u00e4tverk, eller n\u00e5got enklare, som att du m\u00e5ste beskriva processerna i f\u00f6retaget eller avdelningen. Det handlar om vilket dokument eller upps\u00e4ttning dokument som helst med text, bilder, tabeller\u2026 Vi komplicerar uppgiften genom att <\/p>\n

    \n
  1. detta arbete f\u00f6ruts\u00e4tter samarbete, insatser fr\u00e5n en grupp eller flera grupper av medarbetare<\/li>\n
  2. och slutresultatet \u00e4r att du vill ha ett dokument i ett visst format, med egenskaper som f\u00f6ljer f\u00f6retagets stil, skapat enligt en viss mall. F\u00f6r tydlighetens skull kommer vi att anta att det handlar om MS Word (.docx)<\/li>\n<\/ol>\n

    \nF\u00f6r 10 \u00e5r sedan hade tillv\u00e4gag\u00e5ngss\u00e4ttet varit entydigt: vi skulle ha skapat ett eller flera MS Word-dokument och organiserat arbetet med att g\u00f6ra \u00e4ndringar p\u00e5 n\u00e5got s\u00e4tt. <\/p>\n

    Och det tillv\u00e4gag\u00e5ngss\u00e4ttet g\u00e4ller fortfarande. Det anv\u00e4nds \u00e4ven av stora integrat\u00f6rer vid skapandet av projektdokumentation. Men det \u00e4r intuitivt klart att om du arbetar intensivt med m\u00e5nga \u00e4ndringar och diskussioner under en l\u00e4ngre tid, \u00e4r detta tillv\u00e4gag\u00e5ngss\u00e4tt inte s\u00e4rskilt bekv\u00e4mt.<\/p>\n

    Exempel<\/b><\/p>\n

    Jag k\u00e4nde av detta problem ganska tydligt n\u00e4r jag arbetade p\u00e5 en stor integrator. Processen f\u00f6r att \u00e4ndra projektdokumentationen s\u00e5g ut som f\u00f6ljande:<\/p>\n

      \n
    1. ingenj\u00f6ren laddar ner den senaste versionen av MS Word-dokumentet (.docx)<\/li>\n
    2. \u00e4ndrar namnet<\/li>\n
    3. g\u00f6r \u00e4ndringar i sp\u00e5rningsl\u00e4ge<\/li>\n
    4. skickar dokumentet med \u00e4ndringarna till arkitekten<\/li>\n
    5. skickar ocks\u00e5 en lista med alla korrigeringar och kommentarer<\/li>\n
    6. arkitekten analyserar \u00e4ndringarna<\/li>\n
    7. om allt g\u00e5r bra, kopierar den data\u00e4ndringarna till filen med den senaste versionen, \u00e4ndrar versionen och l\u00e4gger ut den p\u00e5 en gemensam resurs<\/li>\n
    8. om det finns inv\u00e4ndningar initieras en diskussion (e-post eller m\u00f6ten)<\/li>\n
    9. konsensus uppn\u00e5s<\/li>\n
    10. d\u00e4refter punkterna 3\u20139<\/li>\n<\/ol>\n

      \nN\u00e4r arbetet inte var intensivt funkade det i alla fall, men vid en viss punkt blev denna process det svaga l\u00e4nken i hela projektet och ledde till problem. Det handlar om att allt g\u00e5r snett s\u00e5 snart \u00e4ndringar g\u00f6rs ofta och samtidigt av flera team.<\/p>\n

      S\u00e5 n\u00e4r vi gick in i fasen av prelimin\u00e4r testning b\u00f6rjade olika problem dyka upp, och \u00e4ven om de var sm\u00e5 beh\u00f6vde dokumentationen \u00e4ndras ofta \u2014 fyra olika team, dagligen, praktiskt taget samtidigt, med diskussioner. Alla dessa \u00e4ndringar gick genom en ingenj\u00f6r \u2014 arkitekten. Projektets designfil var enorm, och som f\u00f6ljd av detta blev arkitekten \u00f6verhopad med rutinarbete, inklusive mycket kopiering och redigering, gjorde m\u00e5nga misstag, beh\u00f6vde alltid dubbelkolla, \u00e5ter skicka, och det var n\u00e4ra kaos. <\/p>\n

      I det h\u00e4r fallet fungerade denna metod, metoden f\u00f6r arbete med MS Word-dokument, med stor anstr\u00e4ngning och skapade problem.<\/p><\/blockquote>\n

      <\/p>\n

      Git, Markdown<\/h3>\n

      \nK\u00e4nde jag mig tvungen att utforska problemet som beskrevs i exemplet ovan.
      \nJag s\u00e5g att det blir allt mer popul\u00e4rt att anv\u00e4nda       Markdown<\/a><\/noindex> tillsammans med Git<\/a><\/noindex> vid skapande av dokument.<\/p>\n

      Git \u00e4r ett verktyg f\u00f6r utveckling. Men varf\u00f6r inte anv\u00e4nda det f\u00f6r dokumentationsprocessen? I det h\u00e4r fallet blir fr\u00e5gan om flervalsarbete l\u00f6st. Men f\u00f6r att fullt ut dra nytta av Git:s m\u00f6jligheter beh\u00f6ver vi ett textformat f\u00f6r dokumentet, vi m\u00e5ste hitta ett annat verktyg, inte MS Word, och f\u00f6r dessa \u00e4ndam\u00e5l passar Markdown utm\u00e4rkt. <\/p>\n

      Markdown \u00e4r ett enkelt textmarkeringsspr\u00e5k. Det \u00e4r avsett f\u00f6r att skapa vackert formaterade texter i vanliga TXT-filformat. Om vi skapar v\u00e5ra dokument i Markdown, verkar kopplingen Markdown \u2013 Git naturlig.<\/p>\n

      Och allt skulle vara bra, och p\u00e5 denna punkt skulle man kunna s\u00e4tta punkt, om det inte vore f\u00f6r v\u00e5rt andra villkor: \"vi beh\u00f6ver ett dokument i ett visst format, med attribut av f\u00f6retagets stil, skapat enligt en viss mall\" (och vi kom \u00f6verens om att det i detta fall skulle vara MS Word). Det vill s\u00e4ga, om vi har beslutat att anv\u00e4nda Markdown, s\u00e5 m\u00e5ste vi p\u00e5 n\u00e5got s\u00e4tt omvandla denna fil till .docx i \u00f6nskat format.<\/p>\n

      Det finns program f\u00f6r konvertering mellan olika format, till exempel, Pandoc<\/a><\/noindex>.
      \nDu kan konvertera en Markdown-fil till .docx-format med detta program.
      \nMen \u00e4nd\u00e5, man m\u00e5ste f\u00f6rst\u00e5 att, f\u00f6r det f\u00f6rsta, inte allt som finns i Markdown kommer att konverteras till MS Word och, f\u00f6r det andra, MS Word \u00e4r ett helt annat universum j\u00e4mf\u00f6rt med det smidiga, men \u00e4nd\u00e5 lilla, Markdown. Det finns en enorm m\u00e4ngd funktioner i Word som inte finns i n\u00e5got format av Markdown. Man kan inte bara ta och anv\u00e4nda vissa nycklar f\u00f6r Pandoc f\u00f6r att konvertera din Markdown-format till det \u00f6nskade MS Word-utseendet. S\u00e5 vanligtvis, efter konverteringen, m\u00e5ste man \"arbeta om\" den erh\u00e5llna .docx-dokumentet manuellt, vilket ocks\u00e5 kan vara tidskr\u00e4vande och leda till fel.<\/p>\n

      Om vi skulle kunna skriva ett skript som automatiskt \"slutf\u00f6rde\" det som Pandoc inte klarade skulle det vara en idealisk l\u00f6sning.<\/p>\n

      P\u00e5 grund av olikheterna i funktionaliteten mellan MS Word och Markdown i allm\u00e4nhet \u00e4r det, tror jag, om\u00f6jligt att l\u00f6sa denna uppgift, men kan detta g\u00f6ras i specifika situationer, med specifika krav? Min erfarenhet har visat att ja, det g\u00e5r, och troligtvis \u00e4r det m\u00f6jligt f\u00f6r m\u00e5nga, eller kanske till och med de flesta situationer. <\/p>\n

      L\u00f6sningen p\u00e5 ett specifikt problem<\/h3>\n

      \nS\u00e5, i mitt fall, efter att ha konverterat filen med hj\u00e4lp av Pandoc, var jag tvungen att g\u00f6ra ytterligare bearbetning av filer manuellt, n\u00e4mligen<\/p>\n