Ponekad ne samo sama dokumentacija, već i proces njenog izrade može biti kritičan. Na primjer, u slučaju projekata, veći dio posla često je povezan s pripremom dokumentacije, a pogrešan proces može dovesti do grešaka i čak gubitka informacija, što može rezultirati gubitkom vremena i profita. Međutim, čak i ako ova tema nije centralna u vašem radu i nalazi se na periferiji, pravilan proces može poboljšati kvalitetu dokumenta i uštedjeti vam vrijeme.
Pristup ovdje izložen, uz , ima nizak prag ulaska. Tehnički, već sutra možete početi raditi na novi način.
Postavljanje zadatka
Trebate stvoriti neki dokument ili set dokumenata. Možda je to projektna dokumentacija ili evidentiranje vaše mreže, ili nešto jednostavnije, na primjer, trebate opisati procese u tvrtki ili u vašem odjelu. U suštini, radi se o bilo kom dokumentu ili skupu dokumenata s tekstom, slikama, tablicama... Otežat ćemo stvar time što
- ovaj rad podrazumijeva zajednički rad, napore grupe ili više grupa zaposlenika
- na izlazu želite imati dokument u određenom formatu, s atributima korporativnog stila, izrađen prema određenom predlošku. Za definitivan pristup, smatrat ćemo da je to MS Word (.docx)
Prije 10 godina pristup bi bio jasan: stvorili bismo MS Word dokumente i na neki način organizirali rad na izmjenama.
I takav pristup i dalje je na snazi. Koriste ga, između ostalog, i veliki integratori prilikom izrade projektne dokumentacije. No, intuitivno je jasno da, ako intenzivno radite na dokumentu s mnogim izmjenama i raspravama kroz dulje razdoblje, ovaj pristup nije vrlo praktičan.
Primjer
Oštro sam osjetio ovaj problem dok sam radio u jednom velikom integratoru. Proces izmjene projektne dokumentacije bio je sljedeći:
- inženjer preuzima najnoviju verziju MS Word (.docx) dokumenta
- mijenja naziv
- unosi izmjene u track modu
- šalje dokument s izmjenama arhitektu
- također šalje popis svih ispravki s komentarima
- arhitekt analizira promjene
- ako je sve u redu, kopira te promjene u datoteku s najnovijom verzijom, mijenja verziju, postavlja na zajednički resurs
- ako postoje primjedbe, pokreće se rasprava (email ili sastanci)
- postigne se konsensus
- zatim stavke 3 — 9
Dok rad nije bio intenzivan, to je nekako funkcionisalo, ali u jednom trenutku, ovaj proces je postao usko grlo celog projekta i doveo do problema. Naime, stvari postaju loše čim se izmjene često i istovremeno vrše od strane više timova.
Tako, kada smo prešli na fazu preliminarnog testiranja, počeli su se javljati različiti problemi i, iako su bili sitni, bilo je potrebno često mijenjati dokumentaciju — četiri različita tima, svakodnevno, gotovo istovremeno, uz rasprave. Sve te promjene prolazile su kroz jednog inženjera — arhitektu. Datoteka sa dizajnom projekta bila je ogromna, i kao rezultat, arhitekta je bio preopterećen rutinskim radom vezanim za veliku količinu kopiranja, uređivanja, pravio je mnogo grešaka, sve se moralo ponovo proveravati, proslijediti, i u suštini, to je bilo blizu haosa.
U ovom slučaju, ovaj pristup, pristup radu sa dokumentom MS Word, radio je sa velikim trudom i stvarao probleme.
Git, Markdown
Suočen s problemom opisanim u gornjem primjeru, počeo sam istraživati ovo pitanje.
Primijetio sam da postaje sve popularnije korištenje u kombinaciji sa prilikom kreiranja dokumenata.
Git je alat za razvoj. Ali zašto ga ne koristiti u procesu dokumentovanja? U tom slučaju, pitanje višekorisničkog rada biva riješeno. Ali da bismo u potpunosti iskoristili mogućnosti Gita, potreban nam je tekstualni format dokumenta, potrebno je pronaći drugi alat, ne MS Word, a za te svrhe veoma dobro odgovara Markdown.
Markdown je jednostavni jezik za označavanje teksta. Namijenjen je za kreiranje lijepo formatiranih tekstova u običnim TXT datotekama. Ako budemo pravili naše dokumente u Markdownu, povezanost Markdown — Git izgleda prirodno.
Sve je to u redu, i ovdje bismo mogli staviti tačku, da nije našeg drugog uslova: "na izlazu nam treba dokument u određenom formatu, sa atributima korporativnog stila, napravljen prema određenom šablonu" (i dogovorili smo se na početku da će to za preciznost biti MS Word). Dakle, ako smo odlučili koristiti Markdown, moramo nekako pretvoriti ovaj fajl u .docx traženog izgleda.
Postoje programi za konverziju između različitih formata, na primer, .
Možete pretvoriti Markdown fajl u .docx format pomoću ovog programa.
Ali, ipak, treba imati na umu da, prvo, nije sve što postoji u Markdown-u konvertovano u MS Word, i drugo, MS Word je čitava ‘zemlja’ u poređenju sa skladnim, ali i dalje malo gradom, Markdown. Postoji ogroman broj stvari u Word-u koje ni na koji način ne postoje u Markdown-u. Ne možete samo tako uzeti i sa određenim ključevima Pandoc-a pretvoriti vaš Markdown format u željeni oblik MS Word-a. Tako da obično, nakon konverzije, morate "doraditi" dobijeni .docx dokument ručno, što opet može biti vremenski skupo i dovesti do grešaka.
Da smo mogli napisati skript koji bi automatski "dovršavao" ono što Pandoc nije uspeo — to bi bilo idealno rešenje.
Zbog nejednakosti funkcionalnosti MS Word-a i Markdown-a u opštem smislu, mislim da je rešenje ovog zadatka nemoguće, ali da li se to može učiniti u odnosu na konkretne situacije, konkretne zahteve? Moje iskustvo pokazuje da da, moguće je i verovatno to je moguće za mnoge, ili možda čak i većinu situacija.
Rešenje privatnog zadatka
Dakle, u mom slučaju, nakon konverzije fajla pomoću Pandoc-a, morao sam ručno da radim dodatnu obradu fajlova, a to je
- dodavanje u Word polja sa automatskim numerisanjem naslova (caption) tabela i slika
- promena stila za tabele
Nisam našao kako to učiniti standardnim (Pandoc) ili poznatim sredstvima. Zato sam primenio python skript sa paketom. Kao rezultat, dobio sam potpunu automatizaciju. Sada mogu da konvertujem moj Markdown fajl u potrebnu formu MS Word dokumenta jednom komandom.
Pogledajte detalje .
Napomena
U ovom primjeru, naravno, transformišem neki apstraktni Markdown fajl, ali je isti pristup primijenjen na "borbeni" dokument, i na izlazu sam dobio gotovo identičan MS Word dokument koji smo prethodno dobijali ručnim formatiranjem.
Ukratko, s pywin32 dobijamo gotovo potpunu kontrolu nad MS Word dokumentom, što nam omogućava da ga promijenimo i oblikujemo prema zahtjevima vašeg korporativnog standarda. Naravno, iste ciljeve bi bilo moguće postići i korištenjem drugih alata, poput VBA makroa, ali mi je bilo zgodnije koristiti python.
Kratka formula ovog pristupa:
Markdown + Git -- (nešto) --> MS WordNije toliko važno šta predstavlja "nešto". U mom slučaju to su bili Pandoc i python s pywin32. Možda imate drugačije preferencije, ali važno je da je to moguće. A to je i glavna poruka ovog članka.
Ukratko, ideja je da prilikom ovog pristupa radite samo s Markdown fajlom i koristite Git za organizaciju zajedničkog rada i kontrolu verzija, a samo po potrebi (na primjer, da biste klijentu dostavili dokumentaciju) automatski kreirate fajl potrebnog formata (na primjer, MS Word).
Proces
Mislim da je za mnoge formula navedena iznad dovoljna da shvate kako se proces rada s dokumentacijom sada može organizovati. No obično se fokusiram na mrežne inženjere, pa ću u opštim crtama pokazati kako sada može izgledati proces rada i po čemu se razlikuje od pristupa s uređivanjem MS Word fajlova.
Za preciznost, kao platformu za rad s Git odabiremo GitHub. Tada trebate kreirati repozitorij i u master grani smjestiti Markdown fajl ili fajlove s kojima planirate raditi.
Pogledaćemo jednostavan proces zasnovan na "github flow". Njegovo objašnjenje možete pronaći i na internetu i na .
Pretpostavimo da na dokumentaciji rade četiri osobe i da ste vi jedan od njih. Tada se kreiraju četiri dodatne grane (branch), na primjer, s imenima tih osoba. Svako radi lokalno, u svojoj grani i vrši promjene sa svim potrebnim .
Kada završite neki deo posla, formirate pull request, čime započinjete raspravu o vašim izmenama. Tokom rasprave, može se desiti da saznate da treba da dodate ili promenite još nešto. U tom slučaju, izvršavate potrebne izmene i kreirate dodatni pull request. Na kraju, vaše izmene se prihvataju i spajaju (merge) sa master granom (ili se odbacuju).
Naravno, ovo je prilično opisa. Predlažem da se za kreiranje detaljnih procesa obratite vašim programerima ili pronađete ljude koji se time bave. Ali želim napomenuti da je prag ulaska u Git prilično nizak. To ne znači da je protokol jednostavan, ali možete početi s jednostavnim stvarima. Ako ne znate ništa, mislim da biste, posvetivši nekoliko sati ili možda dana učenju i instaliranju, mogli početi da ga koristite.
Koja je korist od ovog pristupa u poređenju, na primer, sa procesom opisanim u gornjem primeru?
U stvari, procesi su prilično slični, samo ste zamenili
kopiranje datoteke -> kreiranje grane (branch)
kopiranje teksta u konačnu datoteku -> spajanje (merge)
kopiranje poslednjih izmena k sebi -> git pull/fetch
rasprava u prepisci -> pull requests
track mode -> git diff
poslednja odobrena verzija -> master grana
backup (kopiranje na udaljeni server) -> git push
…
Tako ste automatizovali sve ono što ste već morali da radite, ali ručno.
Na višem nivou, to vam omogućava
- da kreirate jasan, jednostavan i kontrolisan proces promena dokumentacije
- pošto konačni dokument (u našem primeru MS Word) kreirate automatski, to smanjuje verovatnoću grešaka vezanih za formatiranje
Napomena
Zbog gore navedenog, mislim da je očigledno da, čak i ako radite sami na dokumentaciji, korišćenje Gita može značajno olakšati vaš rad.
Sve to poboljšava kvalitet dokumentacije i smanjuje vreme potrebno za njeno kreiranje. I još jedna mala pogodnost — naučićete Git, što će vam pomoći u automatizaciji vaše mreže 🙂
Kako preći na novi proces?
Na početku članka sam napisao da već sutra možete početi raditi na nov način. Kako prebaciti svoj rad na novu stazu?
Evo redosleda koraka koje ćete verovatno morati da izvršite:
- ako je vaš dokument veoma veliki, podelite ga na delove
- konvertujte svaki deo u Markdown (na primer, koristeći Pandoc)
- instalirajte jedan od Markdown uređivača (koristim )
- verovatno ćete morati da prilagodite formatiranje stvorenih Markdown dokumenata
- počnite da primenjujete proces opisan u prethodnoj glavi
- paralelno počnite da menjate skript za konverziju prema svojoj potrebi (ili napravite nešto svoje)
Nije potrebno da čekate da dovršite i debagujete mehanizam konverzije Markdown -> željeni izlazni oblik dokumenta. Činjenica je da, čak i ako ne možete brzo potpuno automatizovati proceduru prevođenja vaših Markdown datoteka, i dalje ćete moći to da učinite na neki način koristeći Pandoc, a zatim dovedete do finalnog izgleda ručno. Obično nije potrebno to raditi često, već samo na kraju određenih faza, a ova ručna posao, iako nezgodan, ipak je, po mom mišljenju, posve prihvatljiv u fazi debagovanja i ne bi trebao previše da „uspori“ proces.
Sve ostalo (Markdown, Git, Pandoc, Typora) već je spremno i ne zahteva posebne napore ili vreme da biste započeli rad s njima.
Izvor: habr.com
