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

M\u00f5nikord v\u00f5ib mitte ainult dokumentatsioon ise, vaid ka selle koostamise protsess olla kriitilise t\u00e4htsusega. N\u00e4iteks projektide puhul on suur osa t\u00f6\u00f6st seotud dokumentatsiooni ettevalmistamisega ning vale protsess v\u00f5ib viia vigadeni ja isegi teabe kaotamiseni, mis omakorda p\u00f5hjustab ajakulu ja kahjumit. Kuid isegi kui see teema ei ole teie t\u00f6\u00f6s keskne ja j\u00e4\u00e4b perifeeriasse, v\u00f5ib \u00f5ige protsess siiski parandada dokumendi kvaliteeti ja s\u00e4\u00e4sta aega.<\/p>\n

Toodud l\u00e4henemine, konkreetse rakenduse n\u00e4itega<\/a><\/noindex>, on madala sisenemisbarj\u00e4\u00e4riga. Tehniliselt v\u00f5ite juba homme alustada uut l\u00e4henemist.
\n<\/a><\/noindex><\/p>\n

\u00dclesande seadmine<\/h3>\n

\nTeil on vaja luua mingi dokument v\u00f5i dokumentide kogum. Olgu see projektidokumentatsioon v\u00f5i teie v\u00f5rgu protokollimine, v\u00f5i midagi lihtsamat, n\u00e4iteks peate kirjeldama ettev\u00f5tte v\u00f5i teie osakonna protsesse. Kokkuv\u00f5ttes r\u00e4\u00e4gime igasugustest dokumentidest v\u00f5i dokumentide kogumist, kus on tekst, pildid, tabelid... Teeme \u00fclesande keerulisemaks, et <\/p>\n

    \n
  1. see t\u00f6\u00f6 eeldab koost\u00f6\u00f6d, grupi v\u00f5i mitme t\u00f6\u00f6tajate r\u00fchma pingutusi.<\/li>\n
  2. v\u00e4ljatulev dokument peab olema teatud vormingus, ettev\u00f5tte stiili atribuudi siin, loodud teatud \u0161ablooni j\u00e4rgi. T\u00e4psuse huvides oletame, et see on MS Word (.docx)<\/li>\n<\/ol>\n

    \n10 aastat tagasi oleks l\u00e4henemine olnud \u00fcheselt m\u00f5istetav: oleksime loonud MS Wordi dokumendi v\u00f5i dokumendid ja korraldanud muudatuset\u00f6\u00f6d mingil viisil. <\/p>\n

    Ja see l\u00e4henemine kehtib endiselt. Seda kasutavad ka suured integratsiooniettev\u00f5tted projektidokumendi loomisel. Kuid intuitiivselt on selge, et kui t\u00f6\u00f6tab t\u00f5eliselt intensiivselt, paljude muudatuste ja aruteludega, pika aja jooksul dokumendi kallal, ei ole see l\u00e4henemine v\u00e4ga mugav.<\/p>\n

    N\u00e4ide<\/b><\/p>\n

    Otsisin seda probleemi teravalt, t\u00f6\u00f6tades \u00fche suure integratoriga. Projektidokumentide muutmise protsess oli j\u00e4rgmine:<\/p>\n

      \n
    1. insener allalaadib viimase versiooni MS Word (.docx) dokumendist<\/li>\n
    2. muudab pealkirja<\/li>\n
    3. teeb muudatused track-re\u017eiimis<\/li>\n
    4. saadab redigeeritud dokumendi arhitektile<\/li>\n
    5. saadab ka k\u00f5igi muudatuste loetelu kommentaaridega<\/li>\n
    6. arhitekt anal\u00fc\u00fcsib muudatusi<\/li>\n
    7. kui k\u00f5ik on korras, siis kopeerib see andmete muutused viimase versiooniga faili, muudab versiooni ja avaldab selle \u00fchisesse ressurssi<\/li>\n
    8. kui on m\u00e4rkusi, algatatakse arutelu (e-kiri v\u00f5i kohtumised)<\/li>\n
    9. saavutatakse konsensus<\/li>\n
    10. j\u00e4rgmiseks punktid 3\u20139<\/li>\n<\/ol>\n

      \nKuigi t\u00f6\u00f6 ei olnud intensiivne, toimis see kuidagi, aga ikkagi t\u00f6\u00f6tas. Kuid teatud hetkel sai see protsess kogu projekti kitsaskohaks ja p\u00f5hjustas probleeme. Asi on selles, et k\u00f5ik l\u00e4heb kehvasti, kui muudatusi tehakse tihti ja samal ajal mitme meeskonna poolt.<\/p>\n

      Nii, kui me l\u00e4ksime ettevalmistustestimise faasi, hakkasid ilmuma erinevad probleemid ja kuigi need olid v\u00e4ikesed, tuli dokumentatsiooni sageli muuta - neli erinevat meeskonda, iga p\u00e4ev, praktiliselt samal ajal, aruteludega. K\u00f5ik need muudatused l\u00e4bisid \u00fche inseneri - arhitekti. Projekti disainifail oli tohutu ja seega oli arhitekt koormatud rutiinse t\u00f6\u00f6ga, mis oli seotud suure hulga kopeerimise ja redigeerimisega, tegi palju vigu, tuli k\u00f5ik uuesti kontrollida, \u00fcmber saata, ja \u00fcldiselt oli see l\u00e4hedal kaoseni. <\/p>\n

      Selles olukorras t\u00f6\u00f6tas MS Wordi dokumentide t\u00f6\u00f6tlemise l\u00e4henemine suure skripti ja probleemide loomisega.<\/p><\/blockquote>\n

      <\/p>\n

      Git, Markdown<\/h3>\n

      \nSilmunes eespool kirjeldatud probleemiga, hakkasin seda teemat uurima.
      \nOlen m\u00e4rganud, et \u00fcha populaarsemaks on muutumas       Markdown<\/a><\/noindex> koos Git<\/a><\/noindex> dokumentide loomisel.<\/p>\n

      Git on arendusvahend. Kuid miks mitte kasutada seda dokumentide koostamise protsessis? Sellisel juhul on mitme kasutaja t\u00f6\u00f6 k\u00fcsimus lahendatud. Kuid et Git'i v\u00f5imalusi t\u00e4ielikult \u00e4ra kasutada, vajame dokumendi tekstivormingut ning peame leidma teise t\u00f6\u00f6riista, mitte MS Wordi, ja selleks sobib suurep\u00e4raselt Markdown. <\/p>\n

      Markdown on lihtne tekstiformaadimise keel. See on m\u00f5eldud kaunis vormindatud tekstide loomiseks tavap\u00e4rastes TXT-formaadiga failides. Kui loome meie dokumendid Markdownis, siis tundub Markdown \u2014 Git \u00fchendus loomulik.<\/p>\n

      Ja k\u00f5ik oleks h\u00e4sti, ja just siin v\u00f5iks punkti panna, kui mitte meie teine tingimus: \u201eme vajame v\u00e4ljundina dokumenti kindlas formaadis, ettev\u00f5tte stiili atribuutidega, mis on loodud kindla malliga\u201c (ning me leppisime alguses kokku, et selleks on MS Word). Seega, kui oleme otsustanud kasutada Markdown'i, peame oma faili kuidagi teisendama soovitud .docx formaati.<\/p>\n

      On olemas konversiooniprogramme erinevate formaatide vahel, n\u00e4iteks, Pandoc<\/a><\/noindex>.
      \nSaate konverteerida Markdown faili .docx formaati selle programmiga.
      \nKuid siiski, tuleb m\u00f5ista, et, esiteks, mitte k\u00f5ik, mis on Markdown'is, ei konverteeru MS Wordi ning, teiseks, MS Word on terviklik riik v\u00f5rreldes kompaktse, kuid siiski v\u00e4ikese linnaga, Markdown. Wordis on tohutult palju funktsioone, mida Markdown'is ei ole. Ei saa lihtsalt v\u00f5tta ja teatud Pandoc'i v\u00f5tit kasutades konverteerida oma Markdown formaati soovitud MS Word'i kuvandisse. Seet\u00f5ttu tuleb tavaliselt p\u00e4rast konversiooni saadud .docx dokumenti k\u00e4sitsi \"t\u00e4iendama\", mis omakorda v\u00f5ib olla ajakulukas ja viia vigadeni.<\/p>\n

      Kui me suudaksime kirjutada skripti, mis automaatselt \u00abt\u00e4iendaks\u00bb seda, millega Pandoc hakkama ei saa \u2014 see oleks ideaalne lahendus.<\/p>\n

      T\u00e4nu MS Wordi ja Markdowni funktsioonide erinevustele \u00fcldiselt on selle probleemi lahendamine minu arvates v\u00f5imatu, kuid kas on v\u00f5imalik seda konkreetsete olukordade, spetsiifiliste n\u00f5udmiste alusel teha? Minu kogemus on n\u00e4idanud, et jah, see on v\u00f5imalik ja t\u00f5en\u00e4oliselt sobib see paljudele, v\u00f5ib-olla isegi enamikule olukordadele. <\/p>\n

      Spetsiifilise \u00fclesande lahendus<\/h3>\n

      \nNii et minu puhul, p\u00e4rast faili konversiooni Pandoci abil, pidin ma k\u00e4sitsi tegema t\u00e4iendavat t\u00f6\u00f6tlemist, nimelt<\/p>\n