Ndonjëherë jo vetëm dokumentacioni vetë, por edhe procesi i punës mbi të mund të jetë kritik. Për shembull, në rastin e projekteve, pjesa më e madhe e punës është e lidhur pikërisht me përgatitjen e dokumentacionit, dhe një proces i gabuar mund të çojë në gabime dhe madje në humbje informacioni, dhe, për pasojë, në humbje kohe dhe përfitimi. Por edhe nëse kjo temë nuk është qendrore në punën tuaj dhe ndodhet në periferinë, prapë procesi i duhur mund të përmirësojë cilësinë e dokumentit dhe të kursejë kohë.
Qasja e paraqitur këtu, me , ka një prag të ulët të hyrjes. Teknikisht, që nesër mund të filloni të punoni ndryshe.
Formulimi i detyrës
Ju nevojitet të krijoni një dokument ose një grup dokumentesh. Ndoshta, është dokumentacion projekti ose protokollimi i rrjetit tuaj, ose diçka më e thjeshtë, për shembull, duhet të përshkruani proceset në kompani ose në departamentin tuaj. Në përgjithësi, bëhet fjalë për çdo dokument ose grup dokumentesh me tekst, imazhe, tabela... Ta ndërlikojmë problemin duke marrë parasysh se
- kjo punë parasheh punë bashkëpunuese, përpjekje të një grupi ose disa grupeve të punonjësve
- me rezultatin që dëshironi të keni një dokument në një format të caktuar, me atributet e stilit korporativ, i krijuar sipas një shablli të caktuar. Për të qenë më të qartë do të marrëim parasysh se kjo është MS Word (.docx)
10 vite më parë, qasja do të ishte e qartë: do të kishim krijuar një dokument MS Word ose dokumente dhe në ndonjë formë do të organizonim punën mbi ndryshimin e tyre.
Dhe ajo qasje ende mbetet në fuqi. Ajo përdoret gjithashtu nga integratorët e mëdhenj në krijimin e dokumentacionit të projekteve. Por është intuitivisht e qartë se, nëse ju vërtet punoni intensivisht, me shumë ndryshime dhe diskutime, për një periudhë të gjatë kohore mbi një dokument, kjo qasje nuk është shumë e përshtatshme.
Shembulli
E ndjeva mjaft ndjeshëm këtë problem, duke punuar në një integrator të madh. Procesi i ndryshimit të dokumentacionit projekti ishte si vijon:
- injegjeri shkarkon versionin më të fundit të dokumentit MS Word (.docx)
- ndryshon emrin
- bën ndryshime në modin track
- dërgon dokumentin me ndryshimet tek arkitekti
- po ashtu dërgon një listë të të gjitha rregullimeve me komente
- arkitekti analizon ndryshimet
- nëse gjithçka është në rregull, atëherë kopjon këto ndryshime në dosjen me versionin më të fundit, ndryshon versionin dhe e shpërndan në burimin e përbashkët
- nëse ka vërejtje, fillon diskutimi (email ose takime)
- arrihet një konsensus
- pastaj pikat 3 - 9
Derisa puna nuk ka qenë intensive, kjo ka funksionuar më disa pengesa, por ndonjëherë ka ndodhur. Por në një moment të caktuar, ky proces u bë ngushtësia e të gjithë projektit dhe çoi në probleme. Problemi është se gjithçka shkon keq sapo ndryshimet bëhen shpesh dhe njëkohësisht nga disa ekipe.
KĂ«shtu, kur kaluam nĂ« fazĂ«n e testimit tĂ« parakohshĂ«m, filluan tĂ« shfaqen disa probleme, dhe ndonĂ«se ishin tĂ« vogla, duhet tĂ« ndryshohej shpesh dokumentacioni â katĂ«r ekipe tĂ« ndryshme, çdo ditĂ«, praktikisht nĂ« tĂ« njĂ«jtĂ«n kohĂ«, me diskutime. TĂ« gjitha kĂ«to ndryshime kalonin pĂ«rmes njĂ« inxhinieri â arkitektit. Skedari me dizajnin e projektit ishte i madh, dhe si pasojĂ«, arkitekti ishte i mbushur me punĂ« rutinĂ«, qĂ« kishte tĂ« bĂ«nte me njĂ« numĂ«r tĂ« madh kopjimesh dhe redaktimesh, bĂ«nte shumĂ« gabime, duhej tĂ« kontrolloheshin tĂ« gjitha, tĂ« dĂ«rgoheshin pĂ«rsĂ«ri, dhe gjithsesi, kjo ishte afĂ«r kaosit.
Në këtë rast, ky qasje, qasja për punën mbi dokumentin MS Word, funksiononte 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ë hulumtoj këtë çështje.
Pashë se po bëhet gjithnjë e më popullor përdorimi i bashkë me 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, problemi i punës shumëpërdoruese zgjidhet. Por për të shfrytëzuar plotësisht potencialin 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ë ideal.
Markdown është një gjuhë e thjeshtë e shënjimit të tekstit. Ajo është krijuar për të krijuar tekste në formate të bukura në skedarët e zakonshëm TXT. Nëse ne krijojmë dokumentet tona në Markdown, lidhja Markdown - Git duket natyrale.
E gjithçka do të ishte mirë, dhe në këtë pikë mund të vendosnim një pikë, nëse nuk do të ishte kushti ynë i 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 ne u dakorduam që për qartësi do të përdorim MS Word). Pra, nëse vendosim të përdorim Markdown, na nevojitet një mënyrë për ta transformuar këtë skedë në .docx të kërkuar.
Eksistojnë programe konvertimi midis formateve të ndryshme, për shembull, .
Mund të konvertoni një skedë Markdown në formatin .docx me këtë program.
Megjithatë, duhet ta kuptojmë se, në radhë të parë, nuk çdo gjë që është në Markdown do të konvertohet në MS Word dhe, në të dytë, MS Word është një vend i tërë në krahasim me qytetin e vogël, Markdown. Ka një sasi të madhe të gjitha atyre që janë në Word dhe nuk ekzistojnë në asnjë formë në Markdown. Nuk mund të merrni thjesht dhe të përdorni çelësa të caktuar në Pandoc për të konvertuar formatin tuaj Markdown në pamjen e dëshiruar të MS Word. Prandaj zakonisht, pas konvertimit, duhet të "përfundojmë" dokumentin e .docx të marrë manualisht, që gjithashtu mund të jetë e shtrenjtë në aspektin e kohës dhe të shkaktojë gabime.
Nëse do të mundnim të shkruanim një skenar të cilin automatikisht do të "dënte" atë që Pandoc nuk e kishte mbuluar, do të ishte zgjidhja perfekte.
Për shkak të mosidentitetit të funksionalitetit të MS Word dhe Markdown në mënyrë të përgjithshme, mendoj se është e pamundur të zgjidhet kjo detyrë, por a është e mundur ta realizojmë atë për situata specifike, kërkesa specifike? Përvoja ime ka treguar se po, është e mundur dhe ndoshta e mundur për shumë, ose ndoshta edhe për shumicën e situatave.
Zgjidhja e një detyre private
Pra, në rastin tim, pas konvertimit të skedës me Pandoc, më është dashur të bëj përpunim të mëtejshëm manual të skedave, pra
- të shtoj në Word fushat me numërim automatik të titujve (caption) për tabelat dhe imazhet
- të ndryshoj stilin për tabelat
Nuk e kam gjetur se si ta bëj këtë me mjete standarde (Pandoc) ose të njohura. Prandaj kam aplikuar një skenar python me paketë. Si rezultat, kam arritur automatizimin e plotë. Tani mund të konvertoj skedën time Markdown në formën e nevojshme të dokumentit MS Word me një komandë.
Shihni detajet .
VĂ«rejtje
Në këtë shembull, natyrisht, po konvertoj një skedar abstrakt Markdown, por qasja e njëjtë është përdorur për një dokument 'luftarak', dhe rezultati është një dokument MS Word pothuajse identik me atë që na jepnim me formatim manual.
Në përgjithësi, me pywin32 ne marrim kontroll praktikisht të plotë mbi dokumentin MS Word, duke na lejuar ta modifikojmë dhe ta sjellim në formën që kërkon standardi juaj korporativ. Sigurisht, këto qëllime mund të arrihen edhe me mjete të tjera, për shembull, makrot VBA, por mua më ishte më e lehtë të përdor python.
Formula e shkurtër e këtij qëndrim është:
Markdown + Git -- (diçka) --> MS WordNuk ka shumë rëndësi se çfarë është 'diçka'. Në rastin tim, ishte Pandoc dhe python me pywin32. Ndoshta ju keni preferenca të tjera, por e rëndësishme është se kjo është e mundur. Dhe kjo është mesazhi kryesor i këtij artikulli.
Në përfundim, ideja është që me një qasje të tillë, ju punoni vetëm me skedarin Markdown dhe përdorni Git për të organizuar punën në grup dhe për të kontrolluar versionet, dhe vetëm kur është e nevojshme (për shembull, për të ofruar dokumentacion klientit) krijoni automatikisht skedarin në formatin e nevojshëm (për shembull, MS Word).
Në ditën e fillimit të modulit, struktura e tij bëhet e disponueshme. Studimi në UoL përbëhet nga cikli në vijim:
Mendoj se për shumëkujt formula e sipërpërmendur është e mjaftueshme për të kuptuar se si mund të organizohet tani procesi i punës me dokumentacionin. Por gjithsesi, unë zakonisht orientohëm ndaj inxhinierëve rrjetë, prandaj në përgjithësi do të tregoj se si mund të duket tani procesi i punës dhe se çfarë e ndan atë nga qasja e redaktimit të skedarëve MS Word.
Për saktësinë, si platformë për të punuar me Git, do të zgjedhim GitHub. Atëherë ju duhet të krijoni një depo dhe në degën master të vendosni skedarin ose skedarët Markdown me të cilët planifikoni të punoni.
Ne do të shqyrtojmë një proces të thjeshtë, të bazuar në 'github flow'. Përshkrimi i tij mund të gjendet si në internet ashtu edhe në .
Supozoni se katër persona po punojnë mbi dokumentacionin dhe ju jeni një nga ata. Atëherë krijohen katër degë shtesë, për shembull, me emrat e këtyre njerëzve. Secili punon lokal, në degën e tij dhe bën ndryshime me të gjitha 'git' komandat e nevojshme. .
Pas një pjesë të përfunduar të punës, ju formoni një pull request, duke iniciuar kështu diskutimin mbi ndryshimet tuaja. Gjatë procesit të diskutimit, mund të rezultojë se duhet të shtoni apo ndryshoni diçka tjetër. Në këtë rast, shkoni përpara me ndryshimet e nevojshme dhe krijoni një pull request shtesë. Më në fund, ndryshimet tuaja pranohet dhe bashkohen (merge) me degën master (ose refuzohen).
Sigurisht, kjo është një përshkrim mjaft i përgjithshëm. Propozoj të kontaktoni zhvilluesit tuaj ose të gjeni njerëz të njohur për të krijuar një proces më të detajuar. Por dua të theksoj se kufiri i hyrjes në Git është mjaft i ulët. Kjo nuk do të thotë se protokolli është i thjeshtë, por ju mund të filloni me diçka të thjeshtë. Nëse nuk dini asgjë, mendoj se duke kaluar disa orë ose ndoshta ditë duke studiuar dhe instaluar, mund të filloni ta përdorni.
Cila është dobi nga ky qasja në krahasim me procesin, për shembull, të përshkruar më sipër?
Në të vërtetë, proceset janë mjaft të ngjashme, thjesht keni zëvendësuar
kopjimin e skedarit -> krijimin e një dege (branch)
kopjimin e tekstit në skedarin përfundimtar -> bashkimin (merge)
kopjimin e ndryshimeve të fundit tek vetja -> git pull/fetch
diskutimin përmes korrespondencës -> pull requests
modeshtyra e gjurmimit -> git diff
versioni i fundit të miratuar -> dega master
backup (kopjimi në serverin e largët) -> git push
âŠ
Kështu, ju keni automatizuar gjithçka që keni qenë të detyruar ta bëni, por me dorë.
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ë asaj që u përmend më lart, mendoj se është e qartë që, edhe nëse punoni një hapësirë dokumentacioni të vetme, 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 nevojshme pĂ«r krijimin e tij. Dhe njĂ« bonus i vogĂ«l â ju do tĂ« mĂ«soni Git, qĂ« do t'ju ndihmojĂ« nĂ« automatizimin e rrjetit tuaj đ.
Si të kaloni në procesin e ri?
Në fillim të artikullit kam shkruar se këtë e dytë mund të filloni të punoni ndryshe. Si ta ktheni punën tuaj në një rrugë të re?
Ja rendi i hapave që ndoshta do t'ju duhet të ndiqni:
- nëse dokumenti juaj është shumë i madh, ndahet në pjesë
- konvertoni çdo pjesë në Markdown (me Pandoc, për shembull)
- instaloni një nga redaktorët Markdown (unë përdor )
- me siguri do t'ju duhet të rregulloni formatimin e dokumenteve Markdown të krijuar
- filloni të aplikoni procesin e përshkruar në kapitullin e mëparshëm
- në të njëjtën kohë filloni të modifikoni skenarin e konvertimit për nevojat tuaja (ose krijoni diçka tuajën)
Nuk është e nevojshme të prisni derisa të krijoni dhe optimizoni 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ë skedarëve tuaj Markdown, ju akoma mund ta bëni këtë në ndonjë formë me Pandoc dhe më pas ta çoni në versionin përfundimtar me dorë. Zakonisht, nuk do t'ju duhet ta bëni këtë shpesh, por vetëm në fund të fazave të caktuara, dhe ky punë manuale, ndonëse e papërshtatshme, për mendimin tim është plotësisht e pranueshme në fazën e debugimit dhe nuk duhet ta "ngadalësojë" shumë procesin.
Gjithçka tjetër (Markdown, Git, Pandoc, Typora) është tashmë gati dhe nuk kërkon përpjekje ose kohë të veçantë për të filluar të punoni me to.
Burimi: habr.com
