Përdorni GIT në dokumentim

Nganjëherë jo vetëm dokumentacioni vetë, por edhe procesi i punës mbi të mund të jetë kritik. Për shembull, në rastet e projekteve, pjesa më e madhe e punës është e lidhur saktësisht me përgatitjen e dokumentacionit, dhe një proces i gabuar mund të çojë në gabime dhe madje në humbje informacioni, dhe, për rrjedhojë, në humbje kohë dhe përfitimi. Por edhe nëse ky temë nuk është qendrore në punën tuaj dhe ndodhet në periferinë, akoma një proces i saktë mund të përmirësojë cilësinë e dokumentit dhe t'ju kursejë kohë.

Qasja e përshkruar këtu, me shembullin e një zbatimi konkret, ka një nivel të ulët hyrjeje. Teknikisht, mund të filloni të punoni ndryshe, që nesër.

Vendosja e detyrës

Ju duhet të krijoni një dokument ose një set dokumentesh. Ndoshta është dokumentacioni i projektit ose protokollimi i rrjetit tuaj, ose diçka më e thjeshtë, për shembull, ju duhet të përshkruani proceset në kompaninë tuaj ose në departamentin tuaj. Për të thënë në përgjithësi, bëhet fjalë për çdo dokument ose grup dokumentesh me tekst, imazhe, tabela... Le ta komplikohemi këtë detyrë sepse

1. kjo punë parashikon bashkëpunim, përpjekje nga një grup ose disa grupe punonjësish
2. në fund do të dëshironit të keni një dokument në një format të caktuar, me atributet e stilit korporativ, i krijuar sipas një shablloni të caktuar. Për saktësi, do të supozojmë se është MS Word (.docx)

Para 10 vjetësh, qasja do të ishte e qartë: do të krijonim një dokument ose dokumente MS Word dhe ndonjëherë do ta organizonim punën për ndryshime.

Dhe kjo qasje është ende në fuqi. Kjo përdoret gjithashtu nga integratorët e mëdhenj për krijimin e dokumentacionit të projekteve. Por intuitivisht kuptohet se, nëse vërtet punoni intensivisht, me shumë ndryshime dhe diskutime, për një periudhë të gjatë mbi një dokument, kjo qasje nuk është shumë e shkathët.

Shembuj

E ndjeva fort këtë problem ndërsa punoja në një integrator të madh. Procesi i ndryshimit të dokumentacionit të projektit ishte si në vazhdim:

1. inxhinieri shkarkon versionin më të fundit të dokumentit MS Word (.docx)
2. ndryshon emrin
3. bën ndryshime në modin track
4. dërgon dokumentin me ndryshime te arkitekti
5. po ashtu dërgon një listë të të gjitha korrigjimeve me komente
6. arkitekti analizon ndryshimet
7. nëse gjithçka është në rregull, ai kopjon ndryshimet në skedarin me versionin më të fundit, ndërron versionin, e ngarkohet në burimin e përbashkët
8. nëse ka vërejtje, inicohet një diskutim (email ose takime)
9. arrihet një konsensusi
10. pastaj pikat 3 - 9

Ndërsa puna nuk ishte intensive, kjo funksiononte ndonjë mënyrë. Por në një moment të caktuar, ky proces u bë ngushti kryesor i një projekti të tërë dhe solli probleme. Problemi ishte që çdo gjë bëhet e keqe sapo ndryshimet bëhen shpesh dhe ndodhen paralelisht nga disa ekipe.

Kështu, kur kaluam në fazën e testimit paraprak, filluan të shfaqen probleme të ndryshme dhe, ndonëse ishin të vogla, por ishte nevoja të ndryshoheshin dokumentet shpesh - katër ekipe të ndryshme, çdo ditë, pothuajse në të njëjtën kohë, me diskutime. Të gjitha këto ndryshime kalonin përmes një inxhinieri - arkitetkti. Skeda me dizajnin e projektit ishte e madhe, dhe si rrjedhojë, arkitekti ishte i mbingarkuar me punë rutinore të lidhura me kopjimin dhe redaktimin të madhe, bënte shumë gabime, duhej të kontrollonte gjithçka, të riposlisi, dhe në përgjithësi kjo ishte afër kaosit.

Në këtë rast, qasja, qasja e punës mbi dokumentin MS Word, punonte me shumë vështirësi dhe krijonte probleme.

Git, Markdown

Duke u përballur me problemin e përshkruar në shembullin e mësipërm, fillova të shqyrtoj këtë çështje.
Pashë se gjithnjë e më shumë po bëhej e zakonshme të përdorej Markdown në kombinim me Git në krijimin e dokumenteve.

Git është një mjet për zhvillim. Por pse të mos e përdorim atë për procesin e dokumentimit? Në këtë rast, çështja e punës shumëpërdoruesve zgjidhet. Por për të shfrytëzuar plotësisht mundësitë e Git, na nevojitet një format tekstual dokumenti, na nevojitet të gjejmë një mjet tjetër, jo MS Word, dhe për këto qëllime Markdown është i përshtatshëm.

Markdown është një gjuhë e thjeshtë e përshkrimit të tekstit. Ajo është e destinuar për të krijuar tekste të bukura në skedarët e zakonshëm me format TXT. Nëse krijojmë dokumentet tona në Markdown, atëherë lidhja Markdown - Git duket natyrale.

Dhe çdo gjë do të ishte në rregull, dhe në këtë pikë do të ishte e mundshme të vendosej një pikë, sikur të mos e kishim kushtin tonë të dytë: "në dalje na nevojitet një dokument në një format të caktuar, me atributet e stilit korporativ, i krijuar sipas një shablloni të caktuar" (dhe u dakorduam në fillim, se për qartësi kjo do të jetë MS Word). Kështu, nëse vendosëm të përdorim Markdown, na nevojitet një mënyrë për të konvertuar këtë skedar në formatin .docx që kërkohet.

Ekzistojnë programe konvertimi midis formateve të ndryshme, për shembull, Pandoc.
Ju mund të konvertoni skedarin Markdown në format .docx me këtë program.
Megjithatë, është e rëndësishme të kuptohet se, përveç të tjerash, jo çdo gjë që është në Markdown do të konvertohet në MS Word dhe, për më tepër, MS Word është një vend i tërë krahasuar me qytetin e rregullt që është Markdown. Ka një sasi të madhe gjërash që gjenden në Word dhe nuk ekzistojnë në asnjë formë në Markdown. Nuk mund të merrni thjesht skedarin dhe me disa çelësa të Pandoc ta konvertoni formatin tuaj Markdown në pamjen e dëshiruar MS Word. Prandaj, zakonisht, pas konvertimit, nevojitet "përpunimi" i dokumentit .docx të marrë manualisht, gjë që gjithashtu mund të jetë e kushtueshme në aspektin e kohës dhe të çojë në gabime.

Nëse do të ishim në gjendje të shkruanim një skript që automatikisht "përfundonte" atë që Pandoc nuk e kishte bërë - do të ishte një zgjidhje ideale.

Duke pasur parasysh se funksionaliteti i MS Word dhe Markdown nuk është identik në terma të përgjithshëm, unë mendoj se zgjidhja e kësaj detyre është e pamundur, por a mund të bëhet kjo për situata specifike, për kërkesa specifike? Eksperienca ime ka treguar se po, është e mundur dhe ndoshta për shumë, ose mund të jetë madje për shumicën e situatave.

Zgjidhja e një detyre të veçantë

Pra, në rastin tim, pas konvertimit të skedarit me ndihmën e Pandoc, më duhej të bëja përpunim të mëtejshëm manual të skedarëve, konkretisht

• shto për Word fushat me numërim automatik të titujve (caption) të tabelave dhe imazheve
• ndrysho stilin për tabelat

Nuk kam gjetur se si të bëj këtë me mjete standarde (Pandoc) ose mjete të njohura. Prandaj, aplikova një skript python me pywin32 paketë. Si rezultat, arrita automatizim të plotë. Tani mund të konvertoj skedarin tim Markdown në formatin e nevojshëm të dokumentit MS Word me një komandë.

Shikoni detajet këtu.

Vërejtje

Në këtë shembull, natyrisht, unë transformoj një skedar të caktuar Markdown, por po kështu është përdorur të njëjtin qasje për një dokument "luftarak", dhe në përfundim mora një dokument MS Word shumë të ngjashëm me atë që kishim marrë më parë me formatim manual.

Në përgjithësi, me pywin32 ne marrim kontrolle praktikisht të plota mbi dokumentin MS Word, që na lejon ta ndryshojmë dhe ta përfundojmë sipas standardeve të korporatës suaj. Natyrisht, këto qëllime mund të arrihen gjithashtu me mjete të tjera, për shembull, makro VBA, por mua më ishte më e lehtë të përdor python.

Formula e shkurtër e këtij qasja është:

Markdown + Git -- (diçka) --> MS Word

Nuk është aq e rëndësishme çfarë është "diçka". Në rastin tim, kjo ishte Pandoc dhe python me pywin32. Ndoshta keni preferenca të tjera, por e rëndësishme është se kjo është e mundur. Dhe kjo është mesazhi kryesor i këtij artikulli.

Për të përmbledhur, ideja është që me këtë qasje punoni vetëm me skedarin Markdown dhe përdorni Git për të organizuar punën ekipore dhe për menaxhimin e versioneve, dhe vetëm kur është e nevojshme (për shembull, për të ofruar dokumentacion për klientin) automatikisht krijoni skedarin e nevojshëm (për shembull, MS Word).

Procesi

Mendoj se për shumë njerëz formula e përmendur më lart është mjaft e mjaftueshme për të kuptuar se si tani mund të organizohet procesi i punës me dokumentacionin. Por unë zakonisht orientohem për inxhinierët e rrjetit, prandaj në mënyrë të përgjithshme do të ilustroj se si tani mund të duket procesi i punës, dhe çfarë ndryshon nga qasja me redaktimin e skedarëve MS Word.

Për qartësi, si platformë për punën me Git do të zgjidhnim GitHub. Atëherë duhet të krijoni një depo dhe në degën master të vendosni skedarin ose skedarët Markdown me të cilët keni në plan të punoni.

Ne do të shqyrtojmë një proces të thjeshtë, të bazuar në "git flow". Përshkrimi i tij mund të gjendet si në internet, ashtu edhe në habr.

Supozoni se katër persona po punojnë mbi dokumentacionin dhe ju jeni njëri prej tyre. Atëherë krijohen katër degë të tjera (branch), për shembull, me emrat e këtyre njerëzve. Çdo njeri punon lokal në degën e tij dhe bën ndryshime me të gjitha komandat e nevojshme git..

Pas përfundimit të një pjesë pune, formoni një pull request, duke njohtuar kështu diskutimin për ndryshimet tuaja. Ndoshta, gjatë diskutimit, do të zbuloni se duhet të shtoni ose ndryshoni diçka tjetër. Në këtë rast, ju bëni ndryshimet e nevojshme dhe krijoni një pull request të mëtejshëm. Në fund, ndryshimet tuaja pranohet dhe bashkohen (merge) me degën master (ose hidhen poshtë).

Sigurisht, kjo është një përshkrim mjaft i përgjithshëm. Sugjeroj që për të krijuar një proces të detajuar të kontaktoni zhvilluesit tuaj ose të gjeni njerëz të njohur. Por dua të nënvizoj se pragu i hyrjes në Git është mjaft i ulët. Kjo nuk do të thotë se protokolli është i thjeshtë, por mund të filloni me diçka të thjeshtë. Nëse nuk dini asgjë, mendoj se duke shpenzuar disa orë ose ndoshta disa ditë për të studiuar dhe instaluar, mund të filloni ta përdorni atë.

Cila është dobi e këtij qasjeje krahasuar, për shembull, me procesin e përshkruar në shembullin më sipër?

Në të vërtetë, proceset janë mjaft të ngjashme, thjesht keni zëvendësuar

kopjimin e skedarit -> krijimin e degës (branch)
kopjimin e tekstit në skedarin përfundimtar -> bashkimin (merge)
kopjimin e ndryshimeve të fundit për vete -> git pull/fetch
diskutimin në komunikim -> kërkesat për tërheqje (pull requests)
modaliteti i ndjekjes -> git diff
versioni i fundit të miratuar -> dega master
backup (kopjimi në serverin e largët) -> git push
…

Pra, keni automatizuar të gjitha ato që duhet t'i bënit edhe manualisht.

Në një nivel më të lartë, kjo ju lejon të

• krijoni një proces të qartë, të thjeshtë dhe të kontrolluar për ndryshimin e dokumentacionit
• pasi dokumenti përfundimtar (në shembullin tonë MS Word) krijohet automatikisht, kjo zvogëlon mundësinë e gabimeve të lidhura me formatimin

Vërejtje

Për shkak të ç’kësaj, mendoj se është e qartë se, edhe nëse punoni vetëm mbi dokumentacionin, përdorimi i Git mund të lehtësojë ndjeshëm punën tuaj.

Të gjitha këto rrisin cilësinë e dokumentacionit dhe zvogëlojnë kohën e krijimit të tij. Dhe një bonus i vogël - do të mësoni Git, gjë që do t'ju ndihmojë në automatizimin e rrjetit tuaj 🙂

Si të kaloni në procesin e ri?

Në fillim të artikullit kam shkruar se nesër mund të filloni të punoni ndryshe. Si ta drejtoni punën tuaj në një rrjedhë të re?

Ja se si do të duhet të veproni:

• nëse dokumenti juaj është shumë i madh, ndahet në pjesë
• konvertoni secilën pjesë në Markdown (p.sh., me Pandoc)
• installoni një nga redaktoret e Markdown (unë përdor Typora)
• ndoshta do t'ju duhet të rregulloni formatimin e dokumenteve Markdown të krijuara
• filloni të aplikoni procesin e përshkruar në kapitullin e mëparshëm
• në të njëjtën kohë filloni ta modifikoni skenarin e konvertimit për nevojat tuaja (ose krijoni diçka tuajën)

Nuk është e nevojshme të prisni derisa të krijoni dhe miratoni në mënyrë të përkryer mekanizmin e konvertimit Markdown -> pamja e kërkuar e dokumentit. E vërteta është se, edhe nëse nuk arrini të automatizoni shpejt procedurën e transformimit të dosjeve tuaja Markdown, sërish do të jeni në gjendje ta bëni atë në një formë me Pandoc dhe pastaj ta arrini pamjen përfundimtare manualisht. Zakonisht nuk është e nevojshme ta bëni këtë shpesh, por vetëm në fund të fazave të caktuara, dhe kjo punë manuale, ndonëse e pakëndshme, është gjithsesi, në mendimin tim, mjaft e pranueshme në fazën e testimit dhe nuk duhet të ngadalësojë shumë procesin.

Të gjitha të tjerat (Markdown, Git, Pandoc, Typora) janë tashmë gati dhe nuk kërkojnë shumë përpjekje ose kohë për t'u filluar punën me to.

Burimi: habr.com