Ahoj všichni!
Jmenuji se Masha a pracuji jako inženýr pro zajištění kvality ve skupině společností Tinkoff. QA práce obnáší hodně komunikace s různými lidmi z různých týmů, navíc jsem byl manažerem a lektorem vzdělávacích programů, takže moje komunikační mapa byla co nejširší. A v určitém okamžiku jsem vybuchl: uvědomil jsem si, že už nemůžu, nemůžu, nemůžu vyplnit pekelné tuny nečitelných tabulek a dokumentů.
Určitě si teď každý z vás představil, o čem mluvím, a polil ho studený pot: seznamy příjmení bez abecedního řazení, tabulky se stovkami sloupců s ledabylým rozložením, tabulky s tisíci řádků, ve kterých je potřeba vygumovat prst na kolečku myši, abyste se podívali do nadpisu, tuny stránek nečíslovaných pokynů, stovky dopisů posílaných mezi sebou s údaji, které je třeba analyzovat a systematizovat a nacpat do stejných nečitelných tabulek.
A tak, když jsem trochu vychladl, rozhodl jsem se napsat tento článek. Budu mluvit o tom, jak můžete normálně (dokonce někdy pohodlně) udržovat různé neproduktové dokumentace. Doufám, že se článek rozsype po síti a úroveň pekla v odděleních sousedících s vývojem alespoň trochu klesne a lidé (včetně mě) budou o něco šťastnější.
Nástroje
Dokumentace k produktu je často uchovávána spolu s kódem, což je dobrá věc. A neproduktová dokumentace je obvykle uložena kdekoli. Často se lidé snaží do Confluence přinášet informace z různých míst a my nejsme výjimkou. Takže zbytek příběhu je o něm.
Obecně je Confluence pokročilý wiki engine. Umožňuje pracovat s daty v různých typech zobrazení: text s formátováním, tabulky, různé grafy. Jedná se o velmi zajímavý a mocný nástroj, ale pokud si s ním nevíte rady, získáte další skládku nečitelných dokumentů. Naučím tě vařit!
Makra
Téměř veškerá magie Confluence je postavena na makrech. Makra je spousta a lze je vzájemně kombinovat. Jsou placená a bezplatná, dále zde budou různé příklady maker s odkazy na dokumentaci k nim.
Rozhraní pro práci s makry je maximálně jednoduché. Chcete-li přidat makro, musíte kliknout na znaménko plus a vybrat požadovaný prvek ze seznamu.
Pokud je makro soběstačné, tedy nevyžaduje vložení něčeho dalšího do sebe, vypadá jako blok.
Pokud makro potřebuje něco uvnitř, aby fungovalo, vypadá jako krabice.
Zároveň můžete do jednoho rámečku umístit tolik dalších, kolik chcete, pokud je ve vaší pyramidě logika.
Každé makro má náhled: hned se ukáže, zda jste makro správně vyplnili a nakonfigurovali.
šablony
Kromě maker existuje pohodlný nástroj pro předvyplnění obsahu – jedná se o šablonu.
Šablony lze použít při vytváření libovolné stránky: stačí kliknout na tři tečky vedle tlačítka „Vytvořit“ a vybrat požadovanou šablonu.
Poté se na vytvořenou stránku přidá veškerý obsah, který je v šabloně.
Stránky ze šablon může vytvářet kdokoli, ale stránky mohou vytvářet pouze ti, kteří mají práva vytvářet nebo upravovat šablony sami. Do šablony můžete přidat další pokyny o tom, jak má být stránka udržována.
Stolní magie
Ve skutečnosti jako technický odborník miluji tabulky a dokážu do nich zabalit téměř jakékoli informace (i když to není vždy efektivní). Samotné tabulky jsou přehledné, strukturované, škálovatelné, kouzelné!
Ale i tak nádherná entita, jakou je stůl, se dá zkazit. A dá se úspěšně používat a dokonce vylepšovat. Více o tom níže.
Filtrování (placený plugin)
Každá obrovská nečitelná tabulka může být pomocí filtrování o něco méně obrovská a o něco čitelnější. K tomu můžete použít placené makro .
Do tohoto makra je potřeba strčit stůl (i ten nejošklivější je možný, hlavní je ho strčit celý). V makru můžete vybrat sloupce pro rozevírací filtr, textový filtr, číselný filtr a filtr podle data.
Představte si, že všechny informace o kandidátech na všechna volná místa jsou zaznamenány v tabulkovém seznamu. Přirozeně neřazeno – lidé nepřicházejí na pohovory v abecedním pořadí. A musíte pochopit, zda jste předtím vedli pohovor s konkrétním uchazečem. Stačí vložit toto peklo do makra filtru, přidat textový filtr podle příjmení – a voila, informace jsou na vaší obrazovce.
Stojí za zmínku, že filtrování velkých tabulek může ovlivnit výkon systému a dobu načítání stránky, takže umístění velké tabulky do filtru je dočasná berlička, je lepší vytvořit proces, ve kterém lidé nebudou muset vytvářet obrovské nečitelné tabulky (např. příklad postupu bude na konci článku).
Řazení (placený plugin)
S magickým makrem můžete také nastavit výchozí řazení pro libovolný sloupec a očíslovat řádky. Nebo klikněte na libovolný sloupec tabulky vložené do makra filtru a dojde k řazení podle tohoto sloupce.
Například máte stejnou tabulku s uchazeči a potřebujete zjistit, kolik pohovorů proběhlo v určitém měsíci – seřadit podle data a radovat se.
Kontingenční tabulky (placený plugin)
Nyní přejděme k zajímavějšímu případu. Představte si, že váš stůl je obrovský a potřebujete na něm něco spočítat. Samozřejmě si to můžete zkopírovat do Excelu, spočítat, co potřebujete a nahrát data zpět do Confluence. Můžete použít makro jednou? a získat stejný výsledek, pouze aktualizován.
Například: máte tabulku, která obsahuje data všech zaměstnanců – kde se geograficky nacházejí a jaké pozice zastávají. Chcete-li vypočítat, kolik lidí je v každém městě, musíte v makru "Kontingenční tabulka" vybrat řádek, podle kterého jsou data agregována (místo) a typ operace (sčítání).
Samozřejmě můžete seskupovat podle několika kritérií najednou, vidíte všechny možnosti .
Grafy (placený plugin)
Jak jsem řekl, ne každý miluje stoly tak jako já. Bohužel většina manažerů je nemá vůbec ráda. Ale každý má rád jasné barevné tabulky.
Své o tom jistě věděli i tvůrci Confluence (určitě mají i šéfy milující reporty a hitparády, kde by bez toho byli). Proto můžete použít magické makro . Do tohoto makra musíte vložit kontingenční tabulku z předchozího odstavce a voila – vaše nudná šedá data jsou krásně vizualizovaná.
Toto makro má samozřejmě také nastavení. Odkaz na dokumentaci jakéhokoli makra lze nalézt v režimu úprav daného makra.
Snadnost agregace
Informace z předchozích odstavců pro vás zřejmě nebyly zjevením. Ale teď už určitě umíte makra používat a můžu přejít k zajímavější části článku.
Tagy
Je špatné, když lidé ukládají informace do jednoho nestrukturovaného článku nebo obrovské tabulky. Ještě horší je, když jsou části těchto informací nejen nečitelné, ale také rozptýlené po rozlehlých oblastech Confluence. Naštěstí je možné shromáždit rozptýlené informace na jednom místě. K tomu musíte použít (značky známé všem na sociálních sítích).
Na libovolnou stránku lze přidat libovolný počet značek. Kliknutím na značku se dostanete na agregační stránku s odkazy na veškerý obsah s touto značkou a také na sadu souvisejících značek. Související značky jsou ty, které se často objevují na stejné stránce.
Vlastnosti stránky
Na stránku můžete přidat další zajímavé makro pro strukturování informací - . Uvnitř musíte odeslat tabulku se dvěma sloupci, první bude klíč a druhý bude hodnota vlastnosti. Makro lze navíc ze stránky skrýt, aby nepřekáželo při čtení obsahu, ale stránka bude stále označena potřebnými klávesami.
Věnujte pozornost ID - je vhodné jej nastavit tak, aby visely různé skupiny vlastností na různých stránkách (nebo dokonce různé skupiny vlastností na jedné stránce).
zprávy
Pomocí značek můžete shromažďovat zprávy. Například makro shromažďuje všechny stránky s určitou sadou značek.
Zajímavější zprávou je ale makro . Sbírá také všechny stránky s určitou sadou tagů, ale nevypisuje je jen tak, ale sestavuje tabulku (chytíte souvislost se začátkem článku?), ve které jsou sloupce klíče vlastností stránky.
Ukazuje se souhrnná tabulka informací z různých zdrojů. Je hezké, že má pohodlné funkce: adaptivní rozložení, řazení podle libovolného sloupce. Takovou tabulku sestav lze také nakonfigurovat uvnitř makra.
Při konfiguraci lze z přehledu odstranit některé sloupce, nastavit výchozí stav nebo počet zobrazených záznamů. Můžete také nastavit ID vlastnosti stránky, abyste viděli pouze informace, které potřebujete.
Máte například spoustu stránek pro zaměstnance, tyto stránky mají sadu vlastností o člověku: na jaké úrovni je, kde je, kdy se připojil k týmu a tak dále. Tyto vlastnosti jsou označeny id = zaměstnanec_inf. A na stejné stránce je druhá sada vlastností, která obsahuje informace o osobě jako součásti týmu: jakou roli tato osoba vykonává, v jakém týmu je a tak dále. Tyto vlastnosti jsou označeny ID = team_inf. Při sestavování sestavy pak můžete zobrazit pouze informace pro jedno ID nebo dvě najednou – podle toho, co je výhodnější.
Krása tohoto přístupu spočívá v tom, že každý si může shromáždit informační tabulku, kterou potřebuje, která nebude nic duplikovat a bude aktualizována při aktualizaci hlavní stránky. Například: vedoucího týmu nezajímá, kdy jeho vývojáři dostali práci, ale je důležité, jakou roli každý z nich v týmu hraje. Vedoucí týmu shromáždí zprávu o týmu. A účetnímu je jedno, kdo jakou roli vykonává, ale pozice jsou důležité - bude shromažďovat zprávu o pozicích. V tomto případě nebude zdroj informací duplikován ani převeden.
Závěrečný proces
Návod
Takže můžeme krásně strukturovat a efektivně agregovat informace v Confluence pomocí maker jako příkladu. V ideálním případě se ale musíte ujistit, že nové informace jsou okamžitě strukturované a dostávají se do všech již používaných agregačních mechanismů.
Zde přijde na pomoc hromada maker a šablon. Chcete-li přimět lidi, aby vytvářeli nové stránky ve správném formátu, můžete použít makro Vytvořit ze šablony. Na stránku přidá tlačítko, na které se kliknutím vytvoří nová stránka ze šablony, kterou potřebujete. Tímto způsobem přimějete lidi okamžitě pracovat ve formátu, který potřebujete.
V šabloně, ze které povolíte vytvořit stránku, je potřeba předem přidat štítky, makro "Vlastnosti stránky" a tabulku vlastností, které potřebujete. Doporučuji také přidat pokyny, jakými hodnotami stránku vyplnit a hodnoty vlastností.
Poté bude konečný proces vypadat takto:
- Vytváříte šablonu pro určitý typ informací.
- V této šabloně přidejte štítky a vlastnosti stránky do makra.
- Na libovolném vhodném místě vytvořte kořenovou stránku pomocí tlačítka, kliknutím na které se ze šablony vytvoří podřízená stránka.
- Spusťte se na kořenové stránce uživatelů, kteří potenciálně vygenerují potřebné informace (podle požadované šablony kliknutím na tlačítko).
- Sestavte si zprávu o vlastnostech stránky pomocí značek, které jste zadali v šabloně.
- Radujte se: všechny potřebné informace máte ve vhodném formátu.
Úskalí
Jako inženýr kvality mohu s klidem říci, že na světě není nic dokonalého. I božské stoly jsou nedokonalé. A ve výše uvedeném procesu jsou úskalí.
- Pokud se rozhodnete změnit názvy nebo složení vlastností stránky, budete muset aktualizovat všechny již vytvořené objekty, aby se jejich data správně natáhla do souhrnné sestavy. To je smutné, ale na druhou stranu vás to nutí detailně přemýšlet o „architekturě“ vašeho informačního souboru, což je velmi zajímavý úkol.
- Budete muset napsat slušné množství návodů, jak vyplnit informační tabulky a používat značky. Ale na druhou stranu můžete tento článek hodit všem správným lidem.
Příklad uložení neproduktové dokumentace
Prostřednictvím výše popsaného procesu můžete uspořádat ukládání téměř jakýchkoli informací. Krása tohoto přístupu spočívá v tom, že je univerzální: jakmile si na něj uživatelé zvyknou, přestanou dělat nepořádek. Velkým (ale ne zadarmo) plusem je také možnost sbírat různé statistiky za chodu a kreslit na ně krásné diagramy.
Uvedu příklad našeho procesu udržování informací o týmu.
Pro každého člověka v týmu jsme se rozhodli vytvořit zaměstnaneckou kartu. Podle toho máme šablonu, podle které si každý nový člověk vytvoří tuto kartu pro sebe a uchová v ní všechny své osobní údaje.
Jak vidíte, máme podrobnou tabulku vlastností a hned máme návod, jak tuto stránku udržovat. Některé štítky si zaměstnanci odkládají sami podle pokynů, v šabloně pouze ty hlavní: štítek na kartu zaměstnaneckou kartu, směrová značka směr-zapojit a příkazový štítek tým-qa.
Výsledkem je, že poté, co si každý vytvoří kartu pro sebe, získá kompletní tabulku s informacemi o zaměstnancích. Tyto informace lze použít na různých místech. Správci zdrojů mohou shromažďovat obecné tabulky pro sebe a vedoucí týmu mohou shromažďovat tabulky příkazů přidáním tagu týmu do výběru.
Podle značek můžete vidět různé souhrny, například podle qa-upgrade-plan zobrazí se všechny úkoly pro vývoj QA. Každý člověk si přitom ve své kartě zaměstnance uchovává důležitý příběh a svůj vlastní plán rozvoje – ze šablony plánů rozvoje si vytvoří vnořenou stránku.
Závěr
Uchovávejte veškerou dokumentaci tak, abyste se za ni nestyděli a uživatelé nebyli nesnesitelně zraněni!
Opravdu doufám, že článek bude užitečný a ve veškeré dokumentaci světa přijde řád.
Zdroj: www.habr.com