Včasih ni kritična le sama dokumentacija, temveč tudi proces dela z njo. Na primer, v primeru projektov je velika večina dela povezana prav s pripravami dokumentacije, nepravilni proces pa lahko privede do napak in celo izgube informacij, kar posledično pomeni izgubo časa in koristi. Vendar pa tudi če ta tema ni osrednja v vašem delu in je na obrobju, pravi proces vseeno lahko izboljša kakovost dokumenta in vam prihrani čas.
Predlagan pristop, s , ima nizek prag vstopa. Tehnično lahko že jutri začnete delati na nov način.
Definisanje zadatka
Potrebno je pripraviti nek dokument ali niz dokumentov. Morda gre za projektno dokumentacijo ali protokoliranje vaše mreže, ali kaj bolj preprostega, na primer opisati procese v podjetju ali vaši ekipi. Na splošno gre za kateri koli dokument ali niz dokumentov s tekstom, slikami, tabelami… Zadevo nekoliko zapleteno, saj
- ta delo predpostavlja skupinsko delo, prizadevanja skupine ali več skupin zaposlenih
- na izhodu želite imeti dokument v določenem formatu, z atributi korporativne identitete, ustvarjen po določenem predlogi. Za večjo jasnost bomo predpostavljali, da gre za MS Word (.docx)
Pred 10 leti bi bil pristop enostavno določen: ustvarili bi MS Word dokumente ali dokument in na nek način organizirali delo pri spremembah.
In tak pristop še vedno velja. Uporabljajo ga tudi veliki integratorji pri izdelavi projektne dokumentacije. Vendar je intuitivno jasno, da, če res intenzivno delate z mnogimi spremembami in razpravami dolgotrajno na dokumentu, ta pristop ni ravno priročen.
Primer
To težavo sem močno občutil, ko sem delal pri enem od velikih integratorjev. Proces spreminjanja projektne dokumentacije je bil naslednji:
- inženir prenese zadnjo različico MS Word (.docx) dokumenta
- spremeni naslov
- vnaša popravke v načinu sledenja
- pošlje dokument s popravki arhitektu
- prav tako pošlje seznam vseh popravkov s komentarji
- arhitekt analizira spremembe
- če je vse v redu, kopira te spremembe v datoteko z zadnjo različico, spremeni različico in objavi na skupnem viru.
- če so pripombe, se sproži razprava (elektronska pošta ali sestanki)
- dosežemo konsenzus
- nato točke 3 — 9
Dokler delo ni bilo intenzivno, je to nekako delovalo. Vendar je v določenem trenutku ta proces postal šibka točka celotnega projekta in povzročil težave. Gre za to, da se stvari poslabšajo, takoj ko se spremembe izvajajo pogosto in hkrati z več ekipami.
Tako, ko smo prešli na fazo predtestiranja, so se začele pojavljati različne težave in, čeprav so bile majhne, je bilo treba pogosto spreminjati dokumentacijo — štiri različne ekipe, dnevno, praktično hkrati, z razpravami. Vse te spremembe so potekale preko enega inženirja — arhitekta. Datoteka s projektom je bila ogromna in kot posledica je bil arhitekt obremenjen z rutinskim delom, ki je zahtevalo veliko kopiranja in urejanja, delal je veliko napak, vse je bilo treba ponovno preverjati, ponovno pošiljati in na splošno je bilo to blizu kaosa.
V tem primeru je ta pristop, pristop dela z dokumentom MS Word, deloval z obsežnim trudom in ustvarjal težave.
Git, Markdown
Ko sem se srečal s težavo, opisano v zgornjem primeru, sem začel raziskovati to vprašanje.
Opazil sem, da postaja vse bolj priljubljena uporaba skupaj z pri ustvarjanju dokumentov.
Git je orodje za razvoj. Ampak zakaj ga ne bi uporabili za proces dokumentiranja? V tem primeru postane vprašanje večuporabniškega dela rešeno. Vendar pa, da bi v polni meri izkoristili zmogljivosti Gita, potrebujemo besedilni format dokumenta, morali bi najti drugo orodje, ne MS Word, in za te namene je Markdown odlična izbira.
Markdown je preprost jezik za oblikovanje besedila. Namenjen je ustvarjanju lepo oblikovanih besedil v običajnih TXT datotekah. Če bomo naše dokumente ustvarjali v Markdownu, se povezava Markdown — Git zdi naravna.
Vse bi bilo dobro, in na tem mestu bi lahko postavili piko, če ne bi bilo našega drugega pogoja: „na izhodu potrebujemo dokument v določenem formatu, z atributi korporativne podobe, ustvarjen po določenem predlošku“ (in dogovorili smo se na začetku, da bo to za natančnost MS Word). To pomeni, da če smo se odločili uporabiti Markdown, moramo nekako pretvoriti to datoteko v .docx zahtevane oblike.
Obstajajo programa za pretvorbo med različnimi formati, na primer, .
Markdown datoteko lahko pretvorite v .docx format s tem programom.
Vendar pa je treba razumeti, da, prvič, ne vse, kar je v Markdownu, bo pretvorjeno v MS Word, in, drugič, MS Word je cela država v primerjavi z urejenim, a še vedno majhnim mestom, Markdownom. Obstaja ogromno vsega, kar je v Wordu in ni v nobeni obliki v Markdownu. Ni mogoče kar tako vzeti in s specifičnimi ključi Pandoc pretvoriti vašega Markdown formata v želeno obliko MS Word. Tako, da običajno, po pretvorbi, morate „dodelati“ pridobljen .docx dokument ročno, kar spet lahko pomeni stroške glede časa in privede do napak.
Če bi lahko napisali skript, ki bi samodejno "dodelal" tisto, s čimer se Pandoc ni spopadel — bi to bilo idealno rešitev.
Glede na nekonkretizirano funkcionalnost MS Word in Markdown v splošnem vidim, da je ni mogoče rešiti, vendar ali je to mogoče storiti v povezavi s specifičnimi situacijami, specifičnimi zahtevami? Moje izkušnje so pokazale, da, da, in verjetno je to mogoče za mnoga, ali morda celo večino situacij.
Rešitev specifične naloge
Tako sem v mojem primeru po pretvorbi datoteke s pomočjo Pandoc moral ročno opraviti dodatno obdelavo datotek, natančneje
- dodati v Word polja z samodejno številčenjem naslovov (caption) tabel in slik
- spremeniti slog za tabele
Nisem našel, kako to storiti s standardnimi (Pandoc) ali znanimi sredstvi. Zato sem uporabil Python skript z paketom. Tako sem dosegel popolno avtomatizacijo. Zdaj lahko svoj Markdown dokument pretvorim v potrebno obliko MS Word dokumenta z eno ukazom.
Oglejte si podrobnosti .
Napomena
V tem primeru seveda pretvarjam nek abstrakten Markdown dokument, vendar je bil isti pristop uporabljen tudi na »bojnem« dokumentu, in na koncu sem dobil skoraj povsem enak dokument MS Word, kot smo ga prej pridobili z ročnim oblikovanjem.
Na splošno, s pywin32 dobimo skoraj popoln nadzor nad dokumentom MS Word, kar omogoča, da ga spremenimo in uredimo v skladu z vašimi korporativnimi standardi. Seveda bi lahko dosegli iste cilje tudi z uporabo drugih orodij, na primer, VBA makrov, vendar mi je bilo lažje uporabljati python.
Kratka formula tega pristopa je:
Markdown + Git -- (nekaj) --> MS WordNi tako pomembno, kaj to »nekaj« je. V mojem primeru je bil to Pandoc in python s pywin32. Morda imate druge preference, vendar je pomembno, da je to mogoče. To je glavno sporočilo tega članka.
Povzamem, ideja je v tem, da pri takem pristopu delate samo z Markdown datoteko in uporabljate Git za organizacijo skupnega dela in za nadzor različic, ter le po potrebi (na primer, za predstavljanje dokumentacije stranki) avtomatsko ustvarjate datoteko želene oblike (na primer, MS Word).
Postopek
Mislim, da je za mnoge formula, predstavljena zgoraj dovolj, da razumejo, kako je zdaj organiziran postopek dela z dokumentacijo. Vendar pa običajno usmerjam k omrežnim inženirjem, zato bom na splošno pokazal, kako je zdaj lahko videti postopek dela in kako se razlikuje od pristopa z urejanjem MS Word datotek.
Za jasnost, kot platformo za delo z Git izberimo GitHub. Tako morate ustvariti repozitorij in v master veji postaviti Markdown datoteko ali datoteke, s katerimi načrtujete delo.
Preučili bomo preprost postopek, ki temelji na »github flow«. Njegov opis najdete tako na internetu kot tudi na .
Predlagajmo, da na dokumentaciji dela štiri osebe in ste vi eden izmed njih. Takrat se ustvarijo štiri dodatne veje, na primer z imeni teh ljudi. Vsak deluje lokalno, v svoji veji in dela spremembe s vsemi potrebnimi .
Izvedbo določenega dela ustvarite pull request, s čimer sprožite razpravo o vaših spremembah. Med razpravo se lahko izkaže, da morate dodati ali spremeniti še kaj. V tem primeru opravite potrebne spremembe in ustvarite dodatni pull request. Na koncu se vaše spremembe sprejmejo in združijo (merge) z master vejo (ali se zavrnejo).
Seveda, to je precej splošen opis. Predlagam, da za oblikovanje natančnega postopka povprašate svoje razvijalce ali najdete nekoga, ki se spozna na to. Vendar želim omeniti, da je vstopna ovira za Git precej nizka. To ne pomeni, da je protokol preprost, vendar lahko začnete na preprost način. Če popolnoma nič ne veste, menim, da lahko po nekaj urah ali morda dneh raziskovanja in nastavitve začnete uporabljati Git.
Kakšna je korist tega pristopa v primerjavi z dosedanjim postopkom, opisanem zgoraj?
V resnici sta si postopka precej podobna, le da ste zamenjali
kopiranje datoteke -> ustvarjanje veje (branch)
kopiranje besedila v končno datoteko -> združitev (merge)
kopiranje zadnjih sprememb k sebi -> git pull/fetch
razprava v komunikaciji -> pull requests
način sledenja -> git diff
zadnja potrjena različica -> master veja
varnostna kopija (kopiranje na oddaljeni strežnik) -> git push
…
Tako ste avtomatizirali vse, kar ste prej počeli ročno.
Na višji ravni vam to omogoča,
- da ustvarite jasen, enostaven in nadzorovan postopek sprememb dokumentacije.
- Ker končni dokument (v našem primeru MS Word) avtomatsko ustvarjate, to zmanjšuje verjetnost napak, povezanih s formatiranjem.
Napomena
Glede na zgoraj navedeno je očitno, da lahko tudi če delate na dokumentaciji sami, uporaba Git-a bistveno olajša vaše delo.
Vse to izboljša kakovost dokumentacije in zmanjšuje čas, potreben za njeno ustvarjanje. In še dodaten bonus — naučili se boste Git-a, kar vam bo pomagalo pri avtomatizaciji vašega omrežja 🙂
Kako preiti na nov postopek?
Na začetku članka sem navedel, da lahko že jutri začnete delati na nov način. Kako preusmeriti svoje delo v novo smer?
Tukaj je zaporedje korakov, ki jih boste verjetno morali izvesti:
- če je vaš dokument zelo obsežen, ga razdelite na dele.
- pretvorite svaki deo u Markdown (na primer, koristeći Pandoc)
- instalirajte jedan od Markdown urednika (ja koristim )
- verovatno ćete morati da prilagodite formatiranje napravljenih Markdown dokumenata
- počnite da primenjujete proces opisan u prethodnoj glavi
- paralelno počnite da menjate skriptu konverzije prema vašim potrebama (ili kreirajte nešto svoje)
Nije potrebno da čekate da savršeno kreirate i ispravite mehanizam konverzije Markdown -> željeni izlazni oblik dokumenta. Činjenica je da, čak i ako ne uspete brzo u potpunosti automatizovati postupak konverzije vaših Markdown fajlova, i dalje možete to uraditi u nekom obliku koristeći Pandoc, a zatim dovesti do konačnog oblika ručno. Obično ne morate često to raditi, već samo na kraju određenih faza, a ovaj ručni rad, iako nezgodan, je po mom mišljenju sasvim prihvatljiv u fazi ispravke i ne bi trebalo da znatno usporava proces.
Sve ostalo (Markdown, Git, Pandoc, Typora) je već spremno i ne zahteva posebne napore ili vreme da biste počeli da radite s njima.
Izvor: habr.com
