Mrazí Vás v zádech z dokumentace ?

Posted on Posted in DevOps

Mrazí Vás v zádech, když slyšíte nebo vidíte slovíčko dokumentace ? Skvělé ! Pravděpodobně jste z IT branže 🙂
Každý obor na světě má své slunné, tak i stinné stránky. Převedeno do žargonu IT, dneska je na výslunní funkcionální programování v čele s frontend programátory a až trochu opodál přešlapují backend vývojáři. Co mají nejen všichni programátoři, ale celé IT, společné ? Ano, je to dokumentace. Dokumentace je něco, co nikdo nechce dělat. Občas se na ní nahlíží jako na podřadnou práci. Přitom síla a podstata dokumentace je přehlížená a velmi podceněná.

Proč vytvářet dokumentaci

  • Žádná tabule ani flipchart nevydrží věčně
  • Týmy se neustále rozrůstají a vysvětlování principů a předávání znalostí širšímu publiku je náročnější
  • Lidé odcházejí a přicházejí
  • Na základě vizualizací a schémat v dokumentaci lze provádět důležitá rozhodnutí
  • Jedinečný nástroj, jak zachytit komplexitu systému. V případě distribuovaných systémů nutnost
  • Zajistíte všem rolím dostatečný přehled o projektu

Je velké množství velmi dobrých důvodů, proč nezapomínat a neodkládat dokumentaci na konec procesu vývoje.  Není dokumentace jako dokumentace. Nesmíme zapomenout, že dokumentaci nečtou pouze uživatelé systému a programátoři. Dokumentace je podklad, který mohou využívat i mnohé další role, ať už uvnitř Vaší firmy nebo Vaši dodavatelé. Význam a hodnota dobré dokumentace se neodvíjí od množství diagramu nebo množství textu, ale od svojí přehledností a věcnosti. Máte v dokumentaci pořádek nebo je ve stavu, aby se neřeklo, že neexistuje ?

Dokumentace v kódu

Z mé zkušenosti nejlepší dokumentace kódu je čitelný kód. Pokud dodnes píšete nad konstruktor, že se jedná o konstruktor, tak děláte něco špatně. Komentáře a věci vhodné pro Vaše IDE? Ano, ale opět platí, že nejlepší je mít dobře pojmenované parametry než psát dvakrát to samé. U specifických problémů je to naopak. Určitě je dobré je zaznamenat. I v případě, že píšete malé hezké metody můžete se dostat do situace, kdy řešíte nějaké logické úskalí. Pokud už máte ten pocit, že se k tomuto problému budete muset někdy vracet a nebylo to lehké vymyslet, je to ideální místo.

Cílem dokumentace není zahltit čtenáře, ale ulehčit mu cestu k dosažení pochopení systému a vazeb.

UML 2.0

Diagramy jsou skvělé a obrázek vydá za tisíc slov, ale … Je nutné se zamyslet nad diagramy, které vytváříte. Opravdu jich potřebujeme tolik ? Diagramy použití jsou fajn, protože víte, jak interaguje systém s uživatelem nebo jiným systémem. Záleží na typu projektu, ale pokud máte jen trochu času, určitě se to vyplatí. Diagram případu použití pochopí i Váš management a dokáže snadno zachytit a znázornit myšlenku ve vyšších vrstvách návrhu. Zároveň Vám mohou posloužit jako podklady k BDD.

Deployment digramy jsou vhodnější hlavně pokud Vaše projekty jsou rozsáhlejší nebo pokud jste se vydali cestou microservice. Každopádně si je zamilujete, protože jsou vážně užitečné. Nelze říct, že ostatní druhy diagramů jsou méně významné, ale největší problém dokumentace tkví v tom, že jí někdo musí udržovat aktuální. Pokud budete mít spoustu class diagramu, sekvenčních diagramů, aktivity diagramů a jiných, tak se především zamyslete, jak a kdo je bude udržovat aktuální. Obchod Vás bude neustále zásobovat nejrůznějšími požadavky na změny v kódu a z Vaší detailní dokumentace se stane zcela bezcenný dokument. Navíc, dnes jsou vývojová prostředí plná nástrojů, které programátorovi umožní bleskovou orientaci v kódu.

 Konvence

Tvořte si týmové nebo celofiremní konvence. Stejně jako u kódu, tak i u dokumentace platí, že nejlepší dokumentace je ta, kterou nemusíte psát. Znáte princip convention over configuration ? Lze jednoduše aplikovat i nad dokumentací. Pravidla aplikovaná napříč projekty se mi vždy osvědčila, ale ověřte si, že všichni členové týmu jim rozumí stejně. Nedělejte dokumentaci pocitově, ale zjistěte jaké role k ní chtějí a potřebují přístup. Pak dokážete vydefinovat různé pohledy na dokumentaci, které by jste měli pokrýt.

Dokumentace vs. Knowledge base

Zdánlivě podobné termíny, ale každý má své jiné uplatnění. Z mé zkušenosti knowledge base by měla být vybudována na základě dotazů a problémů koncových uživatelů. Měla by být reaktivní. Do jisté míry můžete tušit, jaké problémy budou Vaše uživatele trápit, ale připravte se na nečekané, protože uživatelé jsou nevyzpytatelní 🙂 . Knowledge base by měla vždy rozebrat určitý problém a zároveň nastínit řešení.

Jak tvořit dokumentaci a neztratit se ?

Nástrojů na tvorbu diagramů dokumentace a knowledge base je spousty. Cílem hry, dle mého názoru, je tvořit dokumentaci, která je stručná a hlavně efektivní.  Zároveň Vás podrží při důležitém rozhodování. To, že není celý systém zdokumentovaný, nemusí být zcela nutně špatně. V mnoha filmech uslyšíte, že se máte rozhodovat srdcem, ale myslím si, že v IT to rozhodně neplatí. Před tvorbou dokumentace se zkuste zamyslet, jakým způsobem budou Váš systém využívat uživatelé nebo jiné systémy. Jaké role budou využívat Váš systém ? Zvažte, jak by se Váš systém mohl rozrůstat a vytipujte, jaké budou důležité principy a procesy, které budete muset měnit nebo o nich rozhodovat. Na základě těchto úvah již můžete začít připravovat Vaši strategii pro tvorbu dokumentace.

Leave a Reply

Your email address will not be published. Required fields are marked *