🥇Navrhování v Confluence

Ahoj všichni!

Jmenuji se Masha, pracuji jako inženýr kvality ve skupině společností Tinkoff. Práce v QA vyžaduje množství komunikace s různými lidmi z různých týmů, a navíc jsem byla manažerkou a lektorkou vzdělávacích programů, takže moje komunikační mapa byla maximálně široká. A v určitém okamžiku jsem vybuchla: uvědomila jsem si, že už nemohu, nemohu, nemohu vyplňovat pekelné tuny nečitelných tabulek a dokumentů.

Určitě si každý z vás právě teď představuje to, o čem mluvím, a zchladl pot: seznamy příjmení bez abecedního pořádku, tabulky se stovkami sloupců s rozhozeným formátováním, tabulky o tisících řádcích, ve kterých musíte otírat prst o kolečko myši, abyste si prohlédli záhlaví, tuny stran nečíslovaných pokynů, stovky e-mailů, které si navzájem posíláme s daty, která je třeba analyzovat a systematizovat a nacpat do stejně nečitelných tabulek.

A když jsem se trochu ochladila, rozhodla jsem se napsat tento článek. Pověsím vám, jak se dá normálně (a občas i pohodlně) vést různou nepodnikovou dokumentaci. Doufám, že se článek rozšíří po síti a úroveň chaosu v sousedních vývojových odděleních se alespoň trochu sníží, a lidé (včetně mě) se stanou trochu šťastnějšími.

Nástroje

Produktová dokumentace se často ukládá vedle kódu, což je dobré. Nepodniková dokumentace se obvykle ukládá kdekoliv. Často se lidé snaží přenášet informace z různých míst do Confluence, a my nejsme výjimkou. Takže veškeré další vyprávění o něm.

Confluence je celkově pokročilý wiki engine. Umožňuje pracovat s daty v různých typech zobrazení: text s formátováním, tabulky, různé diagramy. Je to velmi zajímavý a mocný nástroj, ale pokud ho neumíte připravit, dostanete další hromadu nečitelných dokumentů. Naučím vás, jak ho připravit!

Makra

Skoro všechno kouzlo Confluence je založené na makrech. Makra je velmi mnoho a lze je kombinovat navzájem. Některá jsou placená a jiná zdarma, dále 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, stačí kliknout na plus a vybrat požadovaný prvek ze seznamu.

Pokud je makro soběstačné, tedy nevyžaduje vložení něčeho jiného do sebe, vypadá jako blok.

Pokud je pro fungování makra potřeba něco umístit dovnitř, vypadá jako rám.

Do jednoho rámu je možné umisťovat neomezené množství dalších, pokud má vaše pyramida logiku.

Každé makro má náhled: ihned vidíte, zda jste správně vyplnili a nastavili makro.

Šablony

Kromě makrů existuje také užitečný nástroj pro předvyplnění obsahu – to je šablona.
Šablony lze použít při vytváření jakékoli stránky: stačí kliknout na tři tečky vedle tlačítka „Vytvořit“ a vybrat požadovanou šablonu.

Pak se do vytvořené stránky přidá celý obsah, který je ve šabloně.

Každý může vytvářet stránky ze šablon, ale vytvářet nebo upravovat samotné šablony mohou jen ti, kdo na to mají práva. Do šablony můžete přidat další pokyny, jak by měla stránka vypadat.

Kouzelné tabulky

Jako technik mám tabulky skutečně rád a dokážu téměř jakoukoli informaci do nich zakomponovat (i když to není vždy efektivní). Samotné tabulky jsou jasné, strukturované, škálovatelné, kouzelné!

Ale i tak skvělou entitu, jako je tabulka, lze pokazit. Lze ji však také úspěšně využít a dokonce vylepšit. O tom níže.

Filtrace (placený plugin)

Jakoukoli obrovskou, nečitelnou tabulku lze učinit o něco méně obrovskou a o něco čitelnější pomocí filtrace. K tomu lze použít placené makro „Filtr tabulek“.

Do tohoto makra je třeba vložit tabulku (může být i ta nejhorší, hlavně ji nacpat celou). V makru můžete vybrat sloupce pro filtr z rozbalovacího seznamu, textového filtru, číselného a filtru podle dat.

Představte si, že všechny informace o uchazečích o všechny pracovní pozice jsou zapisovány v tabulkovém seznamu. Samozřejmě neřazeným – lidé přece na pohovory nechodí podle abecedy. A vy potřebujete zjistit, jestli jste už dříve pohovorovali s konkrétním uchazečem. Stačí tento chaos vložit do filtračního makra, přidat textový filtr podle příjmení – a voilà, informace máte na obrazovce.

Je třeba poznamenat, že filtrování velkých tabulek může ovlivnit výkon systému a dobu načítání stránek, proto zasouvání obrovské tabulky do filtru je dočasné řešení; lépe je vybudovat proces, ve kterém lidé nemusí vytvářet obrovské nečitelná tabulky (příklad procesu bude na konci článku).

Třídění (placený plugin)

Pomocí kouzelného makra „Filtr tabulek“ je také možné nastavit výchozí třídění podle libovolného sloupce a očíslovat řádky. Nebo klikněte na libovolný sloupec tabulky zasunuté do filtračního makra a provede se třídění podle tohoto sloupce.

Například máte stejnou tabulku se žadateli a potřebujete odhadnout, kolik pohovorů proběhlo v určitém měsíci – tříděte podle data a radujte se.

Pivotní tabulky (placený plugin)

Nyní přejdeme k zajímavějšímu případu. Představte si, že vaše tabulka je obrovská a potřebujete něco spočítat. Samozřejmě, můžete ji zkopírovat do Excelu, spočítat potřebné a data vložit zpět do Confluence. Ale můžete jednou použít makro „Pivotní tabulka“ a získat stejný výsledek, který se navíc aktualizuje.

Například: máte tabulku, v níž jsou shromážděna data všech zaměstnanců – kde se geograficky nacházejí a jaké mají pozice. Abychom spočítali, kolik lidí je v každém městě, musíte v makru „Pivotní tabulka“ vybrat řádek, podle kterého se data agregují (umístění) a typ operace (sčítání).

Samozřejmě, že je možné skupinovat podle několika kritérií současně, všechny možnosti si můžete prohlédnout. v dokumentaci.

Grafy (placený plugin)

Jak už jsem řekla, ne všichni milují tabulky tak, jako já. Bohužel manažeři je většinou vůbec nemají rádi. Na druhou stranu všichni milují jasné barevné grafy.
Tvůrci Confluence o tom určitě věděli (určitě mají také nadřízené, kteří mají rádi zprávy a grafy, kam by bez nich). Proto můžete využít kouzelného makra „Graf z tabulky“. Do tohoto makra je třeba vložit pivotní tabulku z předchozího bodu a voilà – vaše šedá nudná data jsou krásně vizualizována.

Samozřejmě, že v tomto makru jsou také nastavení. Odkaz na dokumentaci k jakémukoli makru můžete najít v režimu úpravy tohoto makra.

Jednoduchost agregace

Informace z předchozích bodů pro vás pravděpodobně nebyly překvapením. Ale nyní už určitě víte, jak používat makra, a já se mohu přesunout k zajímavější části článku.

Štítky

Špatně je, když lidé uchovávají informace v jedné nestrukturované článku nebo obrovské tabulce. Ještě horší je, když jsou části těchto informací nejen nečitelně formátovány, ale také rozptýleny po prostorních Confluence. Naštěstí existuje možnost shromáždit rozptýlené informace na jednom místě. K tomu je třeba využít štítky (známé všem z sociálních sítí tagy).

Na kteroukoliv stránku můžete přidat libovolné množství štítků. Když na štítek kliknete, dostanete se na stránku agregace, kde jsou odkazy na všechny materiály s tímto štítkem, a také na soubor souvisejících štítků. Související štítky jsou ty, které se často objevují na jedné stránce.

Vlastnosti stránek

Na stránku můžete přidat další zajímavé makro pro strukturování informací — „Vlastnosti stránek“. Do něj je potřeba poskytnout tabulku ze dvou sloupců, přičemž první bude klíčem a druhý hodnotou vlastnosti. Makro může být skryto na stránce, aby nerušilo čtení obsahu, ale stránka bude stále označena potřebnými klíči.

Všimněte si ID — je výhodné jej definovat, abyste přiřadili různé skupiny vlastností různým stránkám (nebo dokonce různé skupiny vlastností na jednu stránku).

Zprávy

Podle štítků můžete vytvářet zprávy. Například makro „Zpráva o obsahu“ shromažďuje všechny stránky s určitým souborem štítků.

Ale zajímavější zprávou je makro „Zpráva o vlastnostech stránky“. To také shromažďuje všechny stránky s určitým souborem štítků, ale nejenže zobrazí jejich seznam, ale vytvoří tabulku (chápete spojení s začátkem článku?), kde jsou sloupce klíči vlastností stránky.

Vznikne souhrnná tabulka informací z různých zdrojů. Je příjemné, že má pohodlné funkce: responzivní design, třídění podle jakéhokoliv sloupce. Takovou zprávu lze také konfigurovat v rámci makra.

Při konfiguraci můžete ze zprávy odstranit některé sloupce, nastavit stav podle výchozího stavu nebo počet zobrazených záznamů. A můžete také nastavit ID vlastnosti stránky, abyste viděli pouze potřebné informace.

Například máte mnoho stránek zaměstnanců, které mají sadu vlastností týkajících se osoby: jaké má úrovně, kde se nachází, kdy přišel do týmu a tak dále. Tyto vlastnosti jsou označeny ID = employee_inf. A existuje druhá sada vlastností na téže stránce, kde je shromážděna informace o osobě jako o části týmu: jakou roli osoba vykonává, v jakém týmu se nachází a tak dále. Tyto vlastnosti jsou označeny ID = team_inf. Když sestavujete zprávu, můžete zobrazit pouze informace podle jednoho ID nebo rovnou podle dvou — jak vám to bude pohodlnější.

Kouzlo tohoto přístupu spočívá v tom, že si každý může sestavit potřebnou informační tabulku, která nebude nic duplicovat a bude se aktualizovat při aktualizaci hlavní stránky. Například: týmový vedoucí se nemusí zajímat o to, kdy jeho vývojáři nastoupili do práce, ale důležitá je pro něj role každého z nich v týmu. Týmový vedoucí si sestaví zprávu podle týmu. A účetnímu je úplně jedno, kdo jakou roli vykonává, ale důležité jsou pozice — on si sestaví zprávu podle pozic. Přitom zdroj informací nebude duplicován ani přesouván.

Konečný proces

Návod

Takže můžeme pěkně strukturovat a efektivně agregovat informace v Confluence na příkladu použití makr. Ale ideálně by mělo být cílem, aby nové informace okamžitě byly strukturované a dostávaly se do všech již používaných mechanismů agregace.

S tím pomůže kombinace makr a šablon. Abyste donutili lidi vytvářet nové stránky v požadovaném formátu, můžete použít makro „Vytvořit ze šablony“. Přidá na stránku tlačítko, po jehož stisknutí se vytvoří nová stránka z vaší požadované šablony. Tímto způsobem donutíte lidi okamžitě pracovat ve formátu, který potřebujete.

Do šablony, ze které dáváte možnost vytvářet stránku, je třeba předem přidat štítky, makro „Vlastnosti stránky“ a tabulku potřebných vlastností. Také doporučuji přidat instrukce o tom, jaké hodnoty by měly být do stránky vyplněny, a hodnoty vlastností.

Takže konečný proces bude vypadat takto:

Vytváříte šablonu pro informace určitého typu.
Do této šablony přidáte štítky a vlastnosti stránky v makru.
V jakémkoli pohodlném místě vytvoříte hlavní stránku s tlačítkem, po kliknutí na které se vytvoří podřízená stránka z šablony.
Na hlavní stránku pustíte uživatele, kteří potenciálně budou generovat potřebné informace (podle požadované šablony, stisknutím tlačítka).
Sestavíte si report podle vlastností stránky prostřednictvím štítků, které jste uvedli v šabloně.
Těšíte se: máte všechny potřebné informace v pohodlném formátu.

Úskalí

Jako inženýr kvality mohu s jistotou tvrdit, že nic dokonalého na světě neexistuje. Dokonce ani božské tabulky nejsou dokonalé. A v uvedeném procesu existují úskalí.

Pokud se rozhodnete změnit názvy nebo sestavu vlastností stránky, budete muset aktualizovat všechny již vytvořené objekty, aby se jejich data správně převedla do souhrnného reportu. To je smutné, ale na druhou stranu to nutí důkladně promyslet "architekturu" vaší datové sady, což je velmi zajímavý úkol.
Budete muset napsat slušné množství pokynů o tom, jak vyplňovat informační tabulky a používat štítky. Ale na druhou stranu, můžete jednoduše poslat tuto stránku všem potřebným lidem.

Příklad uchovávání neproduktové dokumentace

Díky výše popsanému procesu lze organizovat uchovávání téměř jakýchkoli informací. Krása tohoto přístupu spočívá v jeho univerzálnosti: když si na něj uživatelé zvyknou, přestanou generovat nepořádek. Také velkým (ale ne bezplatným) plusem je možnost sbírat na běhu různou statistiku a vytvářet z ní krásné grafy.

Uvedu příklad našeho procesu sledování informací o týmu.

Pro každou osobu v týmu jsme se rozhodli vytvořit kartu zaměstnance. Tím pádem máme šablonu, podle které si každý nový člen vytváří tuto kartu a vede v ní všechny osobní informace.

Jak vidíte, máme rozvinutou tabulku vlastností a hned jsou zde pokyny, jak přesně vést tuto stránku. Část štítků vyplňují sami zaměstnanci podle pokynů, ve šabloně jsou pouze základní: štítek karty employee-card, štítek směru direction-involve a štítek týmu team-qa.

Nakonec, poté co si každý vytvoří svou kartu, získáme kompletní tabulku s informacemi o zaměstnancích. Tyto informace lze využít na různých místech. Resource manažeři si mohou sestavit společné tabulky, zatímco vedoucí týmů mohou vytvářet týmové tabulky přidáním týmového tagu do výběru.

Podle tagů lze vidět různé shrnutí, například podle qa-upgrade-plan se zobrazí všechny úkoly na rozvoj QA. Každý člověk na své kartě zaměstnance přitom vede důležitý příběh a svůj plán rozvoje – vytváří podstránku z šablony plánů rozvoje.