🥇Navrhovanie v Confluence

Ahojte všetci!

Volám sa Masha, pracujem ako inžinier kvality v skupine Tinkoff. Práca QA zahŕňa množstvo komunikácie s rôznymi ľuďmi z rôznych tímov, a navyše som bola manažérka a lektorka vzdelávacích programov, preto moja komunikačná mapa bola maximálne široká. A v istom momente som vybuchla: uvedomila som si, že viac nemôžem, nemôžem, nemôžem vyplniť hrozné tony nečitateľných tabuliek a dokumentov.

Určite si každý z vás teraz predstavil to, o čom hovorím, a zalial sa studeným potom: zoznamy priezvisk bez abecedného poradia, tabuľky so stovkami stĺpcov so zle formátovaným textom, tabuľky s tisícami riadkov, v ktorých si musíte trénovať prst o koliesko myši, aby ste videli nadpis, tony stránok nepodian numerovaných pokynov, stovky správ posielaných rôzne s dátami, ktoré je potrebné analyzovať a systémovo zorganizovať a natlačiť do rovnakých nečitateľných tabuliek.

A tak, keď som sa trochu upokojila, rozhodla som sa napísať tento článok. Povieme si, ako normálne (aj občas pohodlne) viesť rôznu neproduktovú dokumentáciu. Dúfam, že článok sa rozšíri po sieti a úroveň chaosu v oddeleniach susediacich s vývojom sa aspoň trošku zníži, a ľudia (a ja vrátane) sa stanú o čosi šťastnejší.

Nástroje

Produktová dokumentácia sa často uchováva vedľa kódu, a to je dobré. A neproduktová dokumentácia sa zvyčajne uchováva kdekoľvek. Často sa ľudia snažia prenášať informácie z rôznych miest do Confluence, a my nie sme výnimkou. Takže celý ďalší príbeh o ňom.

V podstate je Confluence pokročilý wiki engine. Umožňuje pracovať s údajmi v rôznych formách zobrazenia: text s formátovaním, tabuľky, rôzne diagramy. Je to veľmi zaujímavý a mocný nástroj, ale ak neviete, ako ho pripraviť, získate iba ďalší zmätok nečitateľných dokumentov. Naučím vás, ako na to!

Makrá

Takmer všetka mágia Confluence je postavená na makrách. Existuje veľmi veľa makier a môžu sa kombinovať navzájom. Sú platené aj bezplatné, ďalej budú rôzne príklady mák s odkazmi na dokumentáciu k nim.

Používateľské rozhranie pre prácu s makrami je maximálne jednoduché. Aby ste pridali makro, stačí kliknúť na plus a vybrať potrebný prvok zo zoznamu.

Ak je makro samostatné, teda nevyžaduje vloženie niečoho iného do seba, vyzerá ako blok.

Ak na fungovanie makra potrebujete niečo vložiť dovnútra, vyzerá ako rám.

Dovnútra jedného rámu môžete umiestniť viacero iných, pokým v pyramíde bude logika.

Každé makro má náhľad: okamžite vidíte, či ste správne vyplnili a nastavili makro.

Šablóny

Okrem makier existuje aj užitočný nástroj na predvyplnenie obsahu – to sú šablóny.
Šablóny môžete používať pri vytváraní akejkoľvek stránky: stačí kliknúť na tri bodky vedľa tlačidla „Vytvoriť“ a vybrať potrebnú šablónu.

Potom sa do vytvorenej stránky pridá celý obsah, ktorý je v šablóne.

Stránky zo šablón môže vytvárať ktokoľvek, ale vytvárať alebo upravovať samotné šablóny môžu len tí, ktorí na to majú práva. Do šablóny môžete pridať ďalšie pokyny o tom, ako by sa mala stránka viesť.

Kúzlo tabuliek

Vlastne, ako technik, milujem tabuľky a môžem takmer akékoľvek informácie v nich zabalit (aj keď to nie vždy je efektívne). Samé o sebe sú tabuľky jasné, štruktúrované, škálovateľné, magické!

Ale aj takú úžasnú entitu, ako tabuľka, môžete pokaziť. Ale môžete ju aj šikovne využiť a dokonca vylepšiť. O tom nižšie.

Filtrovanie (platený plugin)

Akúkoľvek obrovskú, nečitateľnú tabuľku môžete urobiť trochu menej obrovskou a trochu čitateľnejšou pomocou filtrovania. Na to môžete použiť platené makro. „Filter tabuliek“.

Dovnútra tohto makra musíte vložiť tabuľku (môže to byť dokonca tá najšerednejšia, dôležité je zažiť ju celú). V makre môžete zvoliť stĺpce na filtrovanie z rozbaľovacieho zoznamu, textového filtra, numerického a filtra podľa dátumov.

Predstavte si, že všetky informácie o kandidátoch na všetky voľné miesta sú zaznamenané tabulkovým spôsobom. Samozrejme, nesú zoradené — ľudia predsa nechodí na pohovory podľa abecedy. A vy potrebujete pochopiť, či ste sa už s konkrétnym uchádzačom pohovorili. Stačí to všetko vložiť do filtračného makra, pridať textový filter podľa priezviska — a vuala, informácie sú na vašej obrazovke.

Je dôležité poznamenať, že filtrovanie veľkých tabuliek môže ovplyvniť výkon systému a čas načítania stránok, takže umiestniť obrovskú tabuľku do filtra je dočasné riešenie. Je lepšie vytvoriť proces, v ktorom ľudia nemusia vytvárať obrovské nečitateľné tabuľky (príklad procesu bude na konci článku).

Triedenie (platený plugin)

S pomocou čarovného makra „Filter tabuliek“ môžete tiež nastaviť predvolené triedenie podľa ľubovoľného stĺpca a očíslovať riadky. Alebo kliknúť na akýkoľvek stĺpec tabuľky, ktorá je umiestnená v makre filtra, a dôjde k triedeniu podľa tohto stĺpca.

Napríklad, máte tú istú tabuľku s uchádzačmi a potrebujete zistiť, koľko pohovorov sa uskutočnilo v určitom mesiaci — triedte podľa dátumu a tešte sa.

Pivotové tabuľky (platený plugin)

Teraz prejdeme k zaujímavejšiemu prípadu. Predstavte si, že vaša tabuľka je obrovská a potrebujete niečo si vypočítať. Samozrejme, môžete ju skopírovať do Excelu, vypočítať potrebné a preniesť údaje späť do Confluence. Alebo môžete raz použiť makro „Pivotová tabuľka“ a získať rovnaký výsledok, lenže aktualizovaný.

Napríklad: máte tabuľku, v ktorej sú zhromaždené údaje všetkých zamestnancov — kde sa nachádzajú geograficky a aké majú pozície. Aby ste zistili, koľko ľudí sa nachádza v každom meste, musíte v makre „Pivotová tabuľka“ vybrať riadok, podľa ktorého sa aggregujú údaje (miesto) a typ operácie (sčítanie).

Samozrejme, môžete skupinovať aj podľa viacerých kritérií naraz, všetky možnosti si môžete pozrieť v dokumentácii.

Grafy (platený plugin)

Ako som už povedala, nie každý má tak rád tabuľky ako ja. Bohužiaľ, manažéri ich väčšinou vôbec nemajú radi. Ale všetci veľmi milujú jasné farebné grafy.
Tvorcovia Confluence o tom samozrejme vedeli (určite aj oni majú nadriadených, ktorí milujú správy a grafy, kam by to bez nich šlo). Preto je možné využiť čarovné makro „Graf z tabuľky“. Do tohto makra treba vložiť pivotovú tabuľku z predchádzajúceho bodu, a voilà — vaše šedé nudné údaje sú pekne vizualizované.

Samozrejme, v tomto makre sú tiež nastavenia. Odkaz na dokumentáciu k akémukoľvek makru nájdete v režime úprav tohto makra.

Jednoduchosť agregácie

Informácie z predchádzajúcich bodov pre vás určite neboli prekvapením. Ale teraz určite viete, ako používať makrá, a ja sa môžem presunúť k zaujímavejšej časti článku.

Štítky

Je zlé, keď si ľudia uchovávajú informácie v jednej neštruktúrovanej článku alebo obrovskej tabuľke. Ešte horšie je, keď sú časti týchto informácií nielen zle usporiadané, ale aj roztrúsené po rozhraní Confluence. Našťastie existuje možnosť zhromaždiť roztrúsené informácie na jednom mieste. Na to je potrebné využiť štítky (známe z sociálnych sietí ako tagy).

Na akúkoľvek stránku môžete pridať neobmedzené množstvo štítkov. Ak kliknete na štítok, dostanete sa na stránku agregácie, kde sú odkazy na všetky materiály s týmto štítkom, ako aj na sadzbu súvisiacich štítkov. Súvisiace štítky sú tie, ktoré sa často nachádzajú na jednej stránke.

Vlastnosti stránok

Na stránku môžete pridať ešte jeden zaujímavý makro na štruktúrovanie informácií — „Vlastnosti stránok“. Do neho je potrebné zadať tabuľku z dvoch stĺpcov, prvý bude kľúč, a druhý — hodnota vlastnosti. Makro môžete skrývať zo stránky, aby neprekážalo pri čítaní obsahu, ale stránka bude aj tak označená potrebnými kľúčmi.

Venujte pozornosť ID — je pohodlné ho nastavovať, aby ste mohli priradiť rôzne skupiny vlastností rôznym stránkam (alebo dokonca rôzne skupiny vlastností na jednu stránku).

Správy

Podľa štítkov je možné zhromažďovať správy. Napríklad, makro „Správa o obsahu“ zhromažďuje všetky stránky s určitým súborom štítkov.

Ale zaujímavejšia správa je makro „Správa o vlastnostiach stránky“. Tiež zhromažďuje všetky stránky s určitým súborom štítkov, ale nielen, že zobrazuje ich zoznam, ale vytvára tabuľku (poberáte súvis s začiatkom článku?), v ktorej sú stĺpce kľúče vlastností stránky.

Vytvára sa kontingenčná tabuľka na informácie z rôznych zdrojov. Rádo, že má pohodlné funkcie: responzívny dizajn, triedenie podľa akéhokoľvek stĺpca. Túto správu tabuľky je možné konfigurovať aj v rámci makra.

Pri konfigurácii je možné z správy odstrániť niektoré stĺpce, nastaviť predvolený stav alebo počet zobrazených záznamov. A môžete tiež nastaviť ID vlastnosti stránky, aby ste videli iba potrebné informácie.

Napríklad máte množstvo stránok zamestnancov, pričom tieto stránky majú súbor vlastností o osobe: akú má úroveň, kde sa nachádza, kedy prišiel do tímu a podobne. Tieto vlastnosti sú označené ID = employee_inf. A existuje druhý súbor vlastností na tej istej stránke, ktorý zhromažďuje informácie o osobe ako o súčasti tímu: akú úlohu osoba vykonáva, v akom tíme sa nachádza a podobne. Tieto vlastnosti sú označené ID = team_inf. Takže pri zostavovaní správy môžete zobraziť iba informácie podľa jedného identifikačného čísla alebo naraz podľa dvoch — ako je to pohodlnejšie.

Kúzlo tohto prístupu spočíva v tom, že každý si môže zostaviť potrebnú informačnú tabuľku, ktorá nič nebude duplicovať a bude sa aktualizovať pri aktualizácii hlavnej stránky. Napríklad: tímový líder sa nemusí zaujímať, kedy sa jeho vývojári zamestnali, ale je pre neho dôležité, akú úlohu každý z nich vykonáva v tíme. Tímový líder si zostaví správu podľa tímu. A účtovníkovi je úplne jedno, kto akú úlohu vykonáva, ale dôležité sú pozície — on si zostaví správu podľa pozícií. Pri tom nebude zdroj informácií duplicovaný ani presúvaný.

Záverečný proces

Návod

Takže môžeme pekne štruktúrovať a efektívne agregovať informácie v Confluence na príklade využitia makier. Ale v ideále by sa malo urobiť tak, aby nové informácie boli hneď štruktúrované a dostávali sa do všetkých už používaných mechanizmov agregácie.

Tu na pomoc príde kombinácia makier a šablón. Aby ste prinútili ľudí vytvárať nové stránky v požadovanom formáte, môžete využiť makro „Vytvoriť zo šablóny“. To pridáva na stránku tlačidlo, po stlačení ktorého sa vytvorí nová stránka z požadovanej šablóny. Takto nútite ľudí okamžite pracovať v požadovanom formáte.

Do šablóny, z ktorej dávate vytvárať stránku, musíte vopred pridať značky, makro „Vlastnosti stránky“ a tabuľku požadovaných vlastností. Takisto odporúčam pridať pokyny, akými hodnotami treba stránku naplniť, a hodnoty vlastností.

Takže konečný proces bude vyzerať takto:

Vytvárate šablónu pre informácie určitý typ.
Do tejto šablóny pridáte značky a vlastnosti stránky v makre.
Na akomkoľvek vhodnom mieste vytvorte hlavnú stránku s tlačidlom, po ktorom kliknutí sa vytvorí podstránka z šablóny.
Na hlavnú stránku pustíte používateľov, ktorí potenciálne budú generovať potrebné informácie (dľa požadovanej šablóny, kliknutím na tlačidlo).
Zbierate si správu o vlastnostiach stránky prostredníctvom značiek, ktoré ste uviedli v šablóne.
Tešíte sa: máte všetky potrebné informácie v pohodlnom formáte.

Úskalí

Ako kvalitár môžem smelo tvrdiť, že nič dokonalé na svete neexistuje. Dokonca ani božské tabulky nie sú dokonalé. A v uvedenom procese sú skryté úskalia.

Ak sa rozhodnete zmeniť názvy alebo zloženie vlastností stránky, budete musieť aktualizovať všetky už vytvorené objekty, aby sa ich údaje správne preniesli do sumarizačnej správy. Je to smutné, ale na druhej strane to núti podrobne premyslieť "architektúru" vašej sady informácií, čo je veľmi zaujímavá úloha.
Bude potrebné napísať rozumné množstvo pokynov o tom, ako vyplniť informačné tabuľky a používať značky. Na druhej strane, môžete jednoducho poslať tým potrebným ľuďom tento článok.

Príklad uchovávania neproduktuovej dokumentácie

Cez uvedený proces je možné organizovať uchovávanie takmer akýchkoľvek informácií. Krásou prístupu je, že je univerzálny: keď si naň používatelia zvyknú, prestanú generovať chaos. Taktiež je veľkým (ale nie bezplatným) plusom možnosť zbierať naživo rôznu štatistiku a kresliť na jej základe pekné diagramy.

Privediem príklad nášho procesu vedenia informácií o tíme.

Pre každého člena tímu sme sa rozhodli vytvoriť kartu zamestnanca. Podľa toho máme šablónu, podľa ktorej každý nový človek vytvorí túto kartu a vedie v nej všetky osobné informácie.

Ako vidíte, máme rozšírenú tabuľku vlastností a hneď sú tam pokyny, ako presne viesť túto stránku. Časť značiek umiestňujú sami zamestnanci podľa pokynov, v šablóne sú len hlavné: značka karty employee-card, značka smerovania direction-involve a značka tímu team-qa.

Po tom, čo si každý vytvoril svoju kartu, vznikne kompletná tabuľka s informáciami o zamestnancoch. Tieto informácie je možné využiť na rôznych miestach. Manažéri zdrojov si môžu zostaviť všeobecné tabuľky, zatiaľ čo lídrí tímov — tímové tabuľky, pričom do výberu pridávajú tímový tag.

Podľa tagov môžete vidieť rôzne súhrny, napríklad podľa qa-upgrade-plan sa zobrazia všetky úlohy na rozvoj QA. Každý človek vo svojej zamestnaneckej karte vedie dôležitý príbeh a svoj plán rozvoja — vytvára podstránku zo šablóny plánov rozvoja.