{"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\/ro\/blog\/administrirovanie\/ispolzujte-git-pri-dokumentirovanii","title":{"rendered":"Utiliza\u021bi GIT pentru documentare","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

Uneori, nu doar documenta\u021bia \u00een sine, ci \u0219i procesul de lucru asupra acesteia poate fi critic. De exemplu, \u00een cazul proiectelor, o mare parte din munc\u0103 este legat\u0103 de preg\u0103tirea documenta\u021biei, iar un proces gre\u0219it poate duce la erori \u0219i chiar la pierderea informa\u021biilor, deci \u0219i la pierderi de timp \u0219i profit. Dar chiar dac\u0103 aceast\u0103 tem\u0103 nu este central\u0103 \u00een activitatea dumneavoastr\u0103 \u0219i se afl\u0103 \u00een periferie, un proces corect poate \u00eembun\u0103t\u0103\u021bi calitatea documentului \u0219i v\u0103 poate economisi timp.<\/p>\n

Abordarea prezentat\u0103 aici, cu exemplu de implementare concret\u0103<\/a><\/noindex>, prezint\u0103 un prag de accesibilitate sc\u0103zut. Tehnic, pute\u021bi \u00eencepe s\u0103 lucra\u021bi diferit chiar de m\u00e2ine.
\n<\/a><\/noindex><\/p>\n

Formularea problemei<\/h3>\n

\nTrebuie s\u0103 crea\u021bi un document sau un set de documente. Poate c\u0103 este documenta\u021bia proiectului sau documentarea re\u021belei dumneavoastr\u0103, sau ceva mai simplu, de exemplu, trebuie s\u0103 descrie\u021bi procesele din companie sau din departamentul dumneavoastr\u0103. \u00cen general, vorbim despre orice document sau set de documente cu text, imagini, tabele... S\u0103 complic\u0103m sarcina av\u00e2nd \u00een vedere c\u0103 <\/p>\n

    \n
  1. aceast\u0103 activitate implic\u0103 colaborare, eforturi ale unui grup sau a mai multor grupuri de angaja\u021bi<\/li>\n
  2. la final dori\u021bi s\u0103 ave\u021bi un document \u00eentr-un format specific, cu atributele stilului corporativ, creat conform unui anumit \u0219ablon. Pentru a fi mai specific, s\u0103 presupunem c\u0103 este vorba despre MS Word (.docx)<\/li>\n<\/ol>\n

    \nAcum 10 ani, abordarea ar fi fost clar\u0103: am fi creat un document MS Word sau documente \u0219i am organizat \u00een vreun fel munca de modificare. <\/p>\n

    \u0218i aceast\u0103 abordare este \u00eenc\u0103 valabil\u0103. Aceasta este folosit\u0103 \u0219i de mari integratori pentru crearea documenta\u021biei proiectului. Dar este intuitiv clar c\u0103, dac\u0103 lucra\u021bi intensiv, cu multe modific\u0103ri \u0219i discu\u021bii, pe parcursul unei perioade \u00eendelungate asupra unui document, aceast\u0103 abordare nu este foarte convenabil\u0103.<\/p>\n

    Exemplu<\/b><\/p>\n

    Am resim\u021bit destul de acut aceast\u0103 problem\u0103 lucr\u00e2nd pentru un mare integrator. Procesul de modificare a documenta\u021biei proiectului era urm\u0103torul:<\/p>\n

      \n
    1. inginerul descarc\u0103 ultima versiune a documentului MS Word (.docx)<\/li>\n
    2. schimb\u0103 titlul<\/li>\n
    3. face modific\u0103ri \u00een modul de urm\u0103rire a modific\u0103rilor<\/li>\n
    4. trimite documentul cu modific\u0103rile arhitectului<\/li>\n
    5. de asemenea, trimite lista tuturor corec\u021biilor cu comentarii<\/li>\n
    6. arhitectul analizeaz\u0103 schimb\u0103rile<\/li>\n
    7. dac\u0103 totul este bine, copiaz\u0103 modific\u0103rile \u00een fi\u0219ierul cu ultima versiune, schimb\u0103 versiunea, \u00eel \u00eencarc\u0103 pe resursa comun\u0103<\/li>\n
    8. dac\u0103 exist\u0103 observa\u021bii, se ini\u021biaz\u0103 o discu\u021bie (email sau \u00eent\u00e2lniri)<\/li>\n
    9. se atinge consensul<\/li>\n
    10. apoi punctele 3 - 9<\/li>\n<\/ol>\n

      \nP\u00e2n\u0103 acum, activitatea nu a fost intensiv\u0103, a\u0219a c\u0103 a func\u021bionat cumva, dar totu\u0219i a func\u021bionat. Totu\u0219i, \u00eentr-un anumit moment, acest proces a devenit un loc str\u00e2mt al \u00eentregului proiect \u0219i a dus la probleme. Problema este c\u0103 totul devine complicat c\u00e2nd modific\u0103rile sunt frecvente \u0219i sunt efectuate simultan de mai multe echipe.<\/p>\n

      A\u0219adar, c\u00e2nd am trecut la etapa de testare preliminar\u0103, au \u00eenceput s\u0103 apar\u0103 diverse probleme \u0219i, de\u0219i erau m\u0103runte, a fost nevoie s\u0103 modific\u0103m frecvent documenta\u021bia \u2014 patru echipe diferite, zilnic, practic simultan, cu discu\u021bii. Toate aceste modific\u0103ri treceau printr-un inginer \u2014 arhitect. Fi\u0219ierul cu designul proiectului era enorm \u0219i, ca urmare, arhitectul a fost sufocat de munca de rutin\u0103 legat\u0103 de un volum mare de copiere, editare, f\u0103cea multe gre\u0219eli, trebuia s\u0103 verifice totul din nou, s\u0103 redirec\u021bioneze, \u0219i \u00een general, a fost aproape haos. <\/p>\n

      \u00cen acest caz, abordarea de lucru cu documentul MS Word a func\u021bionat cu mult\u0103 str\u00e2nsoare \u0219i a creat probleme.<\/p><\/blockquote>\n

      <\/p>\n

      Git, Markdown<\/h3>\n

      \n\u00cenfrunt\u00e2nd problema descris\u0103 \u00een exemplul de mai sus, am \u00eenceput s\u0103 investighez acest subiect.
      \nAm observat c\u0103 devine din ce \u00een ce mai popular s\u0103 folosim       Markdown<\/a><\/noindex> \u00eempreun\u0103 cu Git<\/a><\/noindex> \u00een crearea documentelor.<\/p>\n

      Git este un instrument pentru dezvoltare. Dar de ce s\u0103 nu-l folosim pentru procesul de documentare? \u00cen acest caz, problema muncii multi-utilizator devine rezolvat\u0103. Dar pentru a profita la maxim de capacit\u0103\u021bile Git, avem nevoie de un format text pentru document, trebuie s\u0103 g\u0103sim un alt instrument, nu MS Word, iar pentru aceste scopuri, Markdown se potrive\u0219te perfect. <\/p>\n

      Markdown este un limbaj simplu de marcare a textului. Este destinat cre\u0103rii de texte frumos formatate \u00een fi\u0219iere normale de format TXT. Dac\u0103 ne cre\u0103m documentele \u00een Markdown, atunci leg\u0103tura Markdown - Git devine natural\u0103.<\/p>\n

      \u0218i totul ar fi fost bine, iar \u00een acest loc s-ar fi putut pune punct, dac\u0103 nu ar fi fost a doua condi\u021bie: \u201ela ie\u0219ire avem nevoie de un document \u00eentr-un anumit format, cu atributele stilului corporativ, creat dup\u0103 un anumit \u0219ablon\u201d (\u0219i ne-am \u00een\u021beles la \u00eenceput c\u0103, pentru claritate, acesta va fi MS Word). Adic\u0103, dac\u0103 am decis s\u0103 folosim Markdown, atunci trebuie s\u0103 transform\u0103m acest fi\u0219ier \u00een .docx de forma necesar\u0103.<\/p>\n

      Exist\u0103 programe de conversie \u00eentre diferite formate, de exemplu, Pandoc<\/a><\/noindex>.
      \nPute\u021bi converti fi\u0219ierul Markdown \u00een format .docx folosind acest program.
      \nDar, totu\u0219i, trebuie s\u0103 \u00een\u021belegem c\u0103, pe de o parte, nu tot ceea ce exist\u0103 \u00een Markdown va fi convertit \u00een MS Word \u0219i, pe de alt\u0103 parte, MS Word este o \u00eentreag\u0103 lume comparativ cu ora\u0219ul bine organizat numit Markdown. Exist\u0103 o mul\u021bime de lucruri \u00een Word care nu exist\u0103 \u00een niciun fel \u00een Markdown. Nu po\u021bi pur \u0219i simplu s\u0103 iei \u0219i s\u0103 converte\u0219ti formatul t\u0103u Markdown \u00een forma dorit\u0103 \u00een MS Word cu anumite chei \u00een Pandoc. A\u0219a c\u0103, de obicei, dup\u0103 conversie, trebuie s\u0103 \u201efinaliz\u0103m\u201d documentul .docx ob\u021binut manual, ceea ce din nou poate fi consumator de timp \u0219i poate duce la erori.<\/p>\n

      Dac\u0103 am putea scrie un script care s\u0103 \u201efinalizeze\u201d automat tot ceea ce nu a reu\u0219it Pandoc \u2014 ar fi solu\u021bia ideal\u0103.<\/p>\n

      Av\u00e2nd \u00een vedere c\u0103 func\u021bionalitatea MS Word \u0219i Markdown nu sunt identice \u00een general, consider c\u0103 a rezolva aceast\u0103 sarcin\u0103 este imposibil, dar se poate face \u00een raport cu situa\u021bii concrete, cerin\u021be specifice? Experien\u021ba mea a ar\u0103tat c\u0103 da, este posibil \u0219i cel mai probabil aceasta este posibil\u0103 pentru multe sau poate chiar majoritatea situa\u021biilor. <\/p>\n

      Rezolvarea unei probleme specifice<\/h3>\n

      \nAstfel, \u00een cazul meu, dup\u0103 conversia fi\u0219ierului cu ajutorul Pandoc, a trebuit s\u0103 fac manual procesarea suplimentar\u0103 a fi\u0219ierelor, \u0219i anume<\/p>\n