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

Ponekad ne samo sama dokumentacija, nego i proces rada na njoj mo\u017ee biti kriti\u010dan. Na primjer, u slu\u010daju projekata, veliki dio posla povezan je upravo s pripremom dokumentacije, a pogre\u0161an proces mo\u017ee dovesti do gre\u0161aka i \u010dak gubitka informacija, a samim tim i do gubitka vremena i koristi. No, \u010dak i ako ova tema nije sredi\u0161nja u va\u0161em radu i nalazi se na periferiji, ispravan proces mo\u017ee ipak pobolj\u0161ati kvalitetu dokumenta i u\u0161tedjeti vam vrijeme.<\/p>\n

Pristup opisan ovdje, s primjerom konkretne implementacije<\/a><\/noindex>, ima nizak prag ulaska. Tehni\u010dki, ve\u0107 sutra mo\u017eete po\u010deti raditi na nov na\u010din.
\n<\/a><\/noindex><\/p>\n

Postavljanje zadatka<\/h3>\n

\nTrebate stvoriti neki dokument ili skup dokumenata. Mo\u017eda je to projektna dokumentacija ili evidencija va\u0161e mre\u017ee, ili ne\u0161to jednostavnije, poput opisa procesa u tvrtki ili va\u0161em odjelu. U osnovi, radi se o bilo kojem dokumentu ili skupu dokumenata s tekstom, slikama, tablicama\u2026 Dodatno \u0107emo zakomplicirati zadatak time \u0161to <\/p>\n

    \n
  1. ova radnja podrazumijeva zajedni\u010dki rad, trud grupe ili nekoliko grupa zaposlenika<\/li>\n
  2. na izlazu \u017eelite imati dokument u odre\u0111enom formatu, s elementima korporativnog stila, izra\u0111en prema odre\u0111enom predlo\u0161ku. Za to\u010dnost \u0107emo uzeti da je to MS Word (.docx)<\/li>\n<\/ol>\n

    \nPrije 10 godina pristup bi bio nedvosmislen: stvorili bismo MS Word dokument ili dokumente i na neki na\u010din organizirali rad na izmjenama. <\/p>\n

    I takav pristup i dalje je na snazi. Koriste ga i veliki integratori prilikom izrade projektne dokumentacije. No, intuicija govori da, ako stvarno intenzivno radite s brojnim izmjenama i raspravama tijekom du\u017eeg razdoblja, taj pristup nije ba\u0161 prakti\u010dan.<\/p>\n

    Primjer<\/b><\/p>\n

    Ovu sam problematiku osjetio vrlo sna\u017eno rade\u0107i u jednom velikom integratoru. Proces izmjene projektne dokumentacije bio je sljede\u0107i:<\/p>\n

      \n
    1. in\u017eenjer preuzima posljednju verziju MS Word (.docx) dokumenta<\/li>\n
    2. mijenja naziv<\/li>\n
    3. unosi izmjene u track modu<\/li>\n
    4. \u0161alje dokument s izmjenama arhitektu<\/li>\n
    5. tako\u0111er \u0161alje popis svih izmjena s komentarima<\/li>\n
    6. arhitekt analizira promjene<\/li>\n
    7. ako je sve u redu, kopira izmjene u datoteku s posljednjom verzijom, mijenja verziju, objavljuje na zajedni\u010dkom resursu<\/li>\n
    8. ako postoje primjedbe, pokre\u0107e se rasprava (email ili sastanci)<\/li>\n
    9. postigne se konsenzus<\/li>\n
    10. dalje stavke 3 \u2014 9<\/li>\n<\/ol>\n

      \nDok rad nije bio intenzivan, sve je nekako funkcioniralo. No u jednom trenutku ovaj proces je postao usko grlo cijelog projekta i doveo je do problema. Naime, sve postaje lo\u0161e kada se promjene \u010desto i istovremeno provode od strane nekoliko timova.<\/p>\n

      Kada smo pre\u0161li na fazu preliminarnog testiranja, po\u010deli su se javljati razli\u010diti problemi i, iako su bili sitni, dokumentaciju je trebalo \u010desto mijenjati \u2014 \u010detiri razli\u010dita tima, svakodnevno, gotovo istovremeno, s raspravama. Sve te promjene prolazile su kroz jednog in\u017eenjera \u2014 arhitekta. Datoteka sa dizajnom projekta bila je ogromna, i kao posljedica toga, arhitekt je bio zatrpan rutinom koja je uklju\u010divala mnogo kopiranja, ure\u0111ivanja, pravio je brojne gre\u0161ke, a sve je trebalo ponovo provjeravati, ponovno slati, i op\u0107enito, to je bilo blizu kaosu. <\/p>\n

      U ovom slu\u010daju, ovaj pristup, pristup radu s dokumentom MS Word, radio je s velikim naporom i stvarao probleme.<\/p><\/blockquote>\n

      <\/p>\n

      Git, Markdown<\/h3>\n

      \nSuo\u010den s problemom opisanim u gornjem primjeru, po\u010deo sam istra\u017eivati to pitanje.
      \nPrimijetio sam da postaje sve popularnije kori\u0161tenje       Markdown<\/a><\/noindex> u suradnji s Git<\/a><\/noindex> prilikom izrade dokumenata.<\/p>\n

      Git je alat za razvoj. No, za\u0161to ga ne koristiti za proces dokumentiranja? U tom slu\u010daju, pitanje vi\u0161ekorisni\u010dkog rada postaje rije\u0161eno. No kako bismo u potpunosti iskoristili mogu\u0107nosti Gita, potreban nam je tekstualni format dokumenta, trebamo prona\u0107i drugi alat, osim MS Word-a, a za te svrhe Markdown se odli\u010dno uklapa. <\/p>\n

      Markdown je jednostavan jezik za markup teksta. Namijenjen je za izradu lijepo oblikovanih tekstova u obi\u010dnim TXT datotekama. Ako budemo kreirali na\u0161e dokumente u Markdown-u, veza izme\u0111u Markdown-a i Gita izgleda prirodno.<\/p>\n

      Sve bi bilo dobro i ovdje bismo mogli staviti to\u010dku, da nije na\u0161e drugog uvjeta: \u201ena izlazu nam treba dokument u odre\u0111enom formatu, s atributima korporativnog stila, izra\u0111en po odre\u0111enom predlo\u0161ku\u201c (i dogovorili smo se na po\u010detku da \u0107e to biti MS Word). To jest, ako smo odlu\u010dili koristiti Markdown, moramo nekako pretvoriti ovu datoteku u .docx tra\u017eenog izgleda.<\/p>\n

      Postoje programi za konverziju izme\u0111u razli\u010ditih formata, na primjer, Pandoc<\/a><\/noindex>.
      \nMo\u017eete pretvoriti Markdown datoteku u .docx format s ovim programom.
      \nNo, treba razumjeti da, prvo, ne\u0107e sve \u0161to postoji u Markdowu biti pretvoreno u MS Word i, drugo, MS Word je cijela zemlja u usporedbi s jednostavnim, ali ipak malim gradom, Markdown. Postoji ogromna koli\u010dina sadr\u017eaja koji postoji u Wordu, a nijedan oblik u Markdownu. Ne mo\u017eete jednostavno tako uzeti i s odre\u0111enim klju\u010devima Pandoc konvertirati va\u0161 Markdown format u \u017eeljeni izgled MS Worda. Dakle, obi\u010dno, nakon konverzije, treba 'dora\u0111ivati' dobiveni .docx dokument ru\u010dno, \u0161to opet mo\u017ee biti vremenski zahtjevno i dovesti do pogre\u0161aka.<\/p>\n

      Kad bismo mogli napisati skript koji bi automatski 'dovr\u0161avao' ono s \u010dime se Pandoc nije mogao nositi \u2014 to bi bilo idealno rje\u0161enje.<\/p>\n

      Zbog nepodudarnosti funkcionalnosti MS Worda i Markdowda u op\u0107em smislu, mislim da je rje\u0161avanje ovog zadatka nemogu\u0107e, ali mo\u017ee li se to u\u010diniti primjenjivo na konkretne situacije, konkretne zahtjeve? Moje iskustvo je pokazalo da, da, to je mogu\u0107e i vjerojatno je to mogu\u0107e za mnoge, ili mo\u017eda \u010dak ve\u0107inu situacija. <\/p>\n

      Rje\u0161enje posebnog zadatka<\/h3>\n

      \nDakle, u mom slu\u010daju, nakon konverzije datoteke pomo\u0107u Pandoca, morao sam ru\u010dno napraviti dodatnu obradu datoteka, naime,<\/p>\n