Pri dokumentiranju uporabite GIT

Včasih je kritična ne le sama dokumentacija, ampak tudi proces dela na njej. Pri projektih je na primer levji delež dela povezan s pripravo dokumentacije, nepravilen proces pa lahko povzroči napake in celo izgubo informacij ter posledično izgubo časa in koristi. Toda tudi če ta tema ni osrednja za vaše delo in je na obrobju, lahko pravi postopek še vedno izboljša kakovost dokumenta in vam prihrani čas.

Pristop, opisan tukaj, s primer konkretne izvedbe, ima nizko vstopno oviro. Tehnično lahko jutri začnete delati na nov način.

Izjava o težavah

Ustvariti morate dokument ali niz dokumentov. Morda je to projektna dokumentacija ali beleženje vašega omrežja ali pa kaj preprostejšega, na primer opisati morate procese v podjetju ali v vašem oddelku. Na splošno govorimo o katerem koli dokumentu ali nizu dokumentov z besedilom, slikami, znaki ... Zakomplicirajmo nalogo z dejstvom, da

1. gre za skupno delo, prizadevanja skupine ali več skupin zaposlenih
2. Posledično želite imeti dokument v določeni obliki, z atributi korporativnega sloga, ustvarjen po določeni predlogi. Če smo natančni, bomo predpostavili, da je to MS Word (.docx)

Pred 10 leti bi bil pristop preprost: ustvarili bi dokument MS Word ali dokumente in nekako organizirali delo pri spremembah.

In ta pristop še vedno velja. Uporabljajo ga tudi veliki integratorji pri izdelavi projektne dokumentacije. Vendar je intuitivno jasno, da če res intenzivno delate na dokumentu, s številnimi urejanji in razpravami, v daljšem časovnem obdobju, ta pristop ni zelo priročen.

Primer

To težavo sem občutil zelo akutno, ko sem delal za velikega integratorja. Postopek spreminjanja projektne dokumentacije je potekal takole:

1. inženir prenese najnovejšo različico dokumenta MS Word (.docx).
2. spremeni ime
3. naredi spremembe, da sledi modi
4. dokument z popravki pošlje arhitektu
5. pošlje tudi seznam vseh popravkov s komentarji
6. arhitekt analizira spremembe
7. če je vse v redu, te spremembe prekopira v datoteko z najnovejšo različico, spremeni različico in jo naloži v skupni vir
8. če so pripombe, se sproži razprava (e-pošta ali sestanki)
9. doseženo soglasje
10. nadaljnje točke 3-9

Čeprav delo ni bilo intenzivno, je nekako bilo, a vseeno je šlo. Toda na določeni točki je ta proces postal ozko grlo celotnega projekta in povzročil težave. Bistvo je, da se stvari poslabšajo takoj, ko se spremembe izvajajo pogosto in hkrati s strani več ekip.

Torej, ko smo prešli v fazo predhodnega testiranja, so se začele pojavljati različne težave in, čeprav v malem, je bilo treba pogosto spreminjati dokumentacijo - štiri različne ekipe, vsak dan, skoraj istočasno, z razpravami. Vse te spremembe so potekale preko enega inženirja – arhitekta. Projektna datoteka je bila ogromna in posledično je bil arhitekt preobremenjen z rutinskim delom, ki je vključevalo veliko kopiranja, urejanja, naredil je veliko napak, moral je vse dvakrat preveriti, znova poslati in na splošno je bilo blizu kaos.

V tem primeru je ta pristop, pristop dela na dokumentu MS Word, deloval zelo težko in povzročal težave.

Git, Markdown

Ko sem se soočil s težavo, opisano v zgornjem primeru, sem začel raziskovati to težavo.
Videl sem, da uporaba Markdown skupaj z git pri izdelavi dokumentov.

Git je razvojno orodje. Toda zakaj ga ne bi uporabili za postopek dokumentacije? V tem primeru se reši vprašanje večuporabniškega dela. Toda da bi v celoti izkoristili Gitove zmožnosti, potrebujemo format besedilnega dokumenta, poiskati moramo orodje, ki ni MS Word, in Markdown je odličen za te namene.

Markdown je preprost jezik za označevanje besedila. Zasnovan je za ustvarjanje lepo oblikovanih besedil v običajnih datotekah TXT. Če svoje dokumente ustvarimo v Markdownu, je kombinacija Markdown – Git videti naravna.

In vse bi bilo v redu in na tej točki bi lahko temu naredili konec, če ne bi bil naš drugi pogoj: »posledično potrebujemo dokument v določenem formatu, z atributi korporativnega sloga, ustvarjen v skladu z določeno predlogo« (in že na začetku smo se dogovorili, da bo za Gotovo MS Word). To pomeni, da če se odločimo za uporabo Markdown, moramo to datoteko nekako pretvoriti v .docx zahtevane vrste.

Obstajajo programi za pretvorbo med različnimi formati, npr. Pandoc.
S tem programom lahko pretvorite datoteko Markdown v format .docx.
Vendar morate razumeti, da prvič, vse, kar je v Markdownu, ne bo pretvorjeno v MS Word, in drugič, MS Word je cela država v primerjavi z vitkim, a še vedno majhnim mestom Markdown. Ogromno vsega, kar je v Wordu, ni v nobeni obliki v Markdownu. Ne morete kar tako pretvoriti svojega formata Markdown v želeni format MS Word z uporabo določenih tipk Pandoc. Običajno morate po pretvorbi nastali dokument .docx »urediti« ročno, kar je spet lahko zamudno in povzroči napake.

Če bi lahko napisali skript, ki bi samodejno "dokončal" tisto, česar Pandoc ne bi mogel obdelati, bi bila to idealna rešitev.

Zaradi neidentičnosti funkcionalnosti MS Word in Markdown menim, da je tega problema nemogoče rešiti na splošno, toda ali je to mogoče storiti v zvezi s posebnimi situacijami, posebnimi zahtevami? Moje izkušnje so pokazale, da je možno in najverjetneje je možno v mnogih ali morda celo v večini situacij.

Rešitev določenega problema

Torej, v mojem primeru sem po pretvorbi datoteke s Pandocom moral ročno opraviti dodatno obdelavo datoteke, in sicer

• dodajte polja v Word s samodejnim številčenjem naslovov (napisov) tabel in slik
• spremenite slog tabele

Nisem našel, kako to narediti s standardnimi (Pandoc) ali znanimi sredstvi. Zato sem uporabil skript python z pywin32 paket. Posledično sem dobil popolno avtomatizacijo. Zdaj lahko svojo datoteko Markdown z enim ukazom pretvorim v želeno obliko dokumenta MS Word.

Glej podrobnosti tukaj.

Opomba

V tem primeru seveda pretvorim neko abstraktno datoteko Markdown, vendar je bil popolnoma enak pristop uporabljen za "bojni" dokument in rezultat, ki sem ga prejel, je bil skoraj popolnoma enak dokument MS Word, kot smo ga prej prejeli z ročnim oblikovanjem .

Na splošno s pywin32 dobimo skoraj popoln nadzor nad dokumentom MS Word, kar nam omogoča, da ga spremenimo in pripeljemo v obliko, ki jo zahteva vaš korporativni standard. Seveda bi lahko iste cilje dosegli z drugimi orodji, na primer z makri VBA, vendar mi je bilo bolj priročno uporabljati python.

Kratka formula za ta pristop:

Markdown + Git -- (нечто) --> MS Word

Ni pomembno, kaj je "nekaj". V mojem primeru sta bila Pandoc in python s pywin32. Vaše želje so lahko različne, a pomembno je, da je to mogoče. In to je glavno sporočilo tega članka.

Če povzamem, ideja je, da s tem pristopom delate samo z datoteko Markdown in uporabljate Git za sodelovanje in nadzor različic ter samo kadar je to potrebno (na primer, da odjemalcu zagotovite dokumentacijo), samodejno ustvarite datoteko v želeni obliki ( na primer MS Word).

Postopek

Mislim, da za mnoge zgornja formula zadostuje za razumevanje, kako je zdaj mogoče organizirati proces dela z dokumentacijo. A vseeno se ponavadi osredotočim na omrežne inženirje, zato bom na splošno prikazal, kako lahko zdaj izgleda delovni proces in kako se ta razlikuje od pristopa urejanja datotek MS Word.

Natančneje, kot platformo za delo z Gitom bomo izbrali GitHub. Nato bi morali ustvariti repozitorij in datoteko Markdown ali datoteke, s katerimi nameravate delati, postaviti v glavno vejo.

Ogledali si bomo preprost postopek, ki temelji na "github flow". Njegov opis je na voljo tako na internetu kot na habre.

Recimo, da z dokumentacijo delajo štirje ljudje in vi ste eden izmed njih. Nato se ustvarijo štiri dodatne veje, na primer z imeni teh ljudi. Vsak dela lokalno, v svoji poslovalnici in dela spremembe z vsem potrebnim ukazi git.

Ko končate nekaj opravljenega dela, ustvarite zahtevo za vlečenje in s tem sprožite razpravo o svojih spremembah. Morda se med razpravo izkaže, da bi morali še kaj dodati ali spremeniti. V tem primeru naredite potrebne spremembe in ustvarite dodatno zahtevo za vleko. Sčasoma so vaše spremembe sprejete in združene v glavno vejo (ali zavržene).

Seveda je to dokaj splošen opis. Če želite ustvariti podroben postopek, predlagam, da se obrnete na svoje razvijalce ali poiščete dobro obveščene ljudi. Vendar želim opozoriti, da je ovira za vstop v Git precej nizka. To ne pomeni, da je protokol preprost, vendar lahko začnete preprosto. Če sploh ne veste ničesar, mislim, da ga lahko začnete uporabljati, potem ko ste porabili nekaj ur ali morda dni za učenje in namestitev.

Kakšna je prednost tega pristopa v primerjavi z na primer postopkom, opisanim v zgornjem primeru?

Pravzaprav so procesi precej podobni, le zamenjali ste

kopiranje datoteke -> ustvarjanje veje
kopiranje besedila v končno datoteko -> spajanje
kopiranje zadnjih sprememb vase -> git pull/fetch
pogovor v korespondenci -> zahteve po vleki
način sledenja -> git diff
zadnja odobrena različica -> glavna veja
varnostno kopiranje (kopiranje na oddaljeni strežnik) -> git push
...

Tako ste avtomatizirali vse, kar ste že morali narediti, vendar ročno.

Na višji ravni vam omogoča

• ustvarite jasen, preprost in nadzorovan postopek za spremembe dokumentov
• Ker končni dokument (v našem primeru MS Word) ustvarite samodejno, to zmanjša verjetnost napak pri oblikovanju

Opomba

Ob tem mislim, da je očitno, da vam lahko uporaba Gita zelo olajša delo, tudi če delate samo na dokumentaciji.

Vse to izboljša kakovost dokumentacije in skrajša čas za njeno izdelavo. In še en majhen bonus - naučili se boste Git, ki vam bo pomagal pri avtomatizaciji omrežja :)

Kako preklopiti na nov postopek?

Na začetku članka sem napisal, da lahko jutri začnete delati na nov način. Kako svoje delo peljati v novo smer?

Tukaj je zaporedje korakov, ki jih boste najverjetneje morali upoštevati:

• če je vaš dokument zelo velik, ga razdelite na dele
• pretvorite vsak del v Markdown (na primer z uporabo Pandoc)
• namestite enega od urejevalnikov Markdown (uporabljam Typora)
• najverjetneje boste morali prilagoditi oblikovanje ustvarjenih dokumentov Markdown
• začnite uporabljati postopek, opisan v prejšnjem poglavju
• istočasno začnite spreminjati skript za pretvorbo, da bo ustrezal vaši nalogi (ali ustvarite nekaj svojega)

Ni vam treba čakati, dokler ne ustvarite in izpopolnite mehanizma za pretvorbo Markdwon -> zahtevana izhodna vrsta dokumenta. Bistvo je, da tudi če ne morete hitro popolnoma avtomatizirati postopka za pretvorbo datotek Markdown, lahko to še vedno storite v neki obliki z uporabo Pandoc-a in nato ročno pripeljete do končne oblike. Običajno vam tega ni treba početi pogosto, ampak samo na koncu določenih stopenj, in to ročno delo, čeprav neprijetno, je po mojem mnenju še vedno povsem sprejemljivo v fazi odpravljanja napak in ne bi smelo "upočasniti" procesa veliko.

Vse ostalo (Markdown, Git, Pandoc, Typora) je že pripravljeno in ne zahteva veliko truda ali časa za začetek dela z njimi.

Vir: www.habr.com