{"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\/hu\/blog\/administrirovanie\/ispolzujte-git-pri-dokumentirovanii","title":{"rendered":"Haszn\u00e1ljon GIT-et a dokument\u00e1ci\u00f3 k\u00e9sz\u00edt\u00e9sekor","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

N\u00e9ha nemcsak a dokument\u00e1ci\u00f3 maga, hanem a k\u00e9sz\u00edt\u00e9se is kritikus lehet. P\u00e9ld\u00e1ul, bizonyos projektek eset\u00e9ben a munka jelent\u0151s r\u00e9sze a dokument\u00e1ci\u00f3 el\u0151k\u00e9sz\u00edt\u00e9s\u00e9vel kapcsolatos, \u00e9s a hib\u00e1s folyamatok hib\u00e1khoz, s\u0151t, inform\u00e1ci\u00f3veszt\u00e9shez vezethetnek, ami id\u0151- \u00e9s haszonvesztes\u00e9get is okozhat. De m\u00e9g ha ez a t\u00e9ma nem is a munka k\u00f6z\u00e9ppontj\u00e1ban \u00e1ll, a megfelel\u0151 folyamat jav\u00edthatja a dokumentum min\u0151s\u00e9g\u00e9t, \u00e9s id\u0151t takar\u00edthat meg.<\/p>\n

A bemutatott megk\u00f6zel\u00edt\u00e9s konkr\u00e9t megval\u00f3s\u00edt\u00e1s\u00e1val<\/a><\/noindex>, alacsony bel\u00e9p\u00e9si k\u00fcsz\u00f6b\u00f6t mutat. Technikai \u00e9rtelemben m\u00e1r holnap elkezdheti az \u00faj m\u00f3dszer alkalmaz\u00e1s\u00e1t.
\n<\/a><\/noindex><\/p>\n

L\u00e9pj\u00fcnk \u00e1t a kit\u0171z\u00f6tt feladatra: \u00edrjunk egy XDP mechanizmust SYN cookie-kkal.<\/h3>\n

\nSz\u00e1m\u00e1ra sz\u00fcks\u00e9ges egy dokumentum vagy dokumentumok halmaz\u00e1nak l\u00e9trehoz\u00e1sa. Lehet ez projekt dokument\u00e1ci\u00f3 vagy a h\u00e1l\u00f3zat\u00e1nak napl\u00f3z\u00e1sa, vagy valami egyszer\u0171bb, p\u00e9ld\u00e1ul a c\u00e9g vagy az oszt\u00e1ly folyamatait kell le\u00edrnia. R\u00f6viden, b\u00e1rmilyen dokumentumr\u00f3l vagy dokumentumhalmazr\u00f3l van sz\u00f3, amely tartalmaz sz\u00f6veget, k\u00e9peket, t\u00e1bl\u00e1zatokat... Nehez\u00edtj\u00fck a feladatot azzal, hogy <\/p>\n

    \n
  1. ez a munka k\u00f6z\u00f6s er\u0151fesz\u00edt\u00e9st ig\u00e9nyel, csoportok, vagy t\u00f6bb csoport alkalmazottainak egy\u00fcttm\u0171k\u00f6d\u00e9s\u00e9t<\/li>\n
  2. az eredm\u00e9ny\u00fcl kapott dokumentumnak egy meghat\u00e1rozott form\u00e1tumban kell lennie, a v\u00e1llalati arculati attrib\u00fatumokkal, egy meghat\u00e1rozott sablon alapj\u00e1n k\u00e9sz\u00fclve. Hat\u00e1rozotts\u00e1g kedv\u00e9\u00e9rt azt fogjuk felt\u00e9telezni, hogy ez egy MS Word (.docx) dokumentum<\/li>\n<\/ol>\n

    \n10 \u00e9ve a megk\u00f6zel\u00edt\u00e9s egy\u00e9rtelm\u0171 lenne: l\u00e9trehozunk egy vagy t\u00f6bb MS Word dokumentumot, \u00e9s valamilyen m\u00f3don szervezn\u00e9nk a m\u00f3dos\u00edt\u00e1sok folyamat\u00e1t. <\/p>\n

    Ez a megk\u00f6zel\u00edt\u00e9s tov\u00e1bbra is \u00e9rv\u00e9nyben van. A nagy integr\u00e1torok is haszn\u00e1lj\u00e1k projekt dokument\u00e1ci\u00f3 k\u00e9sz\u00edt\u00e9sekor. De intuit\u00edv m\u00f3don nyilv\u00e1nval\u00f3, hogy ha val\u00f3ban intenz\u00edven dolgozik a dokumentumon, sok m\u00f3dos\u00edt\u00e1ssal \u00e9s megbesz\u00e9l\u00e9ssel, hossz\u00fa id\u0151n kereszt\u00fcl, ez a megk\u00f6zel\u00edt\u00e9s nem t\u00fal k\u00e9nyelmes.<\/p>\n

    t\u00e1mad\u00e1sra<\/b><\/p>\n

    \u00c9n is er\u0151teljesen tapasztaltam ezt a probl\u00e9m\u00e1t, amikor egy nagy integr\u00e1torn\u00e1l dolgoztam. A projekt dokument\u00e1ci\u00f3 m\u00f3dos\u00edt\u00e1s\u00e1nak folyamata a k\u00f6vetkez\u0151 volt:<\/p>\n

      \n
    1. a m\u00e9rn\u00f6k let\u00f6lti az utols\u00f3 verzi\u00f3j\u00fa MS Word (.docx) dokumentumot<\/li>\n
    2. megv\u00e1ltoztatja a nevet<\/li>\n
    3. v\u00e1ltoztat\u00e1sokat hajt v\u00e9gre az \u00e1ttekint\u00e9si m\u00f3dban<\/li>\n
    4. a m\u00f3dos\u00edtott dokumentumot elk\u00fcldi az \u00e9p\u00edt\u00e9sznek<\/li>\n
    5. szint\u00e9n elk\u00fcldi az \u00f6sszes m\u00f3dos\u00edt\u00e1st a megjegyz\u00e9sekkel<\/li>\n
    6. az \u00e9p\u00edt\u00e9sz elemzi a v\u00e1ltoztat\u00e1sokat<\/li>\n
    7. ha minden rendben van, \u00e1tm\u00e1solja a m\u00f3dos\u00edt\u00e1sokat az utols\u00f3 verzi\u00f3 f\u00e1jlba, megv\u00e1ltoztatja a verzi\u00f3t, \u00e9s k\u00f6zz\u00e9teszi a k\u00f6z\u00f6s er\u0151forr\u00e1son<\/li>\n
    8. Ha b\u00e1rmilyen \u00e9szrev\u00e9tel mer\u00fcl fel, akkor megbesz\u00e9l\u00e9s (email vagy tal\u00e1lkoz\u00f3k) kezdem\u00e9nyez\u0151dik.<\/li>\n
    9. Konszenzus sz\u00fcletik.<\/li>\n
    10. Ezut\u00e1n a 3-9. pontok k\u00f6vetkeznek.<\/li>\n<\/ol>\n

      \nM\u00edg a munkafolyamat nem volt intenz\u00edv, valahogy m\u0171k\u00f6d\u00f6tt. De egy id\u0151 ut\u00e1n ez a folyamat a projekt sz\u0171k keresztmetszet\u00e9v\u00e9 v\u00e1lt, ami probl\u00e9m\u00e1khoz vezetett. Az a helyzet, hogy minden rosszul megy, amint a v\u00e1ltoztat\u00e1sok gyakran \u00e9s egyszerre t\u00f6bb csapat \u00e1ltal t\u00f6rt\u00e9nnek.<\/p>\n

      Amikor \u00e1t\u00e1lltunk az el\u0151zetes tesztel\u00e9si szakaszra, k\u00fcl\u00f6nb\u00f6z\u0151 probl\u00e9m\u00e1k kezdtek megjelenni, \u00e9s b\u00e1r apr\u00f3s\u00e1gokr\u00f3l volt sz\u00f3, a dokument\u00e1ci\u00f3t gyakran kellett m\u00f3dos\u00edtani - n\u00e9gy k\u00fcl\u00f6nb\u00f6z\u0151 csapat, naponta, szinte egyszerre, megbesz\u00e9l\u00e9sekkel. Mindezek a v\u00e1ltoz\u00e1sok egy m\u00e9rn\u00f6k - \u00e9p\u00edt\u00e9sz - \u00e1ltal \u00e9rkeztek. A projekt tervf\u00e1jl \u00f3ri\u00e1si volt, \u00e9s ennek k\u00f6vetkezt\u00e9ben az \u00e9p\u00edt\u00e9sz a sok m\u00e1sol\u00e1ssal \u00e9s szerkeszt\u00e9ssel j\u00e1r\u00f3 rutinfeladatokkal volt elfoglalva, sok hib\u00e1t v\u00e9tett, mindent \u00fajra kellett ellen\u0151rizni, \u00fajrak\u00fcldeni, \u00e9s \u00f6sszess\u00e9g\u00e9ben ez k\u00f6zel \u00e1llt a k\u00e1oszhoz. <\/p>\n

      Ebben az esetben a dokumentummal val\u00f3 munka MS Word megk\u00f6zel\u00edt\u00e9se nagy neh\u00e9zs\u00e9geket okozott \u00e9s probl\u00e9m\u00e1kat teremtett.<\/p><\/blockquote>\n

      <\/p>\n

      Git, Markdown<\/h3>\n

      \nA fent eml\u00edtett probl\u00e9m\u00e1val szembes\u00fclve elkezdtem kutatni ezt a k\u00e9rd\u00e9st.
      \nL\u00e1ttam, hogy egyre n\u00e9pszer\u0171bb\u00e9 v\u00e1lik a haszn\u00e1lata       Markdown<\/a><\/noindex> egy\u00fctt Kont\u00e9neriz\u00e1l\u00e1s<\/a><\/noindex> dokumentumok l\u00e9trehoz\u00e1sakor.<\/p>\n

      A Git egy fejleszt\u0151eszk\u00f6z. De mi\u00e9rt ne haszn\u00e1lhatn\u00e1nk a dokument\u00e1l\u00e1si folyamatra is? Ebben az esetben a t\u00f6bbfelhaszn\u00e1l\u00f3s munka k\u00e9rd\u00e9se megold\u00f3dik. De ahhoz, hogy a Git \u00f6sszes lehet\u0151s\u00e9g\u00e9t teljes m\u00e9rt\u00e9kben kihaszn\u00e1lhassuk, sz\u00f6veges dokumentumform\u00e1tumra van sz\u00fcks\u00e9g\u00fcnk, \u00e9s m\u00e1s eszk\u00f6zt kell keresn\u00fcnk, amely nem MS Word, \u00e9s ezekre a c\u00e9lokra a Markdown kiv\u00e1l\u00f3an alkalmas. <\/p>\n

      A Markdown egy egyszer\u0171 sz\u00f6veges jel\u00f6l\u0151nyelv. Sz\u00e9p form\u00e1z\u00e1s\u00fa sz\u00f6vegek l\u00e9trehoz\u00e1s\u00e1ra szolg\u00e1l sima TXT f\u00e1jlokban. Ha Markdown form\u00e1tumban k\u00e9sz\u00edtj\u00fck el a dokumentumainkat, akkor a Markdown - Git \u00f6sszekapcsol\u00e1sa term\u00e9szetesnek t\u0171nik.<\/p>\n

      Mindez rendben van, \u00e9s itt ak\u00e1r meg is \u00e1llhatn\u00e1nk, ha nem lenne a m\u00e1sodik felt\u00e9tel\u00fcnk: \"a kimenetnek egy bizonyos form\u00e1tumban kell lennie, v\u00e1llalati st\u00edlusjegyekkel, egy meghat\u00e1rozott sablon alapj\u00e1n\" (el\u0151re meg\u00e1llapodtunk abban, hogy ez MS Word lesz). Teh\u00e1t, ha \u00fagy d\u00f6nt\u00f6tt\u00fcnk, hogy Markdown-t haszn\u00e1lunk, akkor valahogy \u00e1t kell alak\u00edtanunk ezt a f\u00e1jlt a k\u00edv\u00e1nt .docx form\u00e1tumba.<\/p>\n

      Vannak programok, amelyek k\u00fcl\u00f6nb\u00f6z\u0151 form\u00e1tumok k\u00f6z\u00f6tt konvert\u00e1lnak, p\u00e9ld\u00e1ul, Pandoc<\/a><\/noindex>.
      \nEzzel a programmal Markdown f\u00e1jlt konvert\u00e1lhat .docx form\u00e1tumba.
      \nDe m\u00e9gis, \u00e9rdemes meg\u00e9rteni, hogy egyr\u00e9szt nem minden, ami Markdown-ban van, lesz konvert\u00e1lva MS Word-be, m\u00e1sr\u00e9szt MS Word egy eg\u00e9sz orsz\u00e1g a viszonylag egyszer\u0171, de m\u00e9gis kisv\u00e1rosk\u00e9nt m\u0171k\u00f6d\u0151 Markdownhoz k\u00e9pest. Rengeteg olyan dolog van Word-ben, ami sehol sincs Markdown form\u00e1tumban. Nem lehet csak \u00fagy, egyes kulcsokkal Pandoc seg\u00edts\u00e9g\u00e9vel \u00e1tkonvert\u00e1lni a Markdown form\u00e1tumot a k\u00edv\u00e1nt MS Word kin\u00e9zetre. Sz\u00f3val \u00e1ltal\u00e1ban a konvert\u00e1l\u00e1s ut\u00e1n k\u00e9zzel kell \"finom\u00edtani\" a kapott .docx dokumentumot, ami megintcsak id\u0151ig\u00e9nyes lehet \u00e9s hib\u00e1khoz vezethet.<\/p>\n

      Ha tudn\u00e1nk \u00edrni egy szkriptet, ami automatikusan \"befejezn\u00e9\" azt, amivel Pandoc nem boldogult \u2014 ez lenne az ide\u00e1lis megold\u00e1s.<\/p>\n

      Tekintettel arra, hogy az MS Word \u00e9s Markdown funkci\u00f3i nem azonosak, ezt a feladatot \u00e1ltal\u00e1noss\u00e1gban v\u00e9ve lehetetlennek gondolom, de lehet-e ezt megoldani konkr\u00e9t helyzetekhez, konkr\u00e9t k\u00f6vetelm\u00e9nyekhez? Tapasztalatom alapj\u00e1n igen, lehet, \u00e9s val\u00f3sz\u00edn\u0171leg sok, vagy tal\u00e1n a legt\u00f6bb helyzetben lehets\u00e9ges. <\/p>\n

      Egyedi feladat megold\u00e1sa<\/h3>\n

      \nTeh\u00e1t az \u00e9n esetemben, miut\u00e1n a f\u00e1jlt Pandoc seg\u00edts\u00e9g\u00e9vel konvert\u00e1ltam, manu\u00e1lisan kellett tov\u00e1bbi feldolgoz\u00e1st v\u00e9geznem, m\u00e9gpedig<\/p>\n