Ahoj všetci!
Volám sa Masha, pracujem ako inžinier zabezpečenia kvality v skupine spoločností Tinkoff. Práca v oblasti QA zahŕňa veľa komunikácie s rôznymi ľuďmi z rôznych tímov a bola som aj manažérkou a lektorkou vzdelávacích programov, takže moja komunikačná mapa bola čo najširšia. A v určitom okamihu som vybuchol: uvedomil som si, že nemôžem, nemôžem, nemôžem vyplniť pekelné tony nečitateľných tabuliek a dokumentov.
Určite si teraz každý z vás predstavil o čom hovorím a oblial ma studený pot: zoznamy priezvisk bez abecedného poradia, tabuľky so stovkami stĺpcov s krivým rozložením, tabuľky s tisíckami riadkov, do ktorých si treba utrieť prst na koliesku myši pozrieť hlavičku, tony strán nečíslovaných inštrukcií, stovky listov, ktoré si navzájom posielajú s údajmi, ktoré treba analyzovať a systematizovať a napchať do rovnako nečitateľných tabuliek.
A tak, keď som trochu vychladol, rozhodol som sa napísať tento článok. Budem hovoriť o tom, ako môžete normálne (dokonca niekedy pohodlne) udržiavať rôzne dokumentácie, ktoré sa netýkajú produktu. Dúfam, že sa článok rozšíri po internete a úroveň pekla v oddeleniach susediacich s vývojom sa aspoň trochu zníži a ľudia (vrátane mňa) budú o niečo šťastnejší.
Nástroje
Dokumentácia k produktu sa často nachádza vedľa kódu, čo je dobrá vec. A neproduktová dokumentácia je zvyčajne uložená kdekoľvek. Ľudia sa často snažia do Confluence presúvať informácie z rôznych miest a my nie sme výnimkou. Takže zvyšok príbehu je o ňom.
Vo všeobecnosti je Confluence pokročilý wiki engine. Umožňuje vám pracovať s údajmi v rôznych typoch zobrazenia: text s formátovaním, tabuľky, rôzne grafy. Je to veľmi zaujímavý a výkonný nástroj, ale ak neviete, ako ho pripraviť, skončíte s ďalšou skládkou nečitateľných dokumentov. Naučím ťa variť!
Makrá
Takmer všetka mágia Confluence pochádza z makier. Makrá je veľa a dajú sa navzájom kombinovať. Môžu byť platené alebo bezplatné, nižšie budú uvedené rôzne príklady makier s odkazmi na dokumentáciu k nim.
Rozhranie pre prácu s makrami je maximálne jednoduché. Ak chcete pridať makro, musíte kliknúť na znamienko plus a vybrať požadovaný prvok zo zoznamu.
Ak je makro samostatné, to znamená, že nevyžaduje vloženie ničoho iného do seba, vyzerá ako blok.
Ak makro vyžaduje, aby sa do neho niečo umiestnilo, aby fungovalo, vyzerá ako rám.
Zároveň môžete do jedného rámu umiestniť toľko ďalších, koľko chcete, pokiaľ je vo vašej pyramíde logika.
Každé makro má náhľad: okamžite sa zobrazí, či ste makro správne vyplnili a nakonfigurovali.
šablóny
Okrem makier existuje pohodlný nástroj na predvyplnenie obsahu – šablóna.
Šablóny je možné použiť pri vytváraní akejkoľvek stránky: stačí kliknúť na tri bodky vedľa tlačidla „Vytvoriť“ a vybrať požadovanú šablónu.
Potom sa všetok obsah, ktorý je v šablóne, pridá na vytvorenú stránku.
Stránky zo šablón môže vytvárať ktokoľvek, ale iba tí, ktorí majú práva na vytváranie alebo úpravu šablón sami. Do šablóny môžete pridať ďalšie pokyny o tom, ako sa má stránka udržiavať.
Kúzlo stolov
V skutočnosti ako technik veľmi milujem tabuľky a dokážem do nich zabaliť takmer akúkoľvek informáciu (aj keď to nie je vždy efektívne). Samotné tabuľky sú prehľadné, štruktúrované, škálovateľné, magické!
Ale aj taká úžasná entita, akou je stôl, môže byť zničená. A môžete ho úspešne používať a dokonca vylepšovať. Viac o tom nižšie.
Filtrovanie (platený doplnok)
Akákoľvek obrovská, nečitateľná tabuľka môže byť pomocou filtrovania o niečo menej veľká a o niečo čitateľnejšia. Na to môžete použiť platené makro .
Do tohto makra musíte vložiť tabuľku (aj tá najškaredšia je možná, hlavné je natlačiť ju celú). V makre môžete vybrať stĺpce pre rozbaľovací filter, textový filter, číselný filter a dátumový filter.
Len si predstavte, že všetky informácie o kandidátoch na všetky voľné miesta sú zaznamenané v tabuľkovom zozname. Prirodzene, netriedené – ľudia prichádzajú na pohovory nie v abecednom poradí. A musíte pochopiť, či ste už predtým viedli pohovor s konkrétnym žiadateľom. Stačí vložiť toto peklo do makra filtra, pridať textový filter podľa priezviska – a voila, informácie sú na vašej obrazovke.
Stojí za zmienku, že filtrovanie veľkých tabuliek môže ovplyvniť výkon systému a časy načítania stránok, takže umiestnenie veľkej tabuľky do filtra je dočasnou barličkou; je lepšie vytvoriť proces, v ktorom ľudia nebudú musieť vytvárať obrovské nečitateľné tabuľky (napr. príklad postupu bude na konci článku).
Triedenie (platený doplnok)
Pomocou magického makra Môžete tiež nastaviť predvolené zoradenie pre ľubovoľný stĺpec a očíslovať riadky. Alebo kliknite na ktorýkoľvek stĺpec tabuľky vložený do makra filtra a zoradenie sa uskutoční podľa tohto stĺpca.
Napríklad máte rovnakú tabuľku s uchádzačmi a potrebujete odhadnúť, koľko pohovorov prebehlo v určitom mesiaci – zoradiť podľa dátumu a mať radosť.
Kontingenčné tabuľky (platený doplnok)
Teraz prejdime k zaujímavejšiemu prípadu. Predstavte si, že váš stôl je obrovský a potrebujete z neho niečo vypočítať. Samozrejme, môžete si to skopírovať do Excelu, vypočítať, čo potrebujete a nahrať dáta späť do Confluence. Môžete použiť makro raz? a získate rovnaký výsledok, len aktualizovaný.
Napríklad: máte tabuľku, ktorá zhromažďuje údaje od všetkých zamestnancov – kde sa geograficky nachádzajú a aké pozície zastávajú. Ak chcete vypočítať, koľko ľudí je v každom meste, musíte vybrať riadok v makre kontingenčnej tabuľky, ktorý agreguje údaje (miesto) a typ operácie (doplnenie).
Prirodzene, môžete zoskupovať podľa viacerých kritérií naraz, je možné zobraziť všetky možnosti .
Grafy (platený doplnok)
Ako som povedal, nie každý miluje stoly tak ako ja. Bohužiaľ, väčšina manažérov ich vôbec nemá rada. Ale každý naozaj miluje jasné farebné diagramy.
Svoje o tom určite vedeli aj tvorcovia Confluence (asi majú aj šéfov, ktorí milujú reporty a diagramy, kde by bez toho boli). Preto môžete použiť magické makro . Do tohto makra musíte vložiť kontingenčnú tabuľku z predchádzajúceho odseku a voila - vaše šedé nudné údaje sú krásne vizualizované.
Toto makro má samozrejme aj nastavenia. Odkaz na dokumentáciu pre každé makro možno nájsť v režime úprav daného makra.
Ľahká agregácia
Informácie z predchádzajúcich odsekov pre vás zrejme neboli zjavením. Teraz však už určite viete, ako používať makrá, a môžem prejsť k zaujímavejšej časti článku.
Tagy
Je zlé, keď ľudia ukladajú informácie do jedného neštruktúrovaného článku alebo obrovskej tabuľky. Je to ešte horšie, keď sú časti týchto informácií nielen nečitateľne naformátované, ale aj roztrúsené po celom Confluence. Našťastie je možné zhromaždiť rozptýlené informácie na jednom mieste. Ak to chcete urobiť, musíte použiť (značky známe každému zo sociálnych sietí).
Na ľubovoľnú stránku môžete pridať ľubovoľný počet značiek. Kliknutím na značku sa dostanete na stránku agregácie s odkazmi na všetok obsah s touto značkou, ako aj so súpravou súvisiacich značiek. Súvisiace značky sú tie, ktoré sa často objavujú na tej istej stránke.
Vlastnosti stránky
Na stránku môžete pridať ďalšie zaujímavé makro na štruktúrovanie informácií - . Vnútri musíte odoslať tabuľku dvoch stĺpcov, prvý bude kľúč a druhý bude hodnota vlastnosti. Makro je navyše možné zo stránky skryť, aby neprekážalo pri čítaní obsahu, ale stránka bude stále označená potrebnými klávesmi.
Pozor na ID – je vhodné si ho nastaviť tak, aby rôznym stránkam priraďoval rôzne skupiny vlastností (alebo aj rôzne skupiny vlastností jednej stránke).
správy
Prehľady môžete zhromažďovať pomocou značiek. Napríklad makro zhromažďuje všetky stránky so špecifickou sadou značiek.
Zaujímavejšou správou je však makro . Zhromažďuje aj všetky stránky s určitou sadou tagov, ale nezobrazuje len ich zoznam, ale vytvára tabuľku (chytíte súvislosť so začiatkom článku?), v ktorej sú stĺpce stránka majetkové kľúče.
Výsledkom je súhrnná tabuľka informácií z rôznych zdrojov. Je pekné, že má pohodlné funkcie: adaptívne rozloženie, triedenie podľa ľubovoľného stĺpca. Takáto tabuľka prehľadov môže byť tiež nakonfigurovaná vo vnútri makra.
Pri konfigurácii môžete z prehľadu odstrániť niektoré stĺpce, nastaviť predvolený stav alebo počet zobrazených záznamov. Môžete tiež nastaviť ID vlastnosti stránky, aby ste videli iba informácie, ktoré potrebujete.
Napríklad máte veľa stránok zamestnancov, tieto stránky majú súbor vlastností o danej osobe: aká je úroveň, kde je, kedy sa pripojil k tímu atď. Tieto vlastnosti sú označené ID = zamestnanec_inf. A na tej istej stránke je druhý súbor vlastností, ktorý obsahuje informácie o osobe ako súčasti tímu: akú rolu osoba hrá, v akom tíme je atď. Tieto vlastnosti sú označené ID = team_inf. Potom pri zostavovaní prehľadu môžete zobraziť len informácie pre jedno ID alebo dve naraz – podľa toho, čo je výhodnejšie.
Krása tohto prístupu spočíva v tom, že každý si môže zostaviť informačnú tabuľku, akú potrebuje, ktorá nebude nič duplikovať a bude aktualizovaná pri aktualizácii hlavnej stránky. Napríklad: pre vedúceho tímu nezáleží na tom, kedy jeho vývojári dostali prácu, ale je dôležité, akú úlohu každý z nich v tíme hrá. Vedúci tímu zozbiera správu o tíme. A účtovníkovi je vo všeobecnosti jedno, kto akú úlohu vykonáva, ale dôležité sú pozície – zostaví správu o pozíciách. V tomto prípade nebude zdroj informácií duplikovaný ani prenesený.
Záverečný proces
Inštrukcie
Takže môžeme krásne štruktúrovať a efektívne agregovať informácie v Confluence pomocou makier ako príkladu. V ideálnom prípade sa však musíte uistiť, že nové informácie sú okamžite štruktúrované a spadajú do všetkých už používaných agregačných mechanizmov.
Tu príde na pomoc hromada makier a šablón. Ak chcete ľudí prinútiť vytvárať nové stránky v požadovanom formáte, môžete použiť makro Vytvoriť zo šablóny. Na stránku pridá tlačidlo, po kliknutí sa vytvorí nová stránka zo šablóny, ktorú potrebujete. Týmto spôsobom prinútite ľudí okamžite pracovať vo formáte, ktorý potrebujete.
Do šablóny, z ktorej vytvárate stránku, musíte vopred pridať štítky, makro „Vlastnosti stránky“ a tabuľku vlastností, ktoré potrebujete. Odporúčam tiež pridať pokyny, aké hodnoty by sa mali na stránke vyplniť a hodnoty vlastností.
Potom bude konečný proces vyzerať takto:
- Vytvoríte šablónu pre konkrétny typ informácií.
- V tejto šablóne pridáte štítky a vlastnosti stránky do makra.
- Na akomkoľvek vhodnom mieste vytvorte koreňovú stránku pomocou tlačidla, kliknutím na ktoré sa vytvorí podradená stránka zo šablóny.
- Používateľom umožníte prejsť na koreňovú stránku, ktorá potenciálne vygeneruje potrebné informácie (podľa požadovanej šablóny kliknutím na tlačidlo).
- Prehľad o vlastnostiach stránky zhromažďujete pomocou značiek, ktoré ste zadali v šablóne.
- Radujte sa: všetky potrebné informácie máte vo vhodnom formáte.
Úskalia
Ako inžinier kvality môžem pokojne povedať, že nič na svete nie je dokonalé. Aj božské stoly sú nedokonalé. A vo vyššie uvedenom procese existujú úskalia.
- Ak sa rozhodnete zmeniť názvy alebo zloženie vlastností stránky, budete musieť aktualizovať všetky už vytvorené objekty, aby boli ich údaje správne zahrnuté v súhrnnom výkaze. Je to smutné, ale na druhej strane vás to núti detailne premýšľať o „architektúre“ vášho súboru informácií, čo je veľmi zaujímavá úloha.
- Budete musieť napísať poriadne množstvo návodov, ako vyplniť informačné tabuľky a používať štítky. Ale na druhej strane, týmto článkom môžete zasiahnuť všetkých správnych ľudí.
Príklad uloženia neproduktovej dokumentácie
Prostredníctvom vyššie opísaného procesu môžete organizovať ukladanie takmer akýchkoľvek informácií. Krása tohto prístupu spočíva v tom, že je univerzálny: keď si naň používatelia zvyknú, prestanú vytvárať neporiadok. Ďalším veľkým (ale nie zadarmo) plusom je možnosť za chodu zbierať rôzne štatistiky a na ich základe kresliť krásne diagramy.
Dovoľte mi uviesť príklad nášho procesu uchovávania informácií o tíme.
Rozhodli sme sa vytvoriť kartu zamestnanca pre každého člena tímu. Podľa toho máme šablónu, podľa ktorej si každý nový človek vytvorí túto kartu pre seba a uchováva v nej všetky osobné údaje.
Ako vidíte, máme podrobnú tabuľku vlastností a hneď aj návod, ako presne túto stránku udržiavať. Niektoré štítky si zamestnanci pridávajú sami podľa pokynov, šablóna obsahuje len tie hlavné: štítok na kartu zamestnaneckú kartu, smerová značka smer-zapojiť a tímová značka tím-qa.
Výsledkom je, že keď si každý vytvorí kartu pre seba, získa sa kompletná tabuľka s informáciami o zamestnancoch. Tieto informácie možno použiť v rôznych bodoch. Správcovia zdrojov môžu zhromažďovať všeobecné tabuľky pre seba a vedúci tímu môžu vytvárať tímové tabuľky pridaním tímovej značky do výberu.
Rôzne súhrny môžete vidieť napríklad podľa značiek qa-upgrade-plan Zobrazia sa všetky úlohy vývoja QA. Zároveň si každý človek vo svojej karte zamestnanca uchová dôležitú históriu a svoj vlastný plán rozvoja – vytvorí vnorenú stránku zo šablóny plánov rozvoja.
Záver
Udržiavajte akúkoľvek dokumentáciu tak, aby sa nehanbila a nespôsobovala používateľom neznesiteľnú bolesť!
Naozaj dúfam, že článok bude užitočný a vo všetkej dokumentácii na svete príde poriadok.
Zdroj: hab.com