Kasutage GIT-i dokumenteerimisel

Mõnikord võib mitte ainult dokumentatsioon ise, vaid ka selle koostamise protsess olla kriitilise tähtsusega. Näiteks projektide puhul on suur osa tööst seotud dokumentatsiooni ettevalmistamisega ning vale protsess võib viia vigadeni ja isegi teabe kaotamiseni, mis omakorda põhjustab ajakulu ja kahjumit. Kuid isegi kui see teema ei ole teie töös keskne ja jääb perifeeriasse, võib õige protsess siiski parandada dokumendi kvaliteeti ja säästa aega.

Toodud lähenemine, konkreetse rakenduse näitega, on madala sisenemisbarjääriga. Tehniliselt võite juba homme alustada uut lähenemist.

Ülesande seadmine

Teil on vaja luua mingi dokument või dokumentide kogum. Olgu see projektidokumentatsioon või teie võrgu protokollimine, või midagi lihtsamat, näiteks peate kirjeldama ettevõtte või teie osakonna protsesse. Kokkuvõttes räägime igasugustest dokumentidest või dokumentide kogumist, kus on tekst, pildid, tabelid... Teeme ülesande keerulisemaks, et

1. see töö eeldab koostööd, grupi või mitme töötajate rühma pingutusi.
2. väljatulev dokument peab olema teatud vormingus, ettevõtte stiili atribuudi siin, loodud teatud šablooni järgi. Täpsuse huvides oletame, et see on MS Word (.docx)

10 aastat tagasi oleks lähenemine olnud üheselt mõistetav: oleksime loonud MS Wordi dokumendi või dokumendid ja korraldanud muudatusetööd mingil viisil.

Ja see lähenemine kehtib endiselt. Seda kasutavad ka suured integratsiooniettevõtted projektidokumendi loomisel. Kuid intuitiivselt on selge, et kui töötab tõeliselt intensiivselt, paljude muudatuste ja aruteludega, pika aja jooksul dokumendi kallal, ei ole see lähenemine väga mugav.

Näide

Otsisin seda probleemi teravalt, töötades ühe suure integratoriga. Projektidokumentide muutmise protsess oli järgmine:

1. insener allalaadib viimase versiooni MS Word (.docx) dokumendist
2. muudab pealkirja
3. teeb muudatused track-režiimis
4. saadab redigeeritud dokumendi arhitektile
5. saadab ka kõigi muudatuste loetelu kommentaaridega
6. arhitekt analüüsib muudatusi
7. kui kõik on korras, siis kopeerib see andmete muutused viimase versiooniga faili, muudab versiooni ja avaldab selle ühisesse ressurssi
8. kui on märkusi, algatatakse arutelu (e-kiri või kohtumised)
9. saavutatakse konsensus
10. järgmiseks punktid 3–9

Kuigi töö ei olnud intensiivne, toimis see kuidagi, aga ikkagi töötas. Kuid teatud hetkel sai see protsess kogu projekti kitsaskohaks ja põhjustas probleeme. Asi on selles, et kõik läheb kehvasti, kui muudatusi tehakse tihti ja samal ajal mitme meeskonna poolt.

Nii, kui me läksime ettevalmistustestimise faasi, hakkasid ilmuma erinevad probleemid ja kuigi need olid väikesed, tuli dokumentatsiooni sageli muuta - neli erinevat meeskonda, iga päev, praktiliselt samal ajal, aruteludega. Kõik need muudatused läbisid ühe inseneri - arhitekti. Projekti disainifail oli tohutu ja seega oli arhitekt koormatud rutiinse tööga, mis oli seotud suure hulga kopeerimise ja redigeerimisega, tegi palju vigu, tuli kõik uuesti kontrollida, ümber saata, ja üldiselt oli see lähedal kaoseni.

Selles olukorras töötas MS Wordi dokumentide töötlemise lähenemine suure skripti ja probleemide loomisega.

Git, Markdown

Silmunes eespool kirjeldatud probleemiga, hakkasin seda teemat uurima.
Olen märganud, et üha populaarsemaks on muutumas Markdown koos Git dokumentide loomisel.

Git on arendusvahend. Kuid miks mitte kasutada seda dokumentide koostamise protsessis? Sellisel juhul on mitme kasutaja töö küsimus lahendatud. Kuid et Git'i võimalusi täielikult ära kasutada, vajame dokumendi tekstivormingut ning peame leidma teise tööriista, mitte MS Wordi, ja selleks sobib suurepäraselt Markdown.

Markdown on lihtne tekstiformaadimise keel. See on mõeldud kaunis vormindatud tekstide loomiseks tavapärastes TXT-formaadiga failides. Kui loome meie dokumendid Markdownis, siis tundub Markdown — Git ühendus loomulik.

Ja kõik oleks hästi, ja just siin võiks punkti panna, kui mitte meie teine tingimus: „me vajame väljundina dokumenti kindlas formaadis, ettevõtte stiili atribuutidega, mis on loodud kindla malliga“ (ning me leppisime alguses kokku, et selleks on MS Word). Seega, kui oleme otsustanud kasutada Markdown'i, peame oma faili kuidagi teisendama soovitud .docx formaati.

On olemas konversiooniprogramme erinevate formaatide vahel, näiteks, Pandoc.
Saate konverteerida Markdown faili .docx formaati selle programmiga.
Kuid siiski, tuleb mõista, et, esiteks, mitte kõik, mis on Markdown'is, ei konverteeru MS Wordi ning, teiseks, MS Word on terviklik riik võrreldes kompaktse, kuid siiski väikese linnaga, Markdown. Wordis on tohutult palju funktsioone, mida Markdown'is ei ole. Ei saa lihtsalt võtta ja teatud Pandoc'i võtit kasutades konverteerida oma Markdown formaati soovitud MS Word'i kuvandisse. Seetõttu tuleb tavaliselt pärast konversiooni saadud .docx dokumenti käsitsi "täiendama", mis omakorda võib olla ajakulukas ja viia vigadeni.

Kui me suudaksime kirjutada skripti, mis automaatselt «täiendaks» seda, millega Pandoc hakkama ei saa — see oleks ideaalne lahendus.

Tänu MS Wordi ja Markdowni funktsioonide erinevustele üldiselt on selle probleemi lahendamine minu arvates võimatu, kuid kas on võimalik seda konkreetsete olukordade, spetsiifiliste nõudmiste alusel teha? Minu kogemus on näidanud, et jah, see on võimalik ja tõenäoliselt sobib see paljudele, võib-olla isegi enamikule olukordadele.

Spetsiifilise ülesande lahendus

Nii et minu puhul, pärast faili konversiooni Pandoci abil, pidin ma käsitsi tegema täiendavat töötlemist, nimelt

• lisama Wordis automaatse numeerimisega pealkirjade (caption) väljad tabelitele ja piltidele
• muutma tabelite stiili

Ma ei leidnud, kuidas seda teha standardsete (Pandoc) või tuntud vahendite abil. Seetõttu kasutasin python skripti koos pywin32 paketiga. Tulemuseks oli täielik automatiseerimine. Nüüd võin konverteerida oma Markdown faili soovitud MS Word dokumendi vormingusse ühe käsuga.

Vaadake detaile siit.

Märkus

Selles näites muudan ma kindlasti mingit abstraktset Markdown faili, kuid täpselt sama lähenemist on rakendatud ka «töödokumentidele», ja tulemuseks sain ma praktiliselt täpselt sama MS Wordi dokumendi, mille olime eelnevalt saanud käsitsi vormindamisega.

Üldiselt saame pywin32 abil praktiliselt täieliku kontrolli MS Wordi dokumendi üle, mis võimaldab seda muuta ja viia vastavusse teie ettevõtte standarditega. Loomulikult on sama eesmärgiga saanud hakkama ka teiste tööriistade, näiteks VBA makrode, kasutamine, kuid mulle oli mugavam kasutada Pythonit.

Selle lähenemise lühike valem:

Markdown + Git -- (midagi) --> MS Word

Ei ole nii oluline, millega on tegu «millegagi». Minu puhul oli see Pandoc ja Python koos pywin32-ga. Võib-olla on teil teised eelistused, kuid oluline on, et see on võimalik. Ja see ongi selle artikli peamine sõnum.

Kokkuvõttes on idee, et sellise lähenemisega töötate te ainult Markdown failiga ja kasutate Git'i koostöö korraldamiseks ja versioonide kontrollimiseks, ning ainult vajadusel (näiteks dokumentatsiooni kliendile esitamiseks) genereerite automaatselt soovitud formaadis faili (näiteks MS Wordi).

Protsess

Arvan, et paljudele on ülaltoodud valem piisav, et mõista, kuidas nüüd saab dokumentatsiooniga töötamise protsess korraldatud. Siiski orienteerun tavaliselt võrguinseneridele, seega näitan lühidalt, kuidas võib nüüd tööprotsess välja näha ja milles see erineb MS Wordi failide redigeerimise lähenemisest.

Selguse huvides valime Giti töötamiseks platvormiks GitHubi. Siis peate looma repository ja master harusse panema Markdown faili või faile, millega kavatsete töötada.

Kuidas näeb välja lihtne protsess, mis põhineb «github flow’il». Selle kirjeldust võib leida nii internetist kui ka Habrast..

Oletame, et dokumentatsiooni kallal töötab neli inimest ja teie olete üks neist. Siis luuakse neli täiendavat harusid (branch), näiteks nende inimeste nimede põhjal. Igaüks töötab kohapeal, oma harus ja teeb muudatuseid kõigi vajalike git käskudega..

Töötades mõne konkreetse ülesande kallal, lood te pull request'i, mis alustab teie muudatuste arutelu. Arutelu käigus võib selguda, et peate lisama või muutma midagi veel. Sellisel juhul teete vajalikud muudatused ja loote uue pull request'i. Lõpuks teie muudatused aktsepteeritakse ja ühendatakse (merge) master haruga (või need lükatakse tagasi).

Muidugi, see on üsna üldine kirjeldus. Soovitan, et loote detailse protsessi koostamiseks pöörduda oma arendajate poole või leida asjatundlikke inimesi. Pean siiski märkima, et Git'i õppimiskünnis on üsna madal. See ei tähenda, et protokoll oleks lihtne, kuid võite alustada lihtsast. Kui te ei tea sellest üldse midagi, siis arvan, et paari tunni või võib-olla päeva jooksul õppimise ja seadistamisega saate hakata seda kasutama.

Milline on selle lähenemise eelis võrreldes näiteks ülaltoodud näite protsessiga?

Tegelikult on protsessid üsna sarnased, lihtsalt olete asendanud

faili kopeerimise -> haru (branch) loomisega
teksti kopeerimise sihtfaili -> ühendamisega (merge)
viimaste muudatuste kopeerimine enda juurde -> git pull/fetch
arutelu vestluses -> pull requests
jälgimisrežiim -> git diff
viimane kinnitatud versioon -> master haru
varukoopia (kopeerimine kaugserverisse) -> git push
…

Nii olete automatiseerinud kõik selle, mida pidite varem manuaalselt tegema.

Kõrgemal tasemel võimaldab see teil

• luua selge, lihtne ja kontrollitav muudatuste protsess dokumentatsioonis
• kuna lõplik dokument (meie näites MS Word) luuakse automaatselt, vähendab see vormindamisvigade tõenäosust

Märkus

Seega on ilmselge, et isegi kui töötate dokumentatsiooniga üksi, võib Git oluliselt teie tööd lihtsustada

Kõik see tõstab dokumentatsiooni kvaliteeti ja vähendab selle loomise aega. Ja veel üks väike boonus — õpite Git'i, mis aitab teil oma võrgu automatiseerimisel 🙂

Kuidas minna üle uue protsessi juurde?

Artikli alguses ütlesin, et juba homme saate alustada uue töötamise viisiga. Kuidas viia oma töö uude suunda?

Siin on samm-sammult juhis, mille tõenäoliselt peate läbi viima:

• kui teie dokument on väga suur, jagage see osadeks
• konverteerige iga osa Markdowni (nt Pandoci abil)
• paigaldage üks Markdowni redaktoritest (mina kasutan Typora)
• on tõenäoliselt vajalik kohandada loodud Markdown dokumentide vormindust
• hakake järgima eelnevas peatükis kirjeldatud protsessi
• samuti hakkake kohandama konversiooniskeemi oma vajadustele (või looge midagi uut)

Te ei pea ootama, kuni loote ja silutate täielikult automatiseeritud Markdown -> soovitud dokumendi vormingu. Isegi kui te ei suuda kiiresti täielikult automatiseerida oma Markdowni failide konverteerimise protseduuri, on teil endiselt võimalik seda mingil kujul teha Pandoci abil ja seejärel käsitsi lõpule viia. Tavaliselt ei pea te seda tihti tegema, vaid vaid teatud etappide lõpus, ja see käsitöö, ehkki ebamugav, on minu arvates täiesti talutav silumise etapis ja ei peaks oluliselt „pidurdama” protsessi.

Kõik muu (Markdown, Git, Pandoc, Typora) on juba valmis ja ei vaja erilisi jõupingutusi ega aega, et nendega alustada.

Allikas: habr.com