{"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\/pl\/blog\/administrirovanie\/ispolzujte-git-pri-dokumentirovanii","title":{"rendered":"U\u017cyj GIT podczas dokumentacji","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

Czasami nie tylko sama dokumentacja, ale tak\u017ce proces pracy nad ni\u0105 mo\u017ce by\u0107 krytyczny. Na przyk\u0142ad w przypadku projekt\u00f3w lwia cz\u0119\u015b\u0107 pracy zwi\u0105zana jest z przygotowaniem dokumentacji, a niew\u0142a\u015bciwy proces mo\u017ce prowadzi\u0107 do b\u0142\u0119d\u00f3w, a nawet utraty informacji, a co za tym idzie, do utraty czasu i korzy\u015bci. Ale nawet je\u015bli ten temat nie jest centralny w Twojej pracy i znajduje si\u0119 na peryferiach, to i tak w\u0142a\u015bciwy proces mo\u017ce poprawi\u0107 jako\u015b\u0107 dokumentu i zaoszcz\u0119dzi\u0107 czas.<\/p>\n

Przedstawione podej\u015bcie, z przyk\u0142adem konkretnej realizacji<\/a><\/noindex>, ma niski pr\u00f3g wej\u015bcia. Technicznie, ju\u017c jutro mo\u017cesz zacz\u0105\u0107 pracowa\u0107 na nowo.
\n<\/a><\/noindex><\/p>\n

Sformu\u0142owanie zadania<\/h3>\n

\nMusisz stworzy\u0107 pewien dokument lub zestaw dokument\u00f3w. Mo\u017ce to by\u0107 dokumentacja projektowa lub protoko\u0142owanie sieci, albo co\u015b prostszego, na przyk\u0142ad musisz opisa\u0107 procesy w firmie lub w swoim dziale. Generalnie chodzi o ka\u017cdy dokument lub zestaw dokument\u00f3w z tekstem, obrazkami, tabelami\u2026 Utrudnimy zadanie tym, \u017ce <\/p>\n

    \n
  1. ta praca zak\u0142ada wsp\u00f3lny wysi\u0142ek, zaanga\u017cowanie grupy lub kilku grup pracownik\u00f3w<\/li>\n
  2. na wyj\u015bciu chcesz mie\u0107 dokument w okre\u015blonym formacie, z atrybutami korporacyjnego stylu, stworzony wed\u0142ug okre\u015blonego szablonu. Na potrzeby tego opisu przyjmijmy, \u017ce jest to MS Word (.docx)<\/li>\n<\/ol>\n

    \n10 lat temu podej\u015bcie by\u0142oby jednoznaczne: stworzyli\u015bmy by dokument MS Word lub dokumenty i w jaki\u015b spos\u00f3b zorganizowali prac\u0119 nad zmianami. <\/p>\n

    I to podej\u015bcie wci\u0105\u017c jest aktualne. Korzystaj\u0105 z niego r\u00f3wnie\u017c du\u017ce integratory przy tworzeniu dokumentacji projektowej. Ale intuicyjnie wiadomo, \u017ce, je\u015bli naprawd\u0119 intensywnie, z wieloma poprawkami i dyskusjami, przez d\u0142ugi czas pracujesz nad dokumentem, to to podej\u015bcie nie jest zbyt wygodne.<\/p>\n

    Przyk\u0142ad<\/b><\/p>\n

    Do\u015b\u0107 ostro odczu\u0142em ten problem, pracuj\u0105c w jednej du\u017cej firmie integracyjnej. Proces wprowadzania zmian w dokumentacji projektowej wygl\u0105da\u0142 nast\u0119puj\u0105co:<\/p>\n

      \n
    1. in\u017cynier pobiera najnowsz\u0105 wersj\u0119 dokumentu MS Word (.docx)<\/li>\n
    2. zmienia tytu\u0142<\/li>\n
    3. wprowadza poprawki w trybie track<\/li>\n
    4. wysy\u0142a dokument z poprawkami do architekta<\/li>\n
    5. tak\u017ce wysy\u0142a list\u0119 wszystkich poprawek z komentarzami<\/li>\n
    6. architekt analizuje zmiany<\/li>\n
    7. je\u015bli wszystko jest w porz\u0105dku, to kopiuje zmiany danych do pliku z ostatni\u0105 wersj\u0105, zmienia wersj\u0119, umieszcza na wsp\u00f3lnym zasobie<\/li>\n
    8. je\u015bli s\u0105 uwagi, to inicjowana jest dyskusja (e-mail lub spotkania)<\/li>\n
    9. osi\u0105gni\u0119to konsensus<\/li>\n
    10. dalej punkty 3 \u2013 9<\/li>\n<\/ol>\n

      \nDop\u00f3ki praca nie by\u0142a intensywna, to jako\u015b to dzia\u0142a\u0142o. Ale w pewnym momencie ten proces sta\u0142 si\u0119 w\u0105skim gard\u0142em ca\u0142ego projektu i doprowadzi\u0142 do problem\u00f3w. Chodzi o to, \u017ce wszystko staje si\u0119 \u017ale, gdy zmiany s\u0105 wprowadzane cz\u0119sto i jednocze\u015bnie przez kilka zespo\u0142\u00f3w.<\/p>\n

      Tak wi\u0119c, gdy przeszli\u015bmy do etapu wst\u0119pnego testowania, zacz\u0119\u0142y pojawia\u0107 si\u0119 r\u00f3\u017cne ma\u0142e problemy i, chocia\u017c drobne, konieczne by\u0142o cz\u0119ste zmienianie dokumentacji \u2014 cztery r\u00f3\u017cne zespo\u0142y, codziennie, niemal r\u00f3wnocze\u015bnie, z dyskusjami. Wszystkie te zmiany przechodzi\u0142y przez jednego in\u017cyniera \u2014 architekta. Plik z projektem by\u0142 ogromny, a w konsekwencji architekt by\u0142 przyt\u0142oczony rutynow\u0105 prac\u0105 zwi\u0105zan\u0105 z du\u017c\u0105 ilo\u015bci\u0105 kopiowania, edytowania, pope\u0142nia\u0142 wiele b\u0142\u0119d\u00f3w, musia\u0142 wszystko sprawdza\u0107, ponownie przesy\u0142a\u0107, a og\u00f3lnie to by\u0142o bliskie chaosowi. <\/p>\n

      W tym przypadku podej\u015bcie, polegaj\u0105ce na pracy nad dokumentem MS Word, dzia\u0142a\u0142o z du\u017cym op\u00f3\u017anieniem i tworzy\u0142o problemy.<\/p><\/blockquote>\n

      <\/p>\n

      Git, Markdown<\/h3>\n

      \nStykaj\u0105c si\u0119 z problemem opisanym w powy\u017cszym przyk\u0142adzie, zacz\u0105\u0142em bada\u0107 t\u0119 kwesti\u0119.
      \nZauwa\u017cy\u0142em, \u017ce coraz popularniejsze staje si\u0119 korzystanie z       Markdown<\/a><\/noindex> wraz z Gitem<\/a><\/noindex> przy tworzeniu dokument\u00f3w.<\/p>\n

      Git to narz\u0119dzie do rozwoju. Ale czemu nie u\u017cywa\u0107 go do procesu dokumentowania? W tym przypadku problem wieloosobowej pracy jest rozwi\u0105zany. Ale \u017ceby w pe\u0142ni wykorzysta\u0107 mo\u017cliwo\u015bci Gita, potrzebujemy tekstowego formatu dokumentu, musimy znale\u017a\u0107 inne narz\u0119dzie, kt\u00f3re nie jest MS Word, a do tych cel\u00f3w \u015bwietnie nadaje si\u0119 Markdown. <\/p>\n

      Markdown to prosty j\u0119zyk znacznik\u00f3w tekstowych. Jest przeznaczony do tworzenia estetycznie wygl\u0105daj\u0105cych tekst\u00f3w w zwyk\u0142ych plikach formatu TXT. Je\u015bli tworzymy nasze dokumenty w Markdown, to po\u0142\u0105czenie Markdown \u2014 Git wydaje si\u0119 naturalne.<\/p>\n

      I wszystko by\u0142oby dobrze, i w tym miejscu mo\u017cna by zako\u0144czy\u0107, gdyby nie nasz drugi warunek: \"na wyj\u015bciu potrzebujemy dokumentu w okre\u015blonym formacie, z atrybutami stylu korporacyjnego, stworzonego wed\u0142ug okre\u015blonego szablonu\" (i zgodzili\u015bmy si\u0119 na pocz\u0105tku, \u017ce dla pewno\u015bci b\u0119dzie to MS Word). To znaczy, je\u015bli zdecydowali\u015bmy si\u0119 u\u017cy\u0107 Markdown, to musimy jako\u015b przekszta\u0142ci\u0107 ten plik w .docx w wymaganym formacie.<\/p>\n

      Istniej\u0105 programy do konwersji mi\u0119dzy r\u00f3\u017cnymi formatami, na przyk\u0142ad, Pandoc<\/a><\/noindex>.
      \nMo\u017cesz przekonwertowa\u0107 plik Markdown na format .docx za pomoc\u0105 tego programu.
      \nJednak nale\u017cy pami\u0119ta\u0107, \u017ce po pierwsze, nie wszystko, co znajduje si\u0119 w Markdown, zostanie przekonwertowane na MS Word, a po drugie, MS Word to ca\u0142y kraj w por\u00f3wnaniu z prostym, ale mimo wszystko miasteczkiem, jakim jest Markdown. Istnieje ogromna liczba rzeczy, kt\u00f3re s\u0105 w Wordzie i w \u017cadnej formie nie ma ich w Markdown. Nie mo\u017cna po prostu wzi\u0105\u0107 i z okre\u015blonymi kluczami Pandoc przekonwertowa\u0107 formatu Markdown na po\u017c\u0105dany wygl\u0105d MS Word. Zazwyczaj wi\u0119c, po konwersji, trzeba r\u0119cznie \"poprawi\u0107\" otrzymany dokument .docx, co r\u00f3wnie\u017c mo\u017ce by\u0107 czasoch\u0142onne i prowadzi\u0107 do b\u0142\u0119d\u00f3w.<\/p>\n

      Gdyby\u015bmy mogli napisa\u0107 skrypt, kt\u00f3ry automatycznie \"wyka\u0144cza\u0142by\" to, z czym nie poradzi\u0142 sobie Pandoc \u2014 to by\u0142oby idealne rozwi\u0105zanie.<\/p>\n

      Ze wzgl\u0119du na niejednorodno\u015b\u0107 funkcjonalno\u015bci MS Word i Markdown w og\u00f3lnym zarysie, my\u015bl\u0119, \u017ce rozwi\u0105zanie tego problemu jest niemo\u017cliwe, ale czy mo\u017cna to zrobi\u0107 w odniesieniu do konkretnych sytuacji, konkretnych wymaga\u0144? Moje do\u015bwiadczenie pokazuje, \u017ce tak, mo\u017cna to zrobi\u0107 i najprawdopodobniej jest to mo\u017cliwe w wielu, a mo\u017ce nawet w wi\u0119kszo\u015bci sytuacji. <\/p>\n

      Rozwi\u0105zanie konkretnego problemu<\/h3>\n

      \nTak wi\u0119c, w moim przypadku, po konwersji pliku za pomoc\u0105 Pandoc, musia\u0142em r\u0119cznie przeprowadzi\u0107 dodatkow\u0105 obr\u00f3bk\u0119 plik\u00f3w, a mianowicie<\/p>\n