Pri dokumentovaní používajte GIT

Niekedy môže byť kritická nielen samotná dokumentácia, ale aj proces práce na nej. Napríklad pri projektoch je leví podiel práce spojený s prípravou dokumentácie a nesprávny postup môže viesť k chybám až strate informácií, a tým aj strate času a výhod. Ale aj keď táto téma nie je ústrednou témou vašej práce a je na okraji, správny proces môže stále zlepšiť kvalitu dokumentu a ušetriť vám čas.

Tu načrtnutý prístup s príklad konkrétnej implementácie, má nízku vstupnú bariéru. Technicky, zajtra môžete začať pracovať novým spôsobom.

Vyhlásenie o probléme

Musíte vytvoriť dokument alebo súbor dokumentov. Možno je to projektová dokumentácia alebo logovanie vašej siete, alebo niečo jednoduchšie, napríklad musíte popísať procesy vo firme alebo vo vašom oddelení. Vo všeobecnosti hovoríme o akomkoľvek dokumente alebo súbore dokumentov s textom, obrázkami, znakmi... Skomplikujme si úlohu tým, že

1. táto práca zahŕňa spoločnú prácu, úsilie skupiny alebo viacerých skupín zamestnancov
2. V dôsledku toho chcete mať dokument v určitom formáte s atribútmi firemného štýlu vytvorený podľa určitej šablóny. Aby sme boli konkrétni, budeme predpokladať, že ide o MS Word (.docx)

Pred 10 rokmi by bol prístup jednoduchý: vytvorili by sme dokument alebo dokumenty MS Word a nejakým spôsobom zorganizovali prácu na zmenách.

A tento prístup stále platí. Využívajú ho aj veľkí integrátori pri tvorbe projektovej dokumentácie. Je však intuitívne jasné, že ak na dokumente skutočne intenzívne pracujete, s mnohými úpravami a diskusiami, počas dlhého obdobia, tento prístup nie je príliš vhodný.

Príklad

Tento problém som dosť akútne pocítil pri práci pre veľkého integrátora. Proces zmeny projektovej dokumentácie bol nasledovný:

1. inžinier stiahne najnovšiu verziu dokumentu MS Word (.docx).
2. zmení meno
3. robí zmeny na sledovanie módy
4. odošle dokument s úpravami architektovi
5. posiela aj zoznam všetkých opráv s komentármi
6. architekt analyzuje zmeny
7. ak je všetko v poriadku, skopíruje tieto zmeny do súboru s najnovšou verziou, zmení verziu a nahrá ju do zdieľaného zdroja
8. ak sú pripomienky, začne sa diskusia (e-mail alebo stretnutia)
9. sa dosiahne konsenzus
10. ďalšie body 3-9

Práca síce nebola intenzívna, nejako bola, ale stále fungovala. No v určitom bode sa tento proces stal prekážkou celého projektu a viedol k problémom. Ide o to, že veci sa zhoršia, akonáhle zmeny vykonáva často a súčasne niekoľko tímov.

Takže, keď sme prešli do fázy predbežného testovania, začali sa objavovať rôzne problémy a aj keď v malých ohľadoch, bolo potrebné často meniť dokumentáciu – štyri rôzne tímy, každý deň, takmer súčasne, s diskusiami. Všetky tieto zmeny prebehli prostredníctvom jedného inžiniera – architekta. Súbor návrhu projektu bol obrovský a v dôsledku toho bol architekt zavalený rutinnou prácou, ktorá zahŕňala veľa kopírovania, úprav, robil veľa chýb, všetko musel dvakrát kontrolovať, znova posielať a vo všeobecnosti to bolo blízko chaos.

V tomto prípade tento prístup, prístup práce na dokumente MS Word, fungoval s veľkými ťažkosťami a vytváral problémy.

Git, Markdown

Tvárou v tvár problému opísanému v príklade vyššie som začal skúmať tento problém.
Videl som, že použitie Markdown spolu s ísť pri vytváraní dokumentov.

Git je vývojový nástroj. Ale prečo to nevyužiť na dokumentačný proces? V tomto prípade sa problém práce viacerých používateľov vyrieši. Aby sme však mohli naplno využiť možnosti Gitu, potrebujeme formát textového dokumentu, musíme nájsť iný nástroj ako MS Word a Markdown je na tieto účely skvelý.

Markdown je jednoduchý textový značkovací jazyk. Je navrhnutý tak, aby vytváral krásne navrhnuté texty v bežných súboroch TXT. Ak vytvárame naše dokumenty v Markdown, potom kombinácia Markdown - Git vyzerá prirodzene.

A všetko by bolo v poriadku a v tomto bode by sme tomu mohli urobiť koniec, nebyť našej druhej podmienky: „v dôsledku toho potrebujeme dokument v určitom formáte, s atribútmi firemného štýlu, vytvorený podľa určitá šablóna“ (a na začiatku sme sa zhodli, že pre Určite to bude MS Word). To znamená, že ak sa rozhodneme použiť Markdown, musíme tento súbor nejako previesť na .docx požadovaného typu.

Existujú programy na konverziu medzi rôznymi formátmi, napr. Pandoc.
Pomocou tohto programu môžete previesť súbor Markdown do formátu .docx.
Stále však musíte pochopiť, že po prvé, nie všetko, čo je v Markdowne, sa prevedie na MS Word a po druhé, MS Word je celá krajina v porovnaní so štíhlym, ale stále malým mestom Markdown. Existuje obrovské množstvo všetkého, čo je vo Worde, čo nie je v žiadnej forme v Markdown. Nemôžete jednoducho pokračovať a previesť svoj formát Markdown do požadovaného formátu MS Word pomocou určitých klávesov Pandoc. Po konverzii teda zvyčajne musíte výsledný .docx dokument „upraviť“ ručne, čo môže byť opäť časovo náročné a viesť k chybám.

Ak by sme dokázali napísať skript, ktorý by automaticky „dokončil“ to, čo Pandoc nezvládol, bolo by to ideálne riešenie.

Vzhľadom na neidentitu funkčnosti MS Word a Markdown je podľa mňa nemožné vyriešiť tento problém všeobecne, ale dá sa to urobiť vo vzťahu ku konkrétnym situáciám, konkrétnym požiadavkám? Moja skúsenosť ukázala, že áno, je to možné a s najväčšou pravdepodobnosťou je to možné pre mnohé, alebo možno dokonca pre väčšinu situácií.

Riešenie konkrétneho problému

Takže v mojom prípade som po konverzii súboru pomocou Pandoc musel manuálne vykonať ďalšie spracovanie súboru, a to

• pridať polia do Wordu s automatickým číslovaním nadpisov (titulkov) tabuliek a obrázkov
• zmeniť štýl tabuľky

Nenašiel som, ako to urobiť pomocou štandardných (Pandoc) alebo známych prostriedkov. Použil som teda skript python s pywin32 balík. V dôsledku toho som dostal plnú automatizáciu. Teraz môžem previesť svoj súbor Markdown do požadovaného formátu dokumentu MS Word pomocou jedného príkazu.

Pozri detaily tu.

poznámka

V tomto príklade, samozrejme, konvertujem nejaký abstraktný súbor Markdown, ale presne ten istý prístup bol aplikovaný na „bojový“ dokument a výstup, ktorý som dostal, bol takmer presne ten istý dokument MS Word, aký sme predtým dostali manuálnym formátovaním. .

Vo všeobecnosti s pywin32 získame takmer úplnú kontrolu nad dokumentom MS Word, čo nám umožňuje zmeniť ho a priviesť ho do podoby, ktorú vyžaduje váš podnikový štandard. Samozrejme, rovnaké ciele by sa dali dosiahnuť pomocou iných nástrojov, napríklad makier VBA, ale pre mňa bolo pohodlnejšie použiť python.

Stručný vzorec pre tento prístup:

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

Nezáleží na tom, čo je to „niečo“. V mojom prípade to bol Pandoc a python s pywin32. Vaše preferencie môžu byť rôzne, ale dôležité je, že je to možné. A toto je hlavné posolstvo tohto článku.

Aby sme to zhrnuli, myšlienka je taká, že s týmto prístupom pracujete iba so súborom Markdown a používate Git na spoluprácu a kontrolu verzií a iba v prípade potreby (napríklad na poskytnutie dokumentácie klientovi) automaticky vytvoríte súbor v požadovanom formáte ( napríklad MS Word).

Proces

Myslím si, že pre mnohých je vyššie uvedený vzorec dostatočný na to, aby pochopili, ako možno teraz organizovať proces práce s dokumentáciou. Napriek tomu sa zvyčajne zameriavam na sieťových inžinierov, takže vo všeobecnosti ukážem, ako môže teraz vyzerať pracovný proces a ako sa to líši od prístupu k úprave súborov MS Word.

Aby sme boli konkrétni, ako platformu pre prácu s Git si vyberieme GitHub. Potom by ste mali vytvoriť úložisko a umiestniť súbor alebo súbory Markdown, s ktorými plánujete pracovať, do hlavnej vetvy.

Pozrieme sa na jednoduchý proces založený na „github flow“. Jeho popis možno nájsť na internete aj na habre.

Povedzme, že na dokumentácii pracujú štyria ľudia a vy ste jedným z nich. Potom sa vytvoria ďalšie štyri vetvy, napríklad s menami týchto ľudí. Každý pracuje lokálne, vo svojej pobočke a robí zmeny so všetkým potrebným git príkazy.

Po dokončení nejakého dokončeného kusu práce vytvoríte požiadavku na stiahnutie, čím spustíte diskusiu o vašich zmenách. Možno sa počas diskusie ukáže, že by ste mali pridať alebo zmeniť niečo iné. V tomto prípade vykonáte potrebné zmeny a vytvoríte dodatočnú požiadavku na stiahnutie. Nakoniec sa vaše zmeny prijmú a zlúčia do hlavnej vetvy (alebo sa zahodia).

Samozrejme, toto je dosť všeobecný popis. Ak chcete vytvoriť podrobný proces, odporúčam vám kontaktovať vývojárov alebo nájsť skúsených ľudí. Chcem však poznamenať, že bariéra vstupu do Git je pomerne nízka. To neznamená, že protokol je jednoduchý, ale môžete začať jednoducho. Ak neviete vôbec nič, myslím, že po niekoľkých hodinách alebo možno dňoch strávených učením sa a inštaláciou ho môžete začať používať.

Aký je prínos tohto prístupu v porovnaní napríklad s procesom opísaným v príklade vyššie?

V skutočnosti sú procesy dosť podobné, len ste vymenili

kopírovanie súboru -> vytvorenie pobočky
kopírovanie textu do výsledného súboru -> zlúčenie
kopírovanie najnovších zmien do seba -> git pull/fetch
diskusia v korešpondencii -> vytiahnuť žiadosti
režim stopy -> git diff
posledná schválená verzia -> hlavná vetva
záloha (kopírovanie na vzdialený server) -> git push
...

Takto ste zautomatizovali všetko, čo ste už museli urobiť, ale manuálne.

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

• vytvoriť jasný, jednoduchý a kontrolovaný proces zmien dokumentov
• pretože konečný dokument (v našom príklade MS Word) vytvoríte automaticky, zníži sa tým pravdepodobnosť chýb formátovania

poznámka

Napriek tomu si myslím, že je zrejmé, že aj keď pracujete na dokumentácii samostatne, používanie Gitu vám môže výrazne uľahčiť prácu.

To všetko skvalitňuje dokumentáciu a skracuje čas na jej tvorbu. A ešte malý bonus - naučíte sa Git, ktorý vám pomôže pri automatizácii vašej siete :)

Ako prejsť na nový proces?

Na začiatku článku som napísal, že zajtra môžete začať pracovať novým spôsobom. Ako posunúť svoju prácu novým smerom?

Tu je postupnosť krokov, ktoré budete s najväčšou pravdepodobnosťou musieť dodržať:

• ak je váš dokument veľmi veľký, rozdeľte ho na časti
• previesť každú časť na Markdown (napríklad pomocou Pandoc)
• nainštalujte si jeden z editorov Markdown (používam Typora)
• s najväčšou pravdepodobnosťou budete musieť upraviť formátovanie vytvorených dokumentov Markdown
• začnite aplikovať proces popísaný v predchádzajúcej kapitole
• zároveň začnite upravovať konverzný skript tak, aby vyhovoval vašej úlohe (alebo vytvorte niečo vlastné)

Nemusíte čakať, kým vytvoríte a zdokonalíte konverzný mechanizmus Markdwon -> požadovaný výstupný typ dokumentu. Ide o to, že aj keď nie ste schopní rýchlo plne zautomatizovať postup konverzie vašich súborov Markdown, stále to môžete urobiť v určitej forme pomocou Pandoc a potom to do finálnej podoby priviesť manuálne. Zvyčajne to nemusíte robiť často, ale iba na konci určitých fáz a táto manuálna práca, aj keď je nepohodlná, je podľa môjho názoru stále celkom prijateľná vo fáze ladenia a nemala by „spomaliť“ proces. veľa.

Všetko ostatné (Markdown, Git, Pandoc, Typora) je už pripravené a na začatie práce s nimi netreba veľa úsilia ani času.

Zdroj: hab.com