Použijte GIT při dokumentování

Někdy může být kritický nejen samotný dokument, ale i proces práce na něm. Například u projektů je velká část práce spojena právě s přípravou dokumentace a nesprávný proces může vést k chybám a dokonce ke ztrátě informací, a tudíž i k ztrátě času a zisku. I když toto téma není centrální v vaší práci a je na okraji, správný proces stále může zlepšit kvalitu dokumentu a ušetřit vám čas.

Přístup uvedený zde, s příkladem konkrétní realizace, má nízký vstupní práh. Technicky můžete už zítra začít pracovat jinak.

Formulace úkolu

Musíte vytvořit určitý dokument nebo sadu dokumentů. Může to být projektová dokumentace nebo protokolování vaší sítě, nebo něco jednoduššího, například potřebujete popsat procesy ve společnosti nebo ve vašem oddělení. Obecně řečeno, jde o jakýkoli dokument nebo sadu dokumentů s textem, obrázky, tabulkami… Ztížíme úkol tím, že

1. tato práce předpokládá společné úsilí skupiny nebo několika skupin zaměstnanců
2. na výstupu chcete mít dokument v určitém formátu, s atributy firemního stylu, vytvořený podle určité šablony. Pro určité určení budeme považovat, že to je MS Word (.docx)

Před 10 lety by byl přístup jednoznačný: vytvořili bychom dokumenty MS Word a nějakým způsobem zorganizovali práci na změnách.

A tento přístup zůstává platný. Používají ho i velcí integrátoři při vytváření projektové dokumentace. Ale intuitivně je zřejmé, že pokud na dokumentu skutečně intenzivně pracujete, s mnoha úpravami a diskusemi po delší dobu, není tento přístup příliš pohodlný.

Příklad

Tuto problematiku jsem intenzivně pocítil, když jsem pracoval v jednom velkém integrátorovi. Proces změny projektové dokumentace byl následující:

1. inženýr stáhne poslední verzi dokumentu MS Word (.docx)
2. změní název
3. provádí úpravy v režimu sledování
4. posílá dokument s úpravami architektovi
5. také posílá seznam všech oprav s komentáři
6. architekt analyzuje změny
7. pokud je vše v pořádku, zkopíruje tyto změny do souboru s poslední verzí, změní verzi a nahrává na sdílený zdroj
8. pokud jsou připomínky, zahájí se diskuse (e-mailem nebo na schůzkách)
9. dosáhne se konsenzu
10. dále body 3 – 9

Když práce nebyla intenzivní, fungovalo to nějak, ale přece jen to fungovalo. Ale v určitém okamžiku se tento proces stal úzkým místem celého projektu a vedl k problémům. Problém je, že všechno jde špatně, jakmile se změny provádějí často a současně několika týmy.

Když jsme přešli do fáze předběžného testování, začaly se objevovat různé problémy a ačkoliv šlo o drobnosti, bylo často potřeba měnit dokumentaci — čtyři různé týmy, denně, prakticky současně, s diskuzemi. Všechny tyto změny procházely jedním inženýrem — architektem. Soubor s návrhem projektu byl obrovský, a následně byl architekt zatížen rutinní prací spojenou s velkým množstvím kopírování, editování, dělal mnoho chyb, bylo potřeba vše dvakrát zkontrolovat, znovu posílat, a celkově to bylo blízko chaosu.

V tomto případě tento přístup, přístup práce s dokumentem MS Word, fungoval s velkým skluzem a vytvářel problémy.

Git, Markdown

Když jsem se setkal s problémem popsaným ve výše uvedeném příkladu, začal jsem tento problém zkoumat.
Viděl jsem, že stále více se stává populární používání Markdown ve spojení s Git při vytváření dokumentů.

Git je nástroj pro vývoj. Ale proč ho nepoužít pro proces dokumentace? V tomto případě je otázka vícestupňové práce vyřešena. Abychom však plně využili možnosti Gitu, potřebujeme textový formát dokumentu, potřebujeme najít jiný nástroj, ne MS Word, a pro tyto účely je Markdown ideální.

Markdown je jednoduchý jazyk pro textové značení. Je určen k vytváření pěkně formátovaných textů v běžných TXT souborech. Pokud budeme vytvářet naše dokumenty v Markdownu, pak vazba Markdown — Git vypadá přirozeně.

Vše by bylo v pořádku a mohli bychom tuto část uzavřít, kdyby nebylo našeho druhého požadavku: „na výstupu potřebujeme dokument v určitém formátu, se známkami firemního stylu, vytvořený podle určité šablony“ (a dohodli jsme se na začátku, že pro jistotu to bude MS Word). To znamená, že pokud jsme se rozhodli použít Markdown, musíme nějak převést tento soubor na .docx požadovaného vzhledu.

Existují programy na převod mezi různými formáty, například, Pandoc.
Můžete převést soubor Markdown do formátu .docx pomocí tohoto programu.
Ale i tak je třeba chápat, že za prvé, ne všechno, co je v Markdown, bude převedeno do MS Word a za druhé, MS Word je celá země ve srovnání s kompaktním, ale přece jen městečkem, kterým Markdown je. Existuje obrovské množství funkcí, které MS Word nabízí a které v žádném případě nejsou v Markdown. Nelze jednoduše vzít a s určitými klíči převést váš Markdown formát do požadovaného vzhledu MS Word pomocí Pandoc. Obvykle tedy, po převodu, je nutné „dopracovat“ získaný dokument .docx ručně, což opět může být časově náročné a může vést k chybám.

Kdybychom mohli napsat skript, který by automaticky „dopracovával“ to, s čím si Pandoc neporadil – to by bylo ideální řešení.

Vzhledem k nesrovnatelnosti funkcí MS Word a Markdown obecně je podle mého názoru vyřešení tohoto úkolu nemožné, ale lze to aplikovat na konkrétní situace, konkrétní požadavky? Moje zkušenost ukazuje, že ano, je to možné a pravděpodobně to možné je pro mnohé, nebo možná dokonce pro většinu situací.

Řešení specifického úkolu

Takže v mém případě, po převodu souboru pomocí Pandoc, jsem musel ručně provést dodatečné zpracování souborů, a to konkrétně

• přidat do Wordu pole s automatickým číslováním nadpisů (caption) tabulek a obrázků
• změnit styl pro tabulky

Nenašel jsem, jak toho dosáhnout standardními (Pandoc) nebo známými prostředky. Proto jsem použil python skript s pywin32 balíčkem. V důsledku toho jsem dosáhl plné automatizace. Nyní mohu převést svůj soubor Markdown do požadovaného tvaru dokumentu MS Word jedním příkazem.

Podívejte se na detaily zde.

Poznámka

V tomto příkladu samozřejmě převádím určitý abstraktní Markdown soubor, ale stejný přístup byl použit také na 'bojovém' dokumentu, a na výstupu jsem dostal prakticky stejný dokument MS Word, který jsme dříve získávali ručním formátováním.

Obecně, s pywin32 máme prakticky plnou kontrolu nad dokumentem MS Word, což nám umožňuje měnit ho a přizpůsobovat vzhledu, který vyžaduje váš firemní standard. Ostatně těchto cílů bylo možné dosáhnout i pomocí jiných nástrojů, například VBA maker, ale mně bylo pohodlnější použít python.

Krátký vzorec tohoto přístupu:

Markdown + Git -- (něco) --> MS Word

Není tak důležité, čím je 'něco'. V mém případě to byl Pandoc a python s pywin32. Možná máte jiné preference, ale důležité je, že je to možné. A to je hlavní poselství tohoto článku.

Shrneme to, myšlenka je ta, že při tomto přístupu pracujete pouze s Markdown souborem a používáte Git pro organizaci spolupráce a kontrolu verzí, a pouze v případě potřeby (například abyste poskytli dokumentaci klientovi) automaticky vytváříte soubor požadovaného formátu (například MS Word).

Proces

Myslím, že pro mnohé je výše uvedený vzorec dostatečný, aby pochopili, jak nyní může být organizován proces práce s dokumentací. Ale většinou se orientuji na síťové inženýry, takže v obecných obrysech ukážu, jak nyní může vypadat proces práce a čím se liší od přístupu s úpravou souborů MS Word.

Pro jasnost zvolíme jako platformu pro práci s Gitem GitHub. Pak byste měli vytvořit repozitář a v master větvi umístit Markdown soubor nebo soubory, se kterými plánujete pracovat.

Prozkoumáme jednoduchý proces založený na 'github flow'. Jeho popis lze najít jak na internetu, tak na habru.

Předpokládejme, že na dokumentaci pracují čtyři lidé a vy jste jedním z nich. Poté jsou vytvořeny čtyři další větve (branch), například s jmény těchto lidí. Každý pracuje lokálně, ve své větvi a provádí změny se všemi potřebnými git příkazy.

Dokončením určitého úseku práce vytváříte pull request, čímž iniciujete diskuzi o vašich změnách. Během této diskuze se může ukázat, že musíte přidat nebo změnit něco dalšího. V takovém případě provedete potřebné úpravy a vytvoříte další pull request. Nakonec jsou vaše změny přijaty a sloučeny (merge) s master větví (nebo odmítnuty).

Samozřejmě, toto je poměrně obecný popis. Navrhuji kontaktovat vaše vývojáře nebo najít znalé osoby pro podrobnější proces. Rád bych ale podotkl, že prahová úroveň pro vstup do Gitu je velmi nízká. Neznamená to, že protokol je jednoduchý, ale můžete začít s něčím jednoduchým. Pokud vůbec nic nevíte, domnívám se, že po několika hodinách nebo možná dnech studia a instalace můžete začít jej používat.

Jaký je tedy přínos tohoto přístupu ve srovnání například s procesem popsaným výše?

Ve skutečnosti jsou procesy docela podobné, jen jste nahradili

kopírování souboru -> vytvoření větve (branch)
kopírování textu do konečného souboru -> sloučení (merge)
kopírování posledních změn k sobě -> git pull/fetch
diskuze v korespondenci -> pull requests
track mode -> git diff
poslední schválená verze -> master větev
záloha (kopírování na vzdálený server) -> git push
…

Tímto způsobem jste automatizovali vše, co jste dříve museli dělat ručně.

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

• vytvořit jasný, jednoduchý a kontrolovatelný proces změn dokumentace
• Protože konečný dokument (v našem příkladě MS Word) vytváříte automaticky, snižuje to pravděpodobnost chyb spojených s formátováním.

Poznámka

S ohledem na výše uvedené je myslím jasné, že i když pracujete na dokumentaci sám, může vám používání Gitu výrazně usnadnit práci.

To vše zvyšuje kvalitu dokumentace a snižuje čas její tvorby. A ještě malý bonus – naučíte se Git, což vám pomůže při automatizaci vaší sítě 🙂.

Jak přejít na nový proces?

Na začátku článku jsem napsal, že již zítra můžete začít pracovat novým způsobem. Jak přenést svou práci do nového směru?

Zde je postup kroků, které pravděpodobně budete muset provést:

• pokud je váš dokument velmi rozsáhlý, rozdělte ho na části.
• Převádějte každou část do Markdownu (například pomocí Pandoc)
• Nainstalujte si jeden z editorů Markdown (já používám Typora)
• pravděpodobně budete muset upravit formátování vytvořených Markdown dokumentů
• začněte aplikovat proces popsaný v předchozí kapitole
• současně začněte upravovat konverzní skript podle své úlohy (nebo vytvořte něco vlastního)

Nemusíte čekat, dokud nevytvoříte a perfektně doladíte mechanismus konverze Markdown -> požadovaný výstupní formát dokumentu. I když se vám nepodaří rychle plně automatizovat proces převodu vašich Markdown souborů, stále to můžete udělat v nějaké podobě pomocí Pandoc a následně doladit výstup ručně. Obvykle to nemusíte dělat často, pouze na konci určitých fází, a tato ruční práce, i když je nepříjemná, je podle mě v fázi ladění zcela přijatelná a neměla by výrazně „zdržovat“ proces.

Všechno ostatní (Markdown, Git, Pandoc, Typora) je již připraveno a nevyžaduje zvláštní úsilí nebo čas, abyste s tím mohli začít pracovat.

Zdroj: habr.com