🥇Koristite GIT pri dokumentiranju

Ponekad ne samo sama dokumentacija, nego i proces rada na njoj može biti kritičan. Na primjer, u slučaju projekata, veliki dio posla povezan je upravo s pripremom dokumentacije, a pogrešan proces može dovesti do grešaka i čak gubitka informacija, a samim tim i do gubitka vremena i koristi. No, čak i ako ova tema nije središnja u vašem radu i nalazi se na periferiji, ispravan proces može ipak poboljšati kvalitetu dokumenta i uštedjeti vam vrijeme.

Pristup opisan ovdje, s primjerom konkretne implementacije, ima nizak prag ulaska. Tehnički, već sutra možete početi raditi na nov način.

Postavljanje zadatka

Trebate stvoriti neki dokument ili skup dokumenata. Možda je to projektna dokumentacija ili evidencija vaše mreže, ili nešto jednostavnije, poput opisa procesa u tvrtki ili vašem odjelu. U osnovi, radi se o bilo kojem dokumentu ili skupu dokumenata s tekstom, slikama, tablicama… Dodatno ćemo zakomplicirati zadatak time što

ova radnja podrazumijeva zajednički rad, trud grupe ili nekoliko grupa zaposlenika
na izlazu želite imati dokument u određenom formatu, s elementima korporativnog stila, izrađen prema određenom predlošku. Za točnost ćemo uzeti da je to MS Word (.docx)

Prije 10 godina pristup bi bio nedvosmislen: stvorili bismo MS Word dokument ili dokumente i na neki način organizirali rad na izmjenama.

I takav pristup i dalje je na snazi. Koriste ga i veliki integratori prilikom izrade projektne dokumentacije. No, intuicija govori da, ako stvarno intenzivno radite s brojnim izmjenama i raspravama tijekom dužeg razdoblja, taj pristup nije baš praktičan.

Primjer
Ovu sam problematiku osjetio vrlo snažno radeći u jednom velikom integratoru. Proces izmjene projektne dokumentacije bio je sljedeći:

inženjer preuzima posljednju verziju MS Word (.docx) dokumenta

mijenja naziv

unosi izmjene u track modu

šalje dokument s izmjenama arhitektu

također šalje popis svih izmjena s komentarima

arhitekt analizira promjene

ako je sve u redu, kopira izmjene u datoteku s posljednjom verzijom, mijenja verziju, objavljuje na zajedničkom resursu

ako postoje primjedbe, pokreće se rasprava (email ili sastanci)

postigne se konsenzus

dalje stavke 3 — 9
Dok rad nije bio intenzivan, sve je nekako funkcioniralo. No u jednom trenutku ovaj proces je postao usko grlo cijelog projekta i doveo je do problema. Naime, sve postaje loše kada se promjene često i istovremeno provode od strane nekoliko timova.
Kada smo prešli na fazu preliminarnog testiranja, počeli su se javljati različiti problemi i, iako su bili sitni, dokumentaciju je trebalo često mijenjati — četiri različita tima, svakodnevno, gotovo istovremeno, s raspravama. Sve te promjene prolazile su kroz jednog inženjera — arhitekta. Datoteka sa dizajnom projekta bila je ogromna, i kao posljedica toga, arhitekt je bio zatrpan rutinom koja je uključivala mnogo kopiranja, uređivanja, pravio je brojne greške, a sve je trebalo ponovo provjeravati, ponovno slati, i općenito, to je bilo blizu kaosu.
U ovom slučaju, ovaj pristup, pristup radu s dokumentom MS Word, radio je s velikim naporom i stvarao probleme.

Git, Markdown

Suočen s problemom opisanim u gornjem primjeru, počeo sam istraživati to pitanje.
Primijetio sam da postaje sve popularnije korištenje Markdown u suradnji s Git prilikom izrade dokumenata.

Git je alat za razvoj. No, zašto ga ne koristiti za proces dokumentiranja? U tom slučaju, pitanje višekorisničkog rada postaje riješeno. No kako bismo u potpunosti iskoristili mogućnosti Gita, potreban nam je tekstualni format dokumenta, trebamo pronaći drugi alat, osim MS Word-a, a za te svrhe Markdown se odlično uklapa.

Markdown je jednostavan jezik za markup teksta. Namijenjen je za izradu lijepo oblikovanih tekstova u običnim TXT datotekama. Ako budemo kreirali naše dokumente u Markdown-u, veza između Markdown-a i Gita izgleda prirodno.

Sve bi bilo dobro i ovdje bismo mogli staviti točku, da nije naše drugog uvjeta: „na izlazu nam treba dokument u određenom formatu, s atributima korporativnog stila, izrađen po određenom predlošku“ (i dogovorili smo se na početku da će to biti MS Word). To jest, ako smo odlučili koristiti Markdown, moramo nekako pretvoriti ovu datoteku u .docx traženog izgleda.

Postoje programi za konverziju između različitih formata, na primjer, Pandoc.
Možete pretvoriti Markdown datoteku u .docx format s ovim programom.
No, treba razumjeti da, prvo, neće sve što postoji u Markdowu biti pretvoreno u MS Word i, drugo, MS Word je cijela zemlja u usporedbi s jednostavnim, ali ipak malim gradom, Markdown. Postoji ogromna količina sadržaja koji postoji u Wordu, a nijedan oblik u Markdownu. Ne možete jednostavno tako uzeti i s određenim ključevima Pandoc konvertirati vaš Markdown format u željeni izgled MS Worda. Dakle, obično, nakon konverzije, treba 'dorađivati' dobiveni .docx dokument ručno, što opet može biti vremenski zahtjevno i dovesti do pogrešaka.

Kad bismo mogli napisati skript koji bi automatski 'dovršavao' ono s čime se Pandoc nije mogao nositi — to bi bilo idealno rješenje.

Zbog nepodudarnosti funkcionalnosti MS Worda i Markdowda u općem smislu, mislim da je rješavanje ovog zadatka nemoguće, ali može li se to učiniti primjenjivo na konkretne situacije, konkretne zahtjeve? Moje iskustvo je pokazalo da, da, to je moguće i vjerojatno je to moguće za mnoge, ili možda čak većinu situacija.

Rješenje posebnog zadatka

Dakle, u mom slučaju, nakon konverzije datoteke pomoću Pandoca, morao sam ručno napraviti dodatnu obradu datoteka, naime,

dodavati u Word polja s automatskim numeriranjem naslova (caption) tablica i slika
mijenjati stil za tablice

Nisam pronašao kako to učiniti standardnim (Pandoc) ili poznatim sredstvima. Stoga sam primijenio python skript s pywin32 paketom. Kao rezultat, dobio sam punu automatizaciju. Sada mogu pretvoriti svoju Markdown datoteku u potreban oblik MS Word dokumenta jednom naredbom.

Pogledajte detalje ovdje.

Napomena
U ovom primjeru, naravno, pretvaram jedan apstraktni Markdown dokument, no isti pristup primijenjen je na "borbeni" dokument, a na izlazu sam dobio gotovo identičan MS Word dokument kao onaj koji smo prije dobivali ručnim formatiranjem.

Uglavnom, s pywin32 dobivamo gotovo potpunu kontrolu nad MS Word dokumentom, što omogućava njegovu promjenu i prilagodbu izgledu koji zahtijeva vaš korporativni standard. Naravno, isti ciljevi mogli bi se postići i korištenjem drugih alata, primjerice VBA makronaredbi, ali meni je bila praktičnija uporaba Pythona.

Kratka formula ovog pristupa:

Markdown + Git -- (nešto) --> MS Word

Nije tako važno što je "nešto". U mom slučaju to su bili Pandoc i Python s pywin32. Možda imate druge preferencije, ali važno je da je to moguće. I to je glavni cilj ovog članka.

Ukratko, ideja je da s ovakvim pristupom radite samo s Markdown dokumentom i koristite Git za organizaciju suradnje i kontrolu verzija, a samo po potrebi (na primjer, za pružanje dokumentacije klijentu) automatski kreirate datoteku potrebnog formata (na primjer, MS Word).

Proces

Mislim da je za mnoge formula navedena iznad dovoljna za razumijevanje kako bi se sad mogao organizirati proces rada s dokumentacijom. Ipak, ja se obično orijentiram na mrežne inženjere, stoga ću u općim crtama prikazati kako sada može izgledati proces rada i čime se razlikuje od pristupa s uređivanjem MS Word datoteka.

Za konkretnost, kao platformu za rad s Git-om odabiremo GitHub. Tada trebate stvoriti repozitorij i u master grani staviti Markdown datoteku ili datoteke s kojima planirate raditi.

Istražit ćemo jednostavan proces temeljen na "github flow". Njegov opis možete pronaći i na internetu, a također i na habru.

Pretpostavimo da na dokumentaciji rade četiri osobe i vi ste jedna od njih. Tada se kreiraju četiri dodatne grane, primjerice, s imenima tih ljudi. Svaki radi lokalno, u svojoj grani i radi promjene sa svim potrebnim git naredbama.

Kada završite neki dovršeni dio posla, stvarate pull request, čime inicirate raspravu o vašim promjenama. Tijekom rasprave, možda će se pokazati da trebate dodati ili promijeniti još nešto. U tom slučaju, izvršavate potrebne izmjene i kreirate dodatni pull request. Na kraju, vaše promjene se prihvaćaju i spajaju (merge) s master granom (ili se odbacuju).

Naravno, to je prilično općenit opis. Predlažem da se za izradu detaljnog procesa obratite svojim programerima ili pronađete stručne osobe. No, želim napomenuti da je ulazni prag za Git prilično nizak. To ne znači da je protokol jednostavan, ali možete započeti s jednostavnim. Ako ne znate ništa, mislim da ćete, potrošivši nekoliko sati ili možda dana na učenje i instalaciju, moći početi koristiti.

Koja je korist ovog pristupa u usporedbi, na primjer, s procesom opisanom u gornjem primjeru?

U stvari, procesi su prilično slični, samo ste zamijenili

kopiranje datoteke -> stvaranje grane (branch)
kopiranje teksta u konačnu datoteku -> spajanje (merge)
kopiranje posljednjih promjena na sebe -> git pull/fetch
rasprava u korespondenciji -> pull requests
track mode -> git diff
najnovija odobrena verzija -> master grana
backup (kopiranje na udaljeni server) -> git push
…

Tako ste automatizirali sve ono što ste već morali raditi ručno.

Na višoj razini to vam omogućuje

stvaranje jasnog, jednostavnog i kontroliranog procesa izmjena dokumentacije
pošto konačni dokument (u našem primjeru MS Word) stvarate automatski, to smanjuje vjerojatnost grešaka povezanih s formatiranjem

Napomena
U svjetlu gore navedenog, mislim da je očito da, čak i ako radite na dokumentaciji sami, korištenje Gita može značajno olakšati vaš rad.

Sve to poboljšava kvalitetu dokumentacije i smanjuje vrijeme potrebno za njezino stvaranje. I još mali bonus — naučit ćete Git, što će vam pomoći u automatizaciji vaše mreže 🙂

Kako preći na novi proces?

Na početku članka napisao sam da već sutra možete započeti raditi na novi način. Kako prevesti svoj rad u novo područje?

Evo redoslijeda koraka koje ćete vjerojatno morati izvršiti:

ako je vaš dokument vrlo velik, podijelite ga na dijelove
konvertirajte svaki dio u Markdown (na primjer, putem Pandoca)
instalirajte jedan od Markdown uređivača (koristim Typora)
vjerojatno ćete morati prilagoditi formatiranje stvorenih Markdown dokumenata
počnite primjenjivati proces opisan u prethodnom poglavlju
paralelno počnite prilagođavati skriptu konverzije prema svojim potrebama (ili izradite nešto svoje)

Nije potrebno čekati da savršeno izradite i ispravite mehanizam konverzije Markdown -> traženi izlazni oblik dokumenta. Činjenica je da, čak i ako ne uspijete brzo potpuno automatizirati postupak transformacije vaših Markdown datoteka, i dalje ćete moći to učiniti u nekom obliku pomoću Pandoca i zatim dovesti do konačnog oblika ručno. Obično to ne trebate raditi često, nego samo na kraju određenih faza, a taj ručni rad, iako neudoban, još uvijek je, prema mom mišljenju, potpuno prihvatljiv u fazi ispravljanja i ne bi trebao značajno „usporavati“ proces.

Sve ostalo (Markdown, Git, Pandoc, Typora) već je spremno i ne zahtijeva posebne napore ili vrijeme za početak rada s njima.

Izvor: habr.com