{"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\/sl\/blog\/administrirovanie\/ispolzujte-git-pri-dokumentirovanii","title":{"rendered":"Koristite GIT prilikom dokumentovanja","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

V\u010dasih ni kriti\u010dna le sama dokumentacija, temve\u010d tudi proces dela z njo. Na primer, v primeru projektov je velika ve\u010dina dela povezana prav s pripravami dokumentacije, nepravilni proces pa lahko privede do napak in celo izgube informacij, kar posledi\u010dno pomeni izgubo \u010dasa in koristi. Vendar pa tudi \u010de ta tema ni osrednja v va\u0161em delu in je na obrobju, pravi proces vseeno lahko izbolj\u0161a kakovost dokumenta in vam prihrani \u010das.<\/p>\n

Predlagan pristop, s primerom konkretne izvedbe<\/a><\/noindex>, ima nizek prag vstopa. Tehni\u010dno lahko \u017ee jutri za\u010dnete delati na nov na\u010din.
\n<\/a><\/noindex><\/p>\n

Definisanje zadatka<\/h3>\n

\nPotrebno je pripraviti nek dokument ali niz dokumentov. Morda gre za projektno dokumentacijo ali protokoliranje va\u0161e mre\u017ee, ali kaj bolj preprostega, na primer opisati procese v podjetju ali va\u0161i ekipi. Na splo\u0161no gre za kateri koli dokument ali niz dokumentov s tekstom, slikami, tabelami\u2026 Zadevo nekoliko zapleteno, saj <\/p>\n

    \n
  1. ta delo predpostavlja skupinsko delo, prizadevanja skupine ali ve\u010d skupin zaposlenih<\/li>\n
  2. na izhodu \u017eelite imeti dokument v dolo\u010denem formatu, z atributi korporativne identitete, ustvarjen po dolo\u010denem predlogi. Za ve\u010djo jasnost bomo predpostavljali, da gre za MS Word (.docx)<\/li>\n<\/ol>\n

    \nPred 10 leti bi bil pristop enostavno dolo\u010den: ustvarili bi MS Word dokumente ali dokument in na nek na\u010din organizirali delo pri spremembah. <\/p>\n

    In tak pristop \u0161e vedno velja. Uporabljajo ga tudi veliki integratorji pri izdelavi projektne dokumentacije. Vendar je intuitivno jasno, da, \u010de res intenzivno delate z mnogimi spremembami in razpravami dolgotrajno na dokumentu, ta pristop ni ravno priro\u010den.<\/p>\n

    Primer<\/b><\/p>\n

    To te\u017eavo sem mo\u010dno ob\u010dutil, ko sem delal pri enem od velikih integratorjev. Proces spreminjanja projektne dokumentacije je bil naslednji:<\/p>\n

      \n
    1. in\u017eenir prenese zadnjo razli\u010dico MS Word (.docx) dokumenta<\/li>\n
    2. spremeni naslov<\/li>\n
    3. vna\u0161a popravke v na\u010dinu sledenja<\/li>\n
    4. po\u0161lje dokument s popravki arhitektu<\/li>\n
    5. prav tako po\u0161lje seznam vseh popravkov s komentarji<\/li>\n
    6. arhitekt analizira spremembe<\/li>\n
    7. \u010de je vse v redu, kopira te spremembe v datoteko z zadnjo razli\u010dico, spremeni razli\u010dico in objavi na skupnem viru.<\/li>\n
    8. \u010de so pripombe, se spro\u017ei razprava (elektronska po\u0161ta ali sestanki)<\/li>\n
    9. dose\u017eemo konsenzus<\/li>\n
    10. nato to\u010dke 3 \u2014 9<\/li>\n<\/ol>\n

      \nDokler delo ni bilo intenzivno, je to nekako delovalo. Vendar je v dolo\u010denem trenutku ta proces postal \u0161ibka to\u010dka celotnega projekta in povzro\u010dil te\u017eave. Gre za to, da se stvari poslab\u0161ajo, takoj ko se spremembe izvajajo pogosto in hkrati z ve\u010d ekipami.<\/p>\n

      Tako, ko smo pre\u0161li na fazo predtestiranja, so se za\u010dele pojavljati razli\u010dne te\u017eave in, \u010deprav so bile majhne, je bilo treba pogosto spreminjati dokumentacijo \u2014 \u0161tiri razli\u010dne ekipe, dnevno, prakti\u010dno hkrati, z razpravami. Vse te spremembe so potekale preko enega in\u017eenirja \u2014 arhitekta. Datoteka s projektom je bila ogromna in kot posledica je bil arhitekt obremenjen z rutinskim delom, ki je zahtevalo veliko kopiranja in urejanja, delal je veliko napak, vse je bilo treba ponovno preverjati, ponovno po\u0161iljati in na splo\u0161no je bilo to blizu kaosa. <\/p>\n

      V tem primeru je ta pristop, pristop dela z dokumentom MS Word, deloval z obse\u017enim trudom in ustvarjal te\u017eave.<\/p><\/blockquote>\n

      <\/p>\n

      Git, Markdown<\/h3>\n

      \nKo sem se sre\u010dal s te\u017eavo, opisano v zgornjem primeru, sem za\u010del raziskovati to vpra\u0161anje.
      \nOpazil sem, da postaja vse bolj priljubljena uporaba       Markdown<\/a><\/noindex> skupaj z Git<\/a><\/noindex> pri ustvarjanju dokumentov.<\/p>\n

      Git je orodje za razvoj. Ampak zakaj ga ne bi uporabili za proces dokumentiranja? V tem primeru postane vpra\u0161anje ve\u010duporabni\u0161kega dela re\u0161eno. Vendar pa, da bi v polni meri izkoristili zmogljivosti Gita, potrebujemo besedilni format dokumenta, morali bi najti drugo orodje, ne MS Word, in za te namene je Markdown odli\u010dna izbira. <\/p>\n

      Markdown je preprost jezik za oblikovanje besedila. Namenjen je ustvarjanju lepo oblikovanih besedil v obi\u010dajnih TXT datotekah. \u010ce bomo na\u0161e dokumente ustvarjali v Markdownu, se povezava Markdown \u2014 Git zdi naravna.<\/p>\n

      Vse bi bilo dobro, in na tem mestu bi lahko postavili piko, \u010de ne bi bilo na\u0161ega drugega pogoja: \u201ena izhodu potrebujemo dokument v dolo\u010denem formatu, z atributi korporativne podobe, ustvarjen po dolo\u010denem predlo\u0161ku\u201c (in dogovorili smo se na za\u010detku, da bo to za natan\u010dnost MS Word). To pomeni, da \u010de smo se odlo\u010dili uporabiti Markdown, moramo nekako pretvoriti to datoteko v .docx zahtevane oblike.<\/p>\n

      Obstajajo programa za pretvorbo med razli\u010dnimi formati, na primer, Pandoc<\/a><\/noindex>.
      \nMarkdown datoteko lahko pretvorite v .docx format s tem programom.
      \nVendar pa je treba razumeti, da, prvi\u010d, ne vse, kar je v Markdownu, bo pretvorjeno v MS Word, in, drugi\u010d, MS Word je cela dr\u017eava v primerjavi z urejenim, a \u0161e vedno majhnim mestom, Markdownom. Obstaja ogromno vsega, kar je v Wordu in ni v nobeni obliki v Markdownu. Ni mogo\u010de kar tako vzeti in s specifi\u010dnimi klju\u010di Pandoc pretvoriti va\u0161ega Markdown formata v \u017eeleno obliko MS Word. Tako, da obi\u010dajno, po pretvorbi, morate \u201edodelati\u201c pridobljen .docx dokument ro\u010dno, kar spet lahko pomeni stro\u0161ke glede \u010dasa in privede do napak.<\/p>\n

      \u010ce bi lahko napisali skript, ki bi samodejno \"dodelal\" tisto, s \u010dimer se Pandoc ni spopadel \u2014 bi to bilo idealno re\u0161itev.<\/p>\n

      Glede na nekonkretizirano funkcionalnost MS Word in Markdown v splo\u0161nem vidim, da je ni mogo\u010de re\u0161iti, vendar ali je to mogo\u010de storiti v povezavi s specifi\u010dnimi situacijami, specifi\u010dnimi zahtevami? Moje izku\u0161nje so pokazale, da, da, in verjetno je to mogo\u010de za mnoga, ali morda celo ve\u010dino situacij. <\/p>\n

      Re\u0161itev specifi\u010dne naloge<\/h3>\n

      \nTako sem v mojem primeru po pretvorbi datoteke s pomo\u010djo Pandoc moral ro\u010dno opraviti dodatno obdelavo datotek, natan\u010dneje<\/p>\n