{"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 t\u00f6\u00f6protsess selle kallal olla kriitiline. N\u00e4iteks projektide puhul on suur osa t\u00f6\u00f6st seotud just dokumentatsiooni ettevalmistamisega ning vale protsess v\u00f5ib viia vigadeni ja isegi teabe kaotamiseni, seega ka aja ja kasumi kaotamiseni. Kuid isegi kui see teema ei ole teie t\u00f6\u00f6s keskne ja asub perifeerias, v\u00f5ib \u00f5ige protsess siiski parandada dokumendi kvaliteeti ja s\u00e4\u00e4sta teie aega.<\/p>\n

Siin esitatud l\u00e4henemine, koos konkreetse rakenduse n\u00e4itega,<\/a><\/noindex>on madala sisenemise t\u00f5kete tasemega. Tehniliselt v\u00f5ite juba homme alustada uue l\u00e4henemise rakendamist.
\n<\/a><\/noindex><\/p>\n

\u00dclesande seadmine<\/h3>\n

\nVajate mingisuguse dokumendi v\u00f5i dokumentide kogumi loomist. See v\u00f5ib olla projektidokumendid v\u00f5i teie v\u00f5rgu protokollimine, v\u00f5i midagi lihtsamat, n\u00e4iteks peate kirjeldama protsesse oma ettev\u00f5ttes v\u00f5i osakonnas. \u00dches\u00f5naga, te r\u00e4\u00e4gite igasugustest dokumentidest v\u00f5i dokumentide kogumitest, mis sisaldavad teksti, pilte, tabeleid... Teeme \u00fclesande keerukamaks, kuna <\/p>\n

    \n
  1. see t\u00f6\u00f6 eeldab koost\u00f6\u00f6d, grupi v\u00f5i mitme grupi t\u00f6\u00f6tajate pingutust.<\/li>\n
  2. L\u00f5puks tahate, et dokument oleks teatud formaadis, koos ettev\u00f5tte stiili atribuutidega ja loodud vastavalt kindlale mallile. Oletame, et see on MS Word (.docx).<\/li>\n<\/ol>\n

    \n10 aastat tagasi oleks l\u00e4henemine olnud \u00fchem\u00f5tteline: me oleksime loonud MS Wordi dokumendi v\u00f5i dokumendid ja korraldanud t\u00f6\u00f6 muudatuste tegemiseks. <\/p>\n

    Ja see l\u00e4henemine kehtib endiselt. Seda kasutavad ka suured integreerijad projektidokumendi koostamisel. Kuid intuitiivselt on selge, et kui te t\u00f5eliselt intensiivselt t\u00f6\u00f6tate dokumendi kallal suurte muudatuste ja aruteludega pikema aja jooksul, pole see l\u00e4henemine just mugav.<\/p>\n

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

    Kogesin seda probleemi teravalt, t\u00f6\u00f6tades \u00fches suures integreerijas. Projektidokumendi muutmise protsess oli j\u00e4rgmine:<\/p>\n

      \n
    1. insener laadib alla viimase versiooni MS Word (.docx) dokumendist,<\/li>\n
    2. muudab pealkirja,<\/li>\n
    3. teeb muudatused j\u00e4lgimismoodulis,<\/li>\n
    4. saadab dokumendi muudatustega arhitektile,<\/li>\n
    5. saadab samuti nimekirja k\u00f5igist muudatustest koos kommentaaridega.<\/li>\n
    6. arhitekt anal\u00fc\u00fcsib muudatusi,<\/li>\n
    7. kui k\u00f5ik on korras, kopeerib ta muudatused viimase versiooniga, muudab versiooni ja paneb selle avalikku ressurssi.<\/li>\n
    8. Kui on m\u00e4rkusi, algatatakse arutelu (e-post v\u00f5i koosolekud)<\/li>\n
    9. Saavutatakse konsensus<\/li>\n
    10. Edasi liikuda punktide 3\u20139 juurde<\/li>\n<\/ol>\n

      \nKuna t\u00f6\u00f6 ei olnud intensiivne, t\u00f6\u00f6tas see kuidagi, kuid hoolimata sellest, et t\u00f6\u00f6 oli keerdne, muutus see siiski \u00fchel hetkel kogu projekti kitsaskohaks ja t\u00f5i kaasa probleeme. Asi on selles, et k\u00f5ik muutub halvaks, kui muudatusi tehakse tihti ja samaaegselt mitme meeskonna poolt.<\/p>\n

      Nii kui me j\u00f5udsime eeltestimise staadiumisse, hakkasid ilmuma erinevad probleemid ja kuigi need olid v\u00e4ikesed, tuli dokumentatsiooni pidevalt muuta \u2014 neli erinevat meeskonda, igap\u00e4evaselt, praktiliselt samaaegselt, koos aruteludega. K\u00f5ik need muudatused l\u00e4bisid \u00fche inseneri \u2014 arhitekti. Projekti disainifail oli tohutu ja seet\u00f5ttu oli arhitekt koormatud rutiinse t\u00f6\u00f6ga, mis oli seotud suure hulga kopeerimise ja redigeerimisega, tegi palju vigu, pidin k\u00f5ik \u00fcle kontrollima, uuesti saatma ja see oli \u00fcldiselt peaaegu kaos. <\/p>\n

      Antud juhul toimis see l\u00e4henemisviis, MS Word dokumendi t\u00f6\u00f6tamise l\u00e4henemine, suure vaevaga ja p\u00f5hjustas probleeme.<\/p><\/blockquote>\n

      <\/p>\n

      Git, Markdown<\/h3>\n

      \nSeistes silmitsi eespool toodud n\u00e4ites kirjeldatud probleemiga, hakkasin seda k\u00fcsimust uurima.
      \nN\u00e4gin, et j\u00e4rjest populaarsemaks muutub       Markdown<\/a><\/noindex> koos Git<\/a><\/noindex> dokumentide loomisel.<\/p>\n

      Git on arendust\u00f6\u00f6riist. Aga miks mitte kasutada seda dokumenteerimise protsessis? Sel juhul kaob mitme kasutaja t\u00f6\u00f6 k\u00fcsimus. Kuid Git'i t\u00e4ielike v\u00f5imete kasutamiseks vajame dokumendi tekstiformaati, peame leidma teise t\u00f6\u00f6riista, mitte MS Word'i ja nende eesm\u00e4rkide jaoks sobib suurep\u00e4raselt Markdown. <\/p>\n

      Markdown on lihtne tekstiformaatimise keel. See on ette n\u00e4htud kaunite tekstide loomiseks tavalistes TXT-vormingus failides. Kui me loome oma dokumendid Markdown'is, siis n\u00e4eb Markdown - Git \u00fchendus loomulik v\u00e4lja.<\/p>\n

      K\u00f5ik oleks h\u00e4sti, ja sel kohal v\u00f5iks punkti panna, kui mitte meie teine tingimus: \u201eme vajame v\u00e4ljundina dokumenti kindlas formaadis, ettev\u00f5tte br\u00e4ndinguga, loodud kindla malliga\u201c (ja me leppisime alguses kokku, et selleks on MS Word). See t\u00e4hendab, et kui me otsustame kasutada Markdown'i, siis peame kuidagi selle faili vajalikku .docx formaati \u00fcmber t\u00f6\u00f6tlema.<\/p>\n

      On olemas erinevate formaatide konversiooniprogrammid, n\u00e4iteks, Pandoc<\/a><\/noindex>.
      \nSa saad konverteerida Markdown faili .docx formaati selle programmi abil.
      \nKuid ikkagi tuleb aru saada, et esiteks ei konverteerita k\u00f5ike, mis Markdown'is on, MS Wordi ning teiseks on MS Word hoopis laiem maailm v\u00f5rreldes kompaktse, kuid siiski v\u00e4ikese Markdowniga. Wordis on \u00fcksikkuid funktsioone, mida ei ole Markdownis. Sa ei saa lihtsalt v\u00f5tta ja teatud v\u00f5tmete abil Pandoc'iga konverteerida oma Markdown formaati soovitud MS Wordi vormingusse. Seega tuleb tavaliselt p\u00e4rast konversiooni saadud .docx dokumenti k\u00e4sitsi \u201et\u00e4iendama\u201c, mis j\u00e4lle v\u00f5ib olla ajakulukas ja viia vigadeni.<\/p>\n

      Kui me suudaksime kirjutada skripti, mis automaatselt \u201et\u00e4iendaks\u201c seda, millega Pandoc ei suutnud hakkama saada \u2013 see oleks ideaalne lahendus.<\/p>\n

      Kuna MS Wordi ja Markdowni funktsionaalsus ei ole \u00fcldiselt identne, arvan, et selle \u00fclesande lahendamine on v\u00f5imatu, kuid kas on v\u00f5imalik seda teha antud spetsiifiliste olukordade ja n\u00f5udmiste kohaselt? Minu kogemus on n\u00e4idanud, et jah, see on v\u00f5imalik ja t\u00f5en\u00e4oliselt toimub see paljude, v\u00f5i isegi enamikus olukordades. <\/p>\n

      Kohaliku \u00fclesande lahendus<\/h3>\n

      \nNii et minu puhul pidin p\u00e4rast faili konverteerimist Pandoc'iga k\u00e4esolevat faili k\u00e4sitsi edasi t\u00f6\u00f6tlema, nimelt<\/p>\n