{"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\/sk\/blog\/administrirovanie\/ispolzujte-git-pri-dokumentirovanii","title":{"rendered":"Pou\u017eite GIT pri dokumentovan\u00ed","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

Niekedy nie je kritick\u00e1 len samotn\u00e1 dokument\u00e1cia, ale aj proces pr\u00e1ce na nej. Napr\u00edklad v pr\u00edpade projektov sa ve\u013ek\u00e1 \u010das\u0165 pr\u00e1ce sp\u00e1ja pr\u00e1ve s pr\u00edpravou dokument\u00e1cie, a nespr\u00e1vny proces m\u00f4\u017ee vies\u0165 k chyb\u00e1m a dokonca k strate inform\u00e1ci\u00ed, \u010do znamen\u00e1 aj stratu \u010dasu a zisku. Ale aj ke\u010f t\u00e1to t\u00e9ma nie je centr\u00e1lnou s\u00fa\u010das\u0165ou va\u0161ej pr\u00e1ce a nach\u00e1dza sa na perif\u00e9rii, spr\u00e1vny proces m\u00f4\u017ee zlep\u0161i\u0165 kvalitu dokumentu a u\u0161etri\u0165 v\u00e1m \u010das.<\/p>\n

Pr\u00edstup op\u00edsan\u00fd tu, s pr\u00edkladom konkr\u00e9tnej implement\u00e1cie<\/a><\/noindex>, m\u00e1 n\u00edzky prah vstupu. Technicky m\u00f4\u017eete u\u017e zajtra za\u010da\u0165 pracova\u0165 inak.
\n<\/a><\/noindex><\/p>\n

Stanovenie \u00falohy<\/h3>\n

\nMus\u00edte vytvori\u0165 nejak\u00fd dokument alebo sadu dokumentov. Mo\u017eno ide o projektov\u00fa dokument\u00e1ciu alebo protokolovanie va\u0161ej siete, alebo nie\u010do jednoduch\u0161ie, napr\u00edklad by ste mali pop\u00edsa\u0165 procesy vo firme alebo vo va\u0161om oddelen\u00ed. V podstate ide o ak\u00fdko\u013evek dokument alebo sadu dokumentov s textom, obr\u00e1zkami, tabu\u013ekami... Urobme \u00falohu zlo\u017eitej\u0161ou t\u00fdm, \u017ee <\/p>\n

    \n
  1. t\u00e1to pr\u00e1ca predpoklad\u00e1 spolo\u010dn\u00fa pr\u00e1cu, \u00fasilie skupiny alebo viacer\u00fdch skup\u00edn zamestnancov<\/li>\n
  2. a na konci chcete ma\u0165 dokument v konkr\u00e9tnom form\u00e1te, s atrib\u00fatmi firemn\u00e9ho \u0161t\u00fdlu, vytvoren\u00fd pod\u013ea konkr\u00e9tnej \u0161abl\u00f3ny. Pre istotu predpokladajme, \u017ee ide o MS Word (.docx)<\/li>\n<\/ol>\n

    \nPred 10 rokmi by bol pr\u00edstup jednozna\u010dn\u00fd: vytvorili by sme MS Word dokument alebo dokumenty a nejako by sme zorganizovali pr\u00e1cu na ich \u00faprav\u00e1ch. <\/p>\n

    A tento pr\u00edstup st\u00e1le plat\u00ed. Pou\u017e\u00edvaj\u00fa ho aj ve\u013ek\u00ed integr\u00e1tori pri vytv\u00e1ran\u00ed projektovej dokument\u00e1cie. Ale intuit\u00edvne je jasn\u00e9, \u017ee ak skuto\u010dne intenz\u00edvne, s mno\u017estvom \u00faprav a diskusi\u00ed, pracujete na dokumente dlh\u00fd \u010das, tento pr\u00edstup nie je ve\u013emi pohodln\u00fd.<\/p>\n

    Pr\u00edklad<\/b><\/p>\n

    T\u00fato probl\u00e9mov\u00fa situ\u00e1ciu som dos\u0165 ostro c\u00edtil, ke\u010f som pracoval v jednom ve\u013ekom integr\u00e1torovi. Proces \u00fapravy projektovej dokument\u00e1cie bol nasleduj\u00faci:<\/p>\n

      \n
    1. in\u017einier si stiahne posledn\u00fa verziu dokumentu MS Word (.docx)<\/li>\n
    2. zmen\u00ed n\u00e1zov<\/li>\n
    3. upravuje zmeny v re\u017eime sledovania<\/li>\n
    4. posiela dokument s \u00fapravami architektovi<\/li>\n
    5. takisto posiela zoznam v\u0161etk\u00fdch opr\u00e1v s koment\u00e1rmi<\/li>\n
    6. architekt analyzuje zmeny<\/li>\n
    7. ak je v\u0161etko v poriadku, skop\u00edruje tieto zmeny do s\u00faboru s poslednou verziou, zmen\u00ed verziu a nahr\u00e1 na spolo\u010dn\u00fd zdroj<\/li>\n
    8. ak s\u00fa nejak\u00e9 pripomienky, vyvol\u00e1 sa diskusia (e-mail alebo stretnutia)<\/li>\n
    9. dosiahne sa konsenzus<\/li>\n
    10. \u010falej body 3 \u2013 9<\/li>\n<\/ol>\n

      \nKe\u010f pr\u00e1ca nebola intenz\u00edvna, tak to nejak fungovalo. Ale nakoniec sa tento proces stal \u00fazkym miestom cel\u00e9ho projektu a sp\u00f4sobil probl\u00e9my. Probl\u00e9m je v tom, \u017ee sa v\u0161etko zhor\u0161uje, ke\u010f sa zmeny uskuto\u010d\u0148uj\u00fa \u010dasto a s\u00fa\u010dasne viacer\u00fdmi t\u00edmami.<\/p>\n

      Ke\u010f sme pre\u0161li do f\u00e1zy predbe\u017en\u00e9ho testovania, za\u010dali sa objavova\u0165 r\u00f4zne probl\u00e9my a hoci to boli mali\u010dkosti, bolo potrebn\u00e9 \u010dasto meni\u0165 dokument\u00e1ciu \u2014 \u0161tyri r\u00f4zne t\u00edmy, denne, takmer s\u00fa\u010dasne, s diskusiami. V\u0161etky tieto zmeny prech\u00e1dzali cez jedn\u00e9ho in\u017einiera \u2014 architekta. S\u00fabor s dizajnom projektu bol obrovsk\u00fd a n\u00e1sledne bol architekt zavalen\u00fd rutinou spojenou s ve\u013ek\u00fdm mno\u017estvom kop\u00edrovania, editovania, robil ve\u013ea ch\u00fdb, muselo sa v\u0161etko prekontrolova\u0165, preposla\u0165, a v\u00f4bec to bolo bl\u00edzko chaosu. <\/p>\n

      V tomto pr\u00edpade tento pr\u00edstup, pr\u00edstup pr\u00e1ce s dokumentom MS Word, fungoval s ve\u013ek\u00fdm n\u00e1mahou a vytv\u00e1ral probl\u00e9my.<\/p><\/blockquote>\n

      <\/p>\n

      Git, Markdown<\/h3>\n

      \nKe\u010f som sa stretol s probl\u00e9mom op\u00edsan\u00fdm v predch\u00e1dzaj\u00facom pr\u00edklade, za\u010dal som sk\u00fama\u0165 t\u00fato t\u00e9mu.
      \nZistil som, \u017ee st\u00e1le viac rastie popularita pou\u017e\u00edvania       Markdown<\/a><\/noindex> spolo\u010dne s Git<\/a><\/noindex> pri vytv\u00e1ran\u00ed dokumentov.<\/p>\n

      Git je n\u00e1stroj pre v\u00fdvoj. Ale pre\u010do ho nevyu\u017ei\u0165 aj na proces dokumentovania? V tomto pr\u00edpade je ot\u00e1zka viacn\u00e1sobn\u00e9ho pou\u017e\u00edvania vyrie\u0161en\u00e1. Aby sme v\u0161ak mohli plne vyu\u017ei\u0165 mo\u017enosti Git, potrebujeme textov\u00fd form\u00e1t dokumentu, mus\u00edme n\u00e1js\u0165 in\u00fd n\u00e1stroj, nie MS Word, a na tieto \u00fa\u010dely je Markdown skvelou vo\u013ebou. <\/p>\n

      Markdown je jednoduch\u00fd jazyk textov\u00e9ho zna\u010dkovania. Je ur\u010den\u00fd na vytv\u00e1ranie kr\u00e1sne naform\u00e1tovan\u00fdch textov v norm\u00e1lnych TXT s\u00faboroch. Ak budeme vytv\u00e1ra\u0165 na\u0161e dokumenty v Markdown, bude spojenie Markdown \u2013 Git vyzera\u0165 prirodzene.<\/p>\n

      A v\u0161etko by bolo v poriadku, a v tomto bode by sa dalo urobi\u0165 bodka, akoby nebolo n\u00e1\u0161ho druh\u00e9ho po\u017eiadavku: \u201ena v\u00fdstupe potrebujeme dokument v ur\u010ditej forme, s atrib\u00fatmi firemn\u00e9ho \u0161t\u00fdlu, vytvoren\u00fd pod\u013ea ur\u010dit\u00e9ho \u0161abl\u00f3nu\u201c (a dohodli sme sa na za\u010diatku, \u017ee pre jasnos\u0165 to bude MS Word). To znamen\u00e1, ak sme sa rozhodli pou\u017ei\u0165 Markdown, mus\u00edme nejak\u00fdm sp\u00f4sobom previes\u0165 tento s\u00fabor na .docx po\u017eadovanej podoby.<\/p>\n

      Existuj\u00fa programy na konverziu medzi r\u00f4znymi form\u00e1tmi, napr\u00edklad, Pandoc<\/a><\/noindex>.
      \nM\u00f4\u017eete previes\u0165 Markdown s\u00fabor do .docx form\u00e1tu pomocou tejto aplik\u00e1cie.
      \nAle predsa len, treba ch\u00e1pa\u0165, \u017ee po prv\u00e9, nie v\u0161etko, \u010do existuje v Markdown bude preveden\u00e9 do MS Word a po druh\u00e9, MS Word je cel\u00e1 krajina v porovnan\u00ed so \u0161t\u00edhlym, ale predsa len meste\u010dkom, Markdown. Existuje obrovsk\u00e9 mno\u017estvo nie\u010doho, \u010do je v Word a v \u017eiadnej podobe nie je v Markdown. Nem\u00f4\u017eete len tak vzia\u0165 a s ur\u010dit\u00fdmi k\u013e\u00fa\u010dmi Pandoc previes\u0165 v\u00e1\u0161 Markdown form\u00e1t do \u017eelanej podoby MS Word. Tak\u017ee zvy\u010dajne, po konverzii, je potrebn\u00e9 \u201edopracova\u0165\u201c z\u00edskan\u00fd .docx dokument ru\u010dne, \u010do op\u00e4\u0165 m\u00f4\u017ee by\u0165 n\u00e1kladn\u00e9 z poh\u013eadu \u010dasu a m\u00f4\u017ee vies\u0165 k chyb\u00e1m.<\/p>\n

      Keby sme mohli nap\u00edsa\u0165 skript, ktor\u00fd automaticky \u201edopracoval\u201c to, s \u010d\u00edm si neporadil Pandoc \u2013 to by bolo ide\u00e1lne rie\u0161enie.<\/p>\n

      Vzh\u013eadom na to, \u017ee funk\u010dnos\u0165 MS Word a Markdown nie je v celku identick\u00e1, mysl\u00edm, \u017ee vyrie\u0161i\u0165 t\u00fato \u00falohu je nemo\u017en\u00e9, ale je mo\u017en\u00e9 to dosiahnu\u0165 v s\u00favislosti s konkr\u00e9tnymi situ\u00e1ciami, konkr\u00e9tnymi po\u017eiadavkami? Moje sk\u00fasenosti uk\u00e1zali, \u017ee \u00e1no, d\u00e1 sa to a pravdepodobne je to mo\u017en\u00e9 pre mnoh\u00e9, alebo mo\u017eno aj v\u00e4\u010d\u0161inu situ\u00e1ci\u00ed. <\/p>\n

      Rie\u0161enie \u0161pecifickej \u00falohy<\/h3>\n

      \nTak\u017ee, v mojom pr\u00edpade, po konverzii s\u00faboru pomocou Pandoc, som musel ru\u010dne robi\u0165 dodato\u010dn\u00fa \u00fapravu s\u00faborov, a to konkr\u00e9tne<\/p>\n