úterý 29. ledna 2013

Jak si (ne)udělat z wiki žumpu

Krátká zamyšlení na téma, co do wiki nepatří, kde by měla ležet vývojářská dokumentace a proč by pro ní neměla být wiki zdrojem pravdy.

Stane se každá firemní wiki žumpou nebo nestane se každá firemní wiki žumpou? Kolikrát jsem zažil, že po pár letech používání, se z ní stala žumpa zralá na kompletní čistku. V GoodData používáme Confluence, v Systinetu jsme používali Twiki a vždycky to dopadlo stejně katastroficky. Problém nebude v nástroji, ale spíš v jeho použití. Největší výhoda wiki je v jednoduchosti tvorby obsahu a jeho propojení. To co je na jedné straně výhodou, je na straně druhé i největší nevýhodou. Ne nadarmo platí "s čím kdo zachází, tím také schází". Možnost jednoduché tvorby obsahu vede k tomu, že se ve wiki začnou vytvářet i dokumenty dočasného charakteru, například implementační analýzy, popisy použití různých nástrojů a jejich parametrů, nebo backlog pro různé myšlenkové pochody. Tyto dokumenty pochopitelně nikdo neaktualizuje a potřeba aktuálních informací vede k tomu, že vznikají dokumenty nové, překrývající ty původní. Jakékoliv hledání se stává archeologickým průzkumem za použití fulltextu s nejistým výsledkem. Existuje pár pravidel, jak udržet wiki v kondici.

Do wiki rozhodně nepatří všechny typy informací. To se týká informace, které platí jenom po omezenou dobu, například zmíněné implementační analýzy. Wiki by neměla být "zdrojem pravdy" pro často měnící se informace. Zde narážím na fakt, že různé skupiny uživatelů mají různé případy užití wiki. Především vývojářská dokumentace, jako jsou designy nebo popisy užití knihoven a nástrojů, by měla ležet tak blízko zdrojovému kódu, jak je to jenom možné. Za ideální považuji exportování těchto informací do wiki během buildu, a jejich držení ve version control systemu jako je Git, Subversion apod. Díky tomu jsou informace ve wiki vždy aktuální a zároveň k nim mají vývojáři jednoduchý přístup s možností editace.

Pokud používáte GitHub, máte k tomu ideální prostředky. GitHub podporuje značkovací jazyk Markdown a soubory v něm vytvořené přímo renderuje. Na post-commit hook lze navěsit export a převod dokumentů do vašeho wiki systému. Součástí code review pak může být kontrola, že je dokumentace zaktualizovaná.