🥇Použite GIT pri dokumentovaní

Niekedy nie je kritická len samotná dokumentácia, ale aj proces práce na nej. Napríklad v prípade projektov sa veľká časť práce spája práve s prípravou dokumentácie, a nesprávny proces môže viesť k chybám a dokonca k strate informácií, čo znamená aj stratu času a zisku. Ale aj keď táto téma nie je centrálnou súčasťou vašej práce a nachádza sa na periférii, správny proces môže zlepšiť kvalitu dokumentu a ušetriť vám čas.

Prístup opísaný tu, s príkladom konkrétnej implementácie, má nízky prah vstupu. Technicky môžete už zajtra začať pracovať inak.

Stanovenie úlohy

Musíte vytvoriť nejaký dokument alebo sadu dokumentov. Možno ide o projektovú dokumentáciu alebo protokolovanie vašej siete, alebo niečo jednoduchšie, napríklad by ste mali popísať procesy vo firme alebo vo vašom oddelení. V podstate ide o akýkoľvek dokument alebo sadu dokumentov s textom, obrázkami, tabuľkami... Urobme úlohu zložitejšou tým, že

táto práca predpokladá spoločnú prácu, úsilie skupiny alebo viacerých skupín zamestnancov
a na konci chcete mať dokument v konkrétnom formáte, s atribútmi firemného štýlu, vytvorený podľa konkrétnej šablóny. Pre istotu predpokladajme, že ide o MS Word (.docx)

Pred 10 rokmi by bol prístup jednoznačný: vytvorili by sme MS Word dokument alebo dokumenty a nejako by sme zorganizovali prácu na ich úpravách.

A tento prístup stále platí. Používajú ho aj veľkí integrátori pri vytváraní projektovej dokumentácie. Ale intuitívne je jasné, že ak skutočne intenzívne, s množstvom úprav a diskusií, pracujete na dokumente dlhý čas, tento prístup nie je veľmi pohodlný.

Príklad
Túto problémovú situáciu som dosť ostro cítil, keď som pracoval v jednom veľkom integrátorovi. Proces úpravy projektovej dokumentácie bol nasledujúci:

inžinier si stiahne poslednú verziu dokumentu MS Word (.docx)

zmení názov

upravuje zmeny v režime sledovania

posiela dokument s úpravami architektovi

takisto posiela zoznam všetkých opráv s komentármi

architekt analyzuje zmeny

ak je všetko v poriadku, skopíruje tieto zmeny do súboru s poslednou verziou, zmení verziu a nahrá na spoločný zdroj

ak sú nejaké pripomienky, vyvolá sa diskusia (e-mail alebo stretnutia)

dosiahne sa konsenzus

ďalej body 3 – 9
Keď práca nebola intenzívna, tak to nejak fungovalo. Ale nakoniec sa tento proces stal úzkym miestom celého projektu a spôsobil problémy. Problém je v tom, že sa všetko zhoršuje, keď sa zmeny uskutočňujú často a súčasne viacerými tímami.
Keď sme prešli do fázy predbežného testovania, začali sa objavovať rôzne problémy a hoci to boli maličkosti, bolo potrebné často meniť dokumentáciu — štyri rôzne tímy, denne, takmer súčasne, s diskusiami. Všetky tieto zmeny prechádzali cez jedného inžiniera — architekta. Súbor s dizajnom projektu bol obrovský a následne bol architekt zavalený rutinou spojenou s veľkým množstvom kopírovania, editovania, robil veľa chýb, muselo sa všetko prekontrolovať, preposlať, a vôbec to bolo blízko chaosu.
V tomto prípade tento prístup, prístup práce s dokumentom MS Word, fungoval s veľkým námahou a vytváral problémy.

Git, Markdown

Keď som sa stretol s problémom opísaným v predchádzajúcom príklade, začal som skúmať túto tému.
Zistil som, že stále viac rastie popularita používania Markdown spoločne s Git pri vytváraní dokumentov.

Git je nástroj pre vývoj. Ale prečo ho nevyužiť aj na proces dokumentovania? V tomto prípade je otázka viacnásobného používania vyriešená. Aby sme však mohli plne využiť možnosti Git, potrebujeme textový formát dokumentu, musíme nájsť iný nástroj, nie MS Word, a na tieto účely je Markdown skvelou voľbou.

Markdown je jednoduchý jazyk textového značkovania. Je určený na vytváranie krásne naformátovaných textov v normálnych TXT súboroch. Ak budeme vytvárať naše dokumenty v Markdown, bude spojenie Markdown – Git vyzerať prirodzene.

A všetko by bolo v poriadku, a v tomto bode by sa dalo urobiť bodka, akoby nebolo nášho druhého požiadavku: „na výstupe potrebujeme dokument v určitej forme, s atribútmi firemného štýlu, vytvorený podľa určitého šablónu“ (a dohodli sme sa na začiatku, že pre jasnosť to bude MS Word). To znamená, ak sme sa rozhodli použiť Markdown, musíme nejakým spôsobom previesť tento súbor na .docx požadovanej podoby.

Existujú programy na konverziu medzi rôznymi formátmi, napríklad, Pandoc.
Môžete previesť Markdown súbor do .docx formátu pomocou tejto aplikácie.
Ale predsa len, treba chápať, že po prvé, nie všetko, čo existuje v Markdown bude prevedené do MS Word a po druhé, MS Word je celá krajina v porovnaní so štíhlym, ale predsa len mestečkom, Markdown. Existuje obrovské množstvo niečoho, čo je v Word a v žiadnej podobe nie je v Markdown. Nemôžete len tak vziať a s určitými kľúčmi Pandoc previesť váš Markdown formát do želanej podoby MS Word. Takže zvyčajne, po konverzii, je potrebné „dopracovať“ získaný .docx dokument ručne, čo opäť môže byť nákladné z pohľadu času a môže viesť k chybám.

Keby sme mohli napísať skript, ktorý automaticky „dopracoval“ to, s čím si neporadil Pandoc – to by bolo ideálne riešenie.

Vzhľadom na to, že funkčnosť MS Word a Markdown nie je v celku identická, myslím, že vyriešiť túto úlohu je nemožné, ale je možné to dosiahnuť v súvislosti s konkrétnymi situáciami, konkrétnymi požiadavkami? Moje skúsenosti ukázali, že áno, dá sa to a pravdepodobne je to možné pre mnohé, alebo možno aj väčšinu situácií.

Riešenie špecifickej úlohy

Takže, v mojom prípade, po konverzii súboru pomocou Pandoc, som musel ručne robiť dodatočnú úpravu súborov, a to konkrétne

pridávať v Worde polia s automatickým číslovaním nadpisov (caption) tabuliek a obrázkov
mieniť štýl pre tabuľky

Nenašiel som, ako to urobiť pomocou štandardných (Pandoc) alebo známych prostriedkov. Preto som použil python skript s pywin32 balíkom. V dôsledku toho som dosiahol úplnú automatizáciu. Teraz môžem previesť môj Markdown súbor do požadovanej podoby MS Word dokumentu jednou príkazom.

Pozrite si detaily tu.

Poznámka
V tomto prípade samozrejme transformujem akýsi abstraktný Markdown súbor, ale presne ten istý prístup bol aplikovaný aj na "pracovný" dokument, a na výstupe som získal takmer presne ten istý dokument MS Word, ktorý sme predtým dostávali ručným formátovaním.

V zásade s pywin32 získavame takmer úplnú kontrolu nad dokumentom MS Word, čo umožňuje jeho úpravu a prispôsobenie vzhľadu, aký vyžaduje váš firemný štandard. Samozrejme, týchto cieľov by sa dalo dosiahnuť aj s použitím iných nástrojov, ako sú napríklad VBA makrá, ale mne sa pohodlnejšie pracovalo s python.

Stručná formula tohto prístupu:

Markdown + Git -- (niečo) --> MS Word

Nie je tak dôležité, čo je "niečo". V mojom prípade to bol Pandoc a python s pywin32. Možno máte iné preferencie, ale dôležité je, že to je možné. A to je hlavný odkaz tohto článku.

V skratke, myšlienka spočíva v tom, že pri takomto prístupe pracujete len s Markdown súborom a využívate Git na organizovanie tímovej práce a kontrolu verzií, a len v prípade potreby (napríklad na poskytnutie dokumentácie klientovi) automaticky vytvárate súbor požadovaného formátu (napríklad MS Word).

Proces

Myslím, že pre mnohých je vzorec uvedený vyššie dostatočný na to, aby pochopili, ako môže byť organizovaný proces práce s dokumentáciou. Ale predsa len sa obvykle zameriavam na sieťových inžinierov, takže v obrysoch ukážem, ako by mohol teraz vyzerať proces práce a čím sa líši od prístupu s úpravou súborov MS Word.

Pre jednoznačnosť, ako platformu na prácu s Git vyberme GitHub. Potom by ste mali vytvoriť repozitár a v master vetve umiestniť Markdown súbor alebo súbory, s ktorými plánujete pracovať.

Preskúmame jednoduchý proces založený na „github flow“. Jeho popis môžete nájsť ako v internete, tak aj na habre..

Predpokladajme, že na dokumentácii pracujú štyria ľudia a vy ste jedným z nich. Potom sa vytvárajú štyri ďalšie vetvy (branch), napríklad s menami týchto ľudí. Každý pracuje lokálne vo svojich vetvách a robí zmeny so všetkými potrebnými git príkazmi..

Keď vykonáte nejaký uzavretý kus práce, vytvoríte pull request, čím iniciujete diskusiu o vašich zmenách. Počas diskusie sa možno zistí, že musíte pridať alebo zmeniť niečo ďalšie. V tom prípade vykonáte potrebné úpravy a vytvoríte ďalší pull request. Nakoniec budú vaše zmeny prijaté a zlúčené (merge) s hlavným vetvením (master) (alebo zamietnuté).

Samozrejme, toto je dosť všeobecný opis. Navrhujem pre vytvorenie podrobného procesu osloviť vašich vývojárov alebo nájsť znalcov. Ale chcem poznamenať, že prah vstupu do Git je dosť nízky. To neznamená, že protokol je jednoduchý, ale môžete začať s niečím jednoduchým. Ak vôbec nič neviete, myslím, že s niekoľkými hodinami alebo možno dňami štúdia a inštalácie môžete začať ho používať.

Aký prínos má tento prístup v porovnaní napríklad s procesom opísaným v predchádzajúcom príklade?

V skutočnosti sú procesy dosť podobné, jednoducho ste nahradili

kopírovanie súboru -> vytvorenie vetvy (branch)
kopírovanie textu do konečného súboru -> zlúčenie (merge)
kopírovanie posledných zmien na seba -> git pull/fetch
diskusia v korešpondencii -> pull requests
track mode -> git diff
posledná schválená verzia -> master vetva
zálohovanie (kopírovanie na vzdialený server) -> git push
…

Týmto spôsobom ste automatizovali všetko to, čo ste museli robiť ručne.

Na vyššej úrovni vám to umožňuje

vytvoriť jasný, jednoduchý a kontrolovateľný proces zmien dokumentácie
keďže konečný dokument (v našom príklade MS Word) vytvárate automaticky, znižuje to pravdepodobnosť chýb spojených so formátovaním.

Poznámka
Vzhľadom na vyššie uvedené si myslím, že je jasné, že aj keď pracujete na dokumentácii sám, používanie Git vám môže zásadne uľahčiť prácu.

To všetko zvyšuje kvalitu dokumentácie a skracuje čas potrebný na jej vytvorenie. A ešte malý bonus — naučíte sa Git, čo vám pomôže pri automatizácii vašej siete 🙂

Ako prejsť na nový proces?

Na začiatku článku som napísal, že už zajtra môžete začať pracovať novým spôsobom. Ako previesť vašu prácu do nového smeru?

Tu je sekvencia krokov, ktorú pravdepodobne budete musieť vykonať:

ak je váš dokument veľmi veľký, rozdeľte ho na časti
konvertujte každú časť do Markdownu (napríklad pomocou Pandoc)
nainštalujte jeden z editorov Markdownu (ja používam Typora)
pravdepodobne bude potrebné upraviť formátovanie vytvorených Markdown dokumentov
začnite aplikovať proces popísaný v predchádzajúcej kapitole
súbežne začnite prispôsobovať skript konverzie na svoju úlohu (alebo vytvorte niečo vlastné)

Nemusíte čakať, kým sa vám podarí vytvoriť a doladiť mechanizmus konverzie Markdown -> požadovaný výstupný formát dokumentu. Faktom je, že aj keď sa vám nepodarí rýchlo úplne automatizovať postup transformácie vašich Markdown súborov, aj tak to môžete urobiť nejako pomocou Pandoc a neskôr to manuálne dopracovať do konečného formátu. Zvyčajne to nemusíte robiť často, len na konci určitých fáz, a táto ručná práca, aj keď je nepríjemná, je podľa mňa celkom prijateľná v fáze ladenia a nemala by výrazne "spomaliť" proces.

Všetko ostatné (Markdown, Git, Pandoc, Typora) je už pripravené a nevyžaduje osobitné úsilie alebo čas na to, aby ste s nimi začali pracovať.

Zdroj: habr.com