Kasutage GIT-i dokumenteerimisel

Mõnikord võib mitte ainult dokumentatsioon ise, vaid ka tööprotsess selle kallal olla kriitiline. Näiteks projektide puhul on suur osa tööst seotud just dokumentatsiooni ettevalmistamisega ning vale protsess võib viia vigadeni ja isegi teabe kaotamiseni, seega ka aja ja kasumi kaotamiseni. Kuid isegi kui see teema ei ole teie töös keskne ja asub perifeerias, võib õige protsess siiski parandada dokumendi kvaliteeti ja säästa teie aega.

Siin esitatud lähenemine, koos konkreetse rakenduse näitega,on madala sisenemise tõkete tasemega. Tehniliselt võite juba homme alustada uue lähenemise rakendamist.

Ülesande seadmine

Vajate mingisuguse dokumendi või dokumentide kogumi loomist. See võib olla projektidokumendid või teie võrgu protokollimine, või midagi lihtsamat, näiteks peate kirjeldama protsesse oma ettevõttes või osakonnas. Ühesõnaga, te räägite igasugustest dokumentidest või dokumentide kogumitest, mis sisaldavad teksti, pilte, tabeleid... Teeme ülesande keerukamaks, kuna

1. see töö eeldab koostööd, grupi või mitme grupi töötajate pingutust.
2. Lõpuks tahate, et dokument oleks teatud formaadis, koos ettevõtte stiili atribuutidega ja loodud vastavalt kindlale mallile. Oletame, et see on MS Word (.docx).

10 aastat tagasi oleks lähenemine olnud ühemõtteline: me oleksime loonud MS Wordi dokumendi või dokumendid ja korraldanud töö muudatuste tegemiseks.

Ja see lähenemine kehtib endiselt. Seda kasutavad ka suured integreerijad projektidokumendi koostamisel. Kuid intuitiivselt on selge, et kui te tõeliselt intensiivselt töötate dokumendi kallal suurte muudatuste ja aruteludega pikema aja jooksul, pole see lähenemine just mugav.

Näide

Kogesin seda probleemi teravalt, töötades ühes suures integreerijas. Projektidokumendi muutmise protsess oli järgmine:

1. insener laadib alla viimase versiooni MS Word (.docx) dokumendist,
2. muudab pealkirja,
3. teeb muudatused jälgimismoodulis,
4. saadab dokumendi muudatustega arhitektile,
5. saadab samuti nimekirja kõigist muudatustest koos kommentaaridega.
6. arhitekt analüüsib muudatusi,
7. kui kõik on korras, kopeerib ta muudatused viimase versiooniga, muudab versiooni ja paneb selle avalikku ressurssi.
8. Kui on märkusi, algatatakse arutelu (e-post või koosolekud)
9. Saavutatakse konsensus
10. Edasi liikuda punktide 3–9 juurde

Kuna töö ei olnud intensiivne, töötas see kuidagi, kuid hoolimata sellest, et töö oli keerdne, muutus see siiski ühel hetkel kogu projekti kitsaskohaks ja tõi kaasa probleeme. Asi on selles, et kõik muutub halvaks, kui muudatusi tehakse tihti ja samaaegselt mitme meeskonna poolt.

Nii kui me jõudsime eeltestimise staadiumisse, hakkasid ilmuma erinevad probleemid ja kuigi need olid väikesed, tuli dokumentatsiooni pidevalt muuta — neli erinevat meeskonda, igapäevaselt, praktiliselt samaaegselt, koos aruteludega. Kõik need muudatused läbisid ühe inseneri — arhitekti. Projekti disainifail oli tohutu ja seetõttu oli arhitekt koormatud rutiinse tööga, mis oli seotud suure hulga kopeerimise ja redigeerimisega, tegi palju vigu, pidin kõik üle kontrollima, uuesti saatma ja see oli üldiselt peaaegu kaos.

Antud juhul toimis see lähenemisviis, MS Word dokumendi töötamise lähenemine, suure vaevaga ja põhjustas probleeme.

Git, Markdown

Seistes silmitsi eespool toodud näites kirjeldatud probleemiga, hakkasin seda küsimust uurima.
Nägin, et järjest populaarsemaks muutub Markdown koos Git dokumentide loomisel.

Git on arendustööriist. Aga miks mitte kasutada seda dokumenteerimise protsessis? Sel juhul kaob mitme kasutaja töö küsimus. Kuid Git'i täielike võimete kasutamiseks vajame dokumendi tekstiformaati, peame leidma teise tööriista, mitte MS Word'i ja nende eesmärkide jaoks sobib suurepäraselt Markdown.

Markdown on lihtne tekstiformaatimise keel. See on ette nähtud kaunite tekstide loomiseks tavalistes TXT-vormingus failides. Kui me loome oma dokumendid Markdown'is, siis näeb Markdown - Git ühendus loomulik välja.

Kõik oleks hästi, ja sel kohal võiks punkti panna, kui mitte meie teine tingimus: „me vajame väljundina dokumenti kindlas formaadis, ettevõtte brändinguga, loodud kindla malliga“ (ja me leppisime alguses kokku, et selleks on MS Word). See tähendab, et kui me otsustame kasutada Markdown'i, siis peame kuidagi selle faili vajalikku .docx formaati ümber töötlema.

On olemas erinevate formaatide konversiooniprogrammid, näiteks, Pandoc.
Sa saad konverteerida Markdown faili .docx formaati selle programmi abil.
Kuid ikkagi tuleb aru saada, et esiteks ei konverteerita kõike, mis Markdown'is on, MS Wordi ning teiseks on MS Word hoopis laiem maailm võrreldes kompaktse, kuid siiski väikese Markdowniga. Wordis on üksikkuid funktsioone, mida ei ole Markdownis. Sa ei saa lihtsalt võtta ja teatud võtmete abil Pandoc'iga konverteerida oma Markdown formaati soovitud MS Wordi vormingusse. Seega tuleb tavaliselt pärast konversiooni saadud .docx dokumenti käsitsi „täiendama“, mis jälle võib olla ajakulukas ja viia vigadeni.

Kui me suudaksime kirjutada skripti, mis automaatselt „täiendaks“ seda, millega Pandoc ei suutnud hakkama saada – see oleks ideaalne lahendus.

Kuna MS Wordi ja Markdowni funktsionaalsus ei ole üldiselt identne, arvan, et selle ülesande lahendamine on võimatu, kuid kas on võimalik seda teha antud spetsiifiliste olukordade ja nõudmiste kohaselt? Minu kogemus on näidanud, et jah, see on võimalik ja tõenäoliselt toimub see paljude, või isegi enamikus olukordades.

Kohaliku ülesande lahendus

Nii et minu puhul pidin pärast faili konverteerimist Pandoc'iga käesolevat faili käsitsi edasi töötlema, nimelt

• lisama Wordi automaatse nummerdamise väljad tabelite ja piltide pealkirjade (caption) jaoks
• muutma tabelite stiili

Ma ei leidnud, kuidas seda teha tavaliste (Pandoc) või tuntud vahenditega. Seetõttu rakendasin python skripti koos pywin32 paketiga. Tulemuseks oli täielik automatiseerimine. Nüüd saan konverteerida oma Markdown faili vajaliku MS Wordi dokumendi vormingusse ühe käsuga.

Vaata üksikasju siin.

Note

Selles näites muundan ma muidugi mingit abstraktset Markdown faili, kuid täpselt sama lähenemist on rakendatud ka "töökohustuse" dokumendi puhul, ja lõpptulemusena sain ma peaaegu identsed MS Word dokumendid, mille olime varem käsitsi vormindanud.

Kokkuvõttes annab pywin32 meile praktiliselt täieliku kontrolli MS Word dokumendi üle, mis võimaldab seda muuta ja viia selliseks, nagu teie ettevõtte standard nõuab. Loomulikult oleks sama eesmärki saanud saavutada ka teiste tööriistadega, näiteks VBA makrodega, kuid mulle oli mugavam kasutada Pythonit.

Selle lähenemise lühike valem:

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

Pole nii oluline, mis on see "midagi". Minu puhul olid need 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 selles, et sellise lähenemise korral töötate ainult Markdown failiga ja kasutate Git'i koostöö korraldamiseks ja versioonide haldamiseks, ja ainult vajaduse korral (näiteks kliendile dokumentatsiooni esitamiseks) genereerite automaatselt vajaliku formaadi faili (näiteks MS Word).

Protsess

Arvan, et paljudele on ülaltoodud valem piisav, et mõista, kuidas nüüd võiks dokumentatsiooni protsess korraldatud olla. Kuid siiski suunan end tavaliselt võrguinseneride poole, seega näitan üldiselt, kuidas protsess nüüd välja näeks, ja kuidas see erineb MS Wordi failide redigeerimise lähenemisest.

Selguse huvides valime Git'i töötamiseks GitHub'i platvormi. Siis peate looma repositooriumi ja master haru, kuhu paigutate Markdown faili või failid, millega kavatsete töötada.

Käsitleme lihtsat protsessi, mis põhineb "github flow"'l. Selle kirjelduse leiate nii internetist kui ka Habrast.

Eeldame, et dokumentatsiooni kallal töötab neli inimest ja olete üks neist. Selle tulemusena luuakse neli täiendavat haru (branch), näiteks nende inimeste nimedega. Igaüks töötab kohalikult, oma harus ja teeb muudatusi kõigi vajalike git käskude abil..

Töötades ühe lõppenud projekti kallal, loote te pull request'i, käivitades sellega arutelu teie muudatuste üle. Arutelu käigus võib selguda, et peate midagi lisama või muutma. Sel juhul teete vajalikke muudatusi ja loote täiendava pull request'i. Lõpuks võetakse teie muudatused vastu ja need liidetakse (merge) master haruga (või lükatakse tagasi).

Loomulikult on see üsna üldine kirjeldus. Et luua detailne protsess, soovitan pöörduda oma arendajate poole või otsida teadlikke inimesi. Kuid tahan märkida, et Git'i kasutamiskünnis on üsna madal. See ei tähenda, et protokoll oleks lihtne, kuid saate alustada millegi lihtsaga. Kui te ei tea sellest üldse midagi, siis arvan, et kulutades paar tundi või võib-olla päevi õppimisele ja seadistamisele, võite hakata seda kasutama.

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

Tegelikult on protsessid üsna sarnased, te olete lihtsalt asendanud

faili kopeerimine -> haru (branch) loomine
teksti kopeerimine lõppfaili -> liitmine (merge)
uusimate muudatuste kopeerimine enda juurde -> git pull/fetch
arutelu kirjavahetuses -> pull request'id
track mode -> git diff
viimane kinnitatud versioon -> master haru
varundamine (kopeerimine kaugserverisse) -> git push
…

Nii olete automatiseerinud kõik selle, mida pidite käsitsi tegema.

Kõrgemal tasemel võimaldab see teil

• luua selge, lihtsa ja kontrollitava muudatuste protsessi dokumentatsioonis
• kuna lõppdokument (meie näites MS Word) luuakse automaatselt, vähendab see vormindamisega seotud vigade tõenäosust

Note

Eeltoodust tulenevalt on ilmne, et isegi kui töötate dokumentatsiooniga üksi, võib Git'i kasutamine teie tööd oluliselt lihtsustada.

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

Kuidas üleminek uuele protsessile?

Artikli alguses kirjutasin, et juba homme võite hakata uut moodi tööle. Kuidas viia oma töö uude suunda?

Siin on sammude järjestus, mida peate tõenäoliselt järgima:

• kui teie dokument on väga suur, jagage see osadeks
• muutke iga osa Markdowniks (näiteks Pandoci abil)
• installige mõni Markdown toimetaja (mina kasutan Typora)
• tõenäoliselt peate kohandama loodud Markdown dokumentide vormindust
• hakake rakendama protsessi, mida on kirjeldatud eelnevas peatükis
• samal ajal hakake kohandama konversiooniskripti oma ülesande jaoks (või looge midagi oma)

Te ei pea ootama, kuni olete loonud ja täiuslikuks viimistlenud Markdown -> soovitud dokumendi vormingusse konverteerimise mehhanismi. Fakt on see, et isegi kui te ei suuda kiiresti täiuslikult automatiseerida oma Markdowni failide teisendamise protseduuri, on teil ikka võimalik seda mingil kujul teha Pandoci abil ja seejärel viia see lõppvormi käsitsi. Tavaliselt ei pea te seda sageli tegema, vaid ainult teatud etappide lõpus, ja see käsitsi töö, kuigi ebamugav, on siiski minu arvates täiesti aktsepteeritav tõrgete parandamise etapil ega tohiks protsessi oluliselt „pidurdada“.

Kõik muu (Markdown, Git, Pandoc, Typora) on juba valmis ja ei vaja erilisi pingutusi või aega, et alustada nende kasutamist.

Allikas: habr.com