Mindenkinek szia!
A nevem Masha, a Tinkoff cégcsoport minőségbiztosítási mérnöke vagyok. A QA munka sok kommunikációt feltételez különböző emberekkel a különböző csapatokból, és ráadásul én voltam az oktatási programok menedzsere és előadója is, így a kommunikációs hálózatom maximálisan széles volt. És egy idő után dühbe jöttem: rájöttem, hogy már nem tudom, nem tudom, nem tudom kitölteni a pokoli mennyiségű olvashatatlan táblázatot és dokumentumot.
Biztos vagyok benne, hogy mindannyian elképzeltétek, miről beszélek, és hideg verejték öntött el benneteket: névtelen listák ábécé sorrend nélkül, centire benyomódott táblázatok száz rovatban, ezer soros táblázatok, ahol végig kell görgetni az ujjunkat az egérkeréken, hogy megnézhesse a fejléceket, tonnányi számozatlan utasításlap, száz e-mail, amelyet egymásnak kell továbbítani az elemzendő és rendszerezendő adatokkal, hogy aztán belepasszírozzuk őket ugyanilyen olvashatatlan táblázatokba.
És amikor kicsit megnyugodtam, úgy döntöttem, írok erről a cikkről. Elmondom, hogyan lehet normálisan (néha még kényelmesen is) vezetni a különféle nem termékre vonatkozó dokumentációt. Remélem, hogy a cikk elterjed a neten, és az átkok szintje a fejlesztési osztályok közelében kicsit csökken, és az emberek (én is beleértve) egy kicsit boldogabbak lesznek.
Eszközök
A termékre vonatkozó dokumentáció gyakran a kóddal együtt tárolódik, ami jó. A nem termékre vonatkozó dokumentáció viszont általában mindenhol ott van. Gyakran az emberek próbálják az információt különböző helyekről a Confluence-be áthelyezni, és mi sem vagyunk kivételek. Szóval minden további mese róla.
A Confluence egy fejlett wiki motor. Lehetővé teszi, hogy az adatokat különböző megjelenítési formákban használjuk: formázott szöveg, táblázatok, különféle diagramok. Ez egy nagyon érdekes és erőteljes eszköz, de ha nem tudod, hogyan kell megfelelően használni, akkor egy újabb olvashatatlan dokumentumhalmazt kapsz. Megtanítalak rá!
Makrók
A Confluence szinte minden varázslata a makrókon alapul. Nagyon sok makró létezik, és össze lehet őket kombinálni egymással. Lehetnek ingyenesek és fizetősek, a következőkben különböző makrópéldák és dokumentációs linkek találhatók.
A makrókkal való munka felülete maximálisan egyszerű. A makró hozzáadásához kattints a pluszra, és válaszd ki a szükséges elemet a listából.
Ha a makró önálló, tehát nem igényel további elemeket magába, akkor blokk formájában jelenik meg.
Ha a makró működéséhez szükség van valaminek a beillesztésére, akkor keret formájában jelenik meg.
Egy keretbe annyi másik elemet helyezhetünk el, amennyit csak szeretnénk, csak a piramisunknak logikusnak kell lennie.
Minden makrónak van előnézete: azonnal látható, hogy helyesen töltöttük-e ki és állítottuk-e be a makrót.
Sablonok
A makrókon kívül van egy kényelmes tartalom előkitöltő eszköz — ez a sablon.
A sablonokat bármely oldal létrehozásakor használhatjuk: egyszerűen kattintsunk a "Létrehozás" gomb melletti három pontra, és válasszuk ki a szükséges sablont.
Ekkor a létrehozott oldalra az összes tartalom hozzáadódik, ami a sablonban található.
Sablonokat bárki létrehozhat, de maguknak a sablonoknak a létrehozása vagy szerkesztése csak azok számára engedélyezett, akiknek erre joguk van. A sablonba további utasításokat is be lehet illeszteni arról, hogy hogyan kell kezelni az oldalt.
A táblázatok varázsa
Techniológusként valójában mélyen szeretem a táblázatokat, és szinte bármilyen információt képes vagyok beléjük csomagolni (bár nem mindig hatékonyan). Maguk a táblázatok világosak, strukturáltak, skálázhatók, varázslatosak!
De még egy ilyen csodálatos lény, mint a táblázat is elrontható. De megfelelően használva akár javítható is. Erről alább.
Szűrés (fizetős bővítmény)
Bármilyen hatalmas, nehezen olvasható táblázatot egy kicsit kevésbé hatalmassá és egy kicsit olvashatóbbá tehetünk szűréssel. Ehhez felhasználhatjuk a fizetős makrót. .
Ebben a makróban egy táblázatot kell elhelyezni (még a legcsúnyábbat is, a lényeg, hogy egészben belekerüljön). A makróban választhatunk a szűréshez oszlopokat a legördülő listából, szöveges szűrőt, numerikus és dátum szűrőt is.
Képzeld el, hogy az összes pályázó információját táblázatos listába rögzítik. Természetesen nem rendezett formában — hiszen az emberek nem név szerint jönnek az interjúkra. Neked pedig meg kell értened, hogy találkoztál-e már korábban egy adott jelentkezővel. Csak bele kell helyezni ezt a káoszt a szűrő makróba, hozzáadni egy szöveges szűrőt a név alapján — és voilá, az információ megjelenik a képernyődön.
Fontos megjegyezni, hogy hatalmas táblák szűrése befolyásolhatja a rendszer működését és az oldalak betöltési idejét, ezért nem célszerű óriási táblákat befogni egy szűrőbe — a legjobb, ha olyan folyamatot alakítunk ki, amelyben az embereknek nem kell óriási, olvashatatlan táblákat létrehozniuk (a folyamat példája a cikk végén található).
Rendezés (fizetős bővítmény)
A varázslatos makró segítségével alapértelmezett rendezést is meghatározhat bármely oszlop szerint, és számozhatja a sorokat. Vagy rákattinthat bármely táblaoszlopra, melyet a szűrő makróba helyezett, és az az oszlop szerint sorba rendeződik.
Például, ha van egy táblázata, amelyben a jelentkezők adatai szerepelnek, és meg kell néznie, hány interjú zajlott egy adott hónapban — rendezze a dátum szerint, és élvezze.
Kimutatások (fizetős bővítmény)
Most egy érdekesebb esetre térünk át. Képzelje el, hogy a táblázata hatalmas, és számításokat kell végeznie rajta. Természetesen átmásolhatja Excelbe, elvégezheti a szükséges számításokat és visszaexportálhatja az adatokat a Confluence-be. De egy makró egy alkalommal való alkalmazásával ugyanazt az eredményt kapja, csak éppen frissíthető is.
Például: van egy táblázata, amelyben az összes dolgozó adatát összegyűjtötte — hol tartózkodnak és milyen pozíciókat töltenek be. Ahhoz, hogy megtudja, hány fő tartózkodik egyes városokban, ki kell választania a "Kimutatás" makróban azt a sort, amely alapján az adatok aggregálódnak (lokáció) és a művelet típusát (összeadás).
Természetesen több feltétel alapján is lehet csoportosítani, az összes lehetőséget megtekintheti .
Diagramok (fizetős bővítmény)
Ahogy már említettem, nem mindenki szereti annyira a táblázatokat, mint én. Sajnos a menedzserek többsége egyáltalán nem kedveli őket. Viszont mindenki nagyon szereti a színes, figyelemfelkeltő diagramokat.
A Confluence készítői erről kétségtelenül tudtak (bizonyára nekik is van főnökük, aki szereti a jelentéseket és diagramokat, hova máshová). Ezért használhatja a varázslatos makrót . Ezt a makrót be kell helyeznie a korábbi pontból származó kimutatásba, és voilá — a szürke unalmas adatai szépen vizualizálva vannak.
Természetesen ennek a makrónak is vannak beállításai. A makró bármely dokumentációs linkje megtalálható ennek a makrónak a szerkesztési módjában.
Az aggregálás egyszerűsége
A korábbi pontokból származó információk bizonyára nem voltak meglepők számodra. De most már biztosan tudod, hogyan kell használni a makrókat, így áttérhetek a cikk érdekesebb részére.
Címkék
Rossz, amikor az emberek információt egyetlen, nem strukturált cikkben vagy hatalmas táblázatban tárolnak. Még rosszabb, amikor ezen információk egyes részei nemcsak olvashatatlanul vannak megformálva, de szétszórva is találhatók a Confluence világában. Szerencsére van lehetőség arra, hogy a szétszórt információkat egy helyre összegyűjtsük. Ehhez használnunk kell a (amelyek mindenki számára ismerősek a közösségi médiából).
Bármely oldalhoz bármennyi címkét hozzáadhatunk. Ha rákattint egy címkére, akkor egy aggregáló oldalra kerül, ahol hivatkozások találhatók az összes olyan anyagra, amely ezen címkével és a kapcsolódó címkékkel rendelkezik. A kapcsolódó címkék olyanok, amelyeket gyakran találunk egy oldalon.
Oldalattribútumok
Egy oldalhoz hozzáadhatsz egy másik érdekes makrót az információ strukturálásához – . Ezen belül egy kéttagú táblázatot kell megadni: az első a kulcs, a második pedig az attribútum értéke. Ráadásul a makrót elrejtheted az oldalról, hogy ne zavarja az olvasást, de az oldal így is megfelelő kulcsokkal lesz ellátva.
Figyelj a az ID-re – ezt kényelmes beállítani, hogy különböző attribútumcsoportokat rendeljen a különböző oldalakhoz (vagy akár egy oldalon belül különböző attribútumcsoportokat).
Jelentések
A címkék alapján jelentéseket készíthetünk. Például a makró összegyűjti az összes oldalt egy meghatározott címkecsoporthoz.
De egy érdekesebb jelentés a makró . Ez is összegyűjti az összes oldalt egy adott címkecsoporthoz, de nem csupán a lista kiírásával végzi, hanem egy táblázatot állít össze (érted a kapcsolatot a cikk kezdetével?), amelynek oszlopai az oldal attribútumainak kulcsai.
Így egy összesítő táblázatot kapunk a különböző forrásokból származó információkról. Kellemes, hogy kényelmes funkciókkal rendelkezik: reszponzív tervezés, bármely oszlop szerinti rendezés. Ezen kívül ezt a jelentéstáblázatot a makrón belül is konfigurálhatjuk.
A konfigurálás során eltávolíthatunk egyes oszlopokat a jelentésből, beállíthatjuk az alapértelmezett állapotot vagy a megjelenített rekordok számát. Ezen kívül megadhatunk egy oldalattribútum ID-t, hogy csak a szükséges információkat láthassuk.
Például, ha van számos munkatársi oldal, ezek az oldalak tartalmaznak egy sor jellemzőt a személyről: milyen szinten van, hol található, mikor csatlakozott a csapathoz és így tovább. Ezek a jellemzők meg vannak jelölve ID = employee_inf. És van egy második jellemzőkészlet ugyanazon az oldalon, amely információt gyűjt a személyről, mint a csapat része: milyen szerepet tölt be a személy, melyik csapatban van, és így tovább. Ezek a jellemzők meg vannak jelölve ID = team_inf. Így a jelentés összeállításakor csak egy azonosítóra, vagy akár kettőre is kivehetjük az információt — ahogy az kényelmesebb.
Ennek a megközelítésnek az előnye, hogy mindenki létrehozhat egy olyan információs táblázatot, amely nem tartalmaz duplikációt, és frissül, amikor a főoldal frissül. Például: a csapatvezetőt nem érdekli, mikor alkalmazták a fejlesztőit, de fontos számára, hogy ki milyen szerepet tölt be a csapatban. A csapatvezető az ő csapata jelentését fogja elkészíteni. A könyvelőt egyáltalán nem érdekli, ki milyen szerepet tölt be, de fontosak számára a beosztások — ő a beosztásokról fog jelentést készíteni. Így az információforrás nem fog megduplázódni vagy áthelyeződni.
A végső folyamat
Az útmutató
Tehát szépen strukturálhatjuk és hatékonyan aggregálhatjuk az információt a Confluence-ben a makrók használatán keresztül. De ideális esetben úgy kellene eljárni, hogy az új információ azonnal struktúrált legyen, és bekerüljön minden már használt aggregáló mechanizmusba.
Ehhez segítséget nyújt a makrók és sablonok összekapcsolása. Az emberek új oldalakat a megfelelő formátumban történő létrehozására a "Sablonból létrehozás" makrót használhatjuk. Ez hozzáad egy gombot az oldalhoz, amelynek megnyomásával új oldal jön létre a kívánt sablon alapján. Így az embereket azonnal a kívánt formátumban tudja működésre bírni.
A sablonba, amelyből új oldalt készít, előre kell hozzáadni címkéket, a "Oldal jellemzők" makrót és a kívánt jellemzők táblázatát. Javaslom továbbá, hogy adjunk hozzá utasításokat arról, hogy milyen értékekkel kell feltölteni az oldalt és a tulajdonságok értékeit.
A végső folyamat tehát így néz ki:
- Sablont hozol létre egy adott típusú információhoz.
- Ebben a sablonban hozzáadod a címkéket és a jellemzőket a makróban.
- Bármilyen kényelmes helyen létrehozhat egy gyökéroldalt egy gombbal, aminek megnyomásával egy láncoldal készül a sablon alapján.
- Hozzáférést ad a gyökéroldalhoz olyan felhasználóknak, akik potenciálisan létrehozhatják a szükséges információt (a kívánt sablon alapján, a gomb megnyomásával).
- Összeállítja a jelentést a lap tulajdonságai alapján a címkék segítségével, amelyeket a sablonban megadott.
- Örülhet: minden szükséges információ megvan egy kényelmes formátumban.
Csapdák
Minőségügyi mérnökként bátran állíthatom, hogy a világban nincs tökéletes dolog. Még a mennyei táblázatok sem tökéletesek. Az előbb említett folyamatban is vannak buktatók.
- Ha úgy dönt, hogy megváltoztatja az oldaltulajdonságok nevét vagy összetételét, frissítenie kell az összes már létrehozott objektumot, hogy adatai helyesen átkerüljenek a jelentésbe. Ez sajnálatos, de másrészt arra kényszerít, hogy alaposan átgondolja az információk "architektúráját", ami egy nagyon érdekes feladat.
- Elég sok útmutatót kell írnia arról, hogyan kell kitölteni az információs táblázatokat és használni a címkéket. De másrészt, egyszerűen megoszthatja ezt a cikket a szükséges emberekkel.
Példa nem termékként kezelendő dokumentáció tárolására
A fent leírt folyamat révén szinte bármilyen információ tárolása megszervezhető. Az előny az, hogy ez egy univerzális megközelítés: amikor a felhasználók hozzászoknak, abbahagyják a zűrzavar generálását. Egy másik nagy (de nem ingyenes) előny az, hogy valós időben összegyűjtheti a különféle statisztikákat, és szép diagramokat rajzolhat alapjánuk.
Példát adok a csapat információjának kezelésére.
Minden csapattag számára úgy döntöttünk, hogy készítünk egy munkatársi kártyát. Ennek megfelelően van egy sablonunk, amely alapján minden új ember létrehozza ezt a kártyát és vezeti benne a személyes információit.
Mint látható, van egy kiterjedt tulajdonság táblázatunk, és már van útmutató arról, hogyan kell kezelni ezt az oldalt. Egyes címkéket maguk a munkatársak állítanak be az útmutatások alapján, a sablonban viszont csak az alapvetőek találhatók: a kártya címkéje employee-card, az irány címkéje direction-involve és a csapat címkéje team-qa.
Miután mindenki létrehozta a saját kártyáját, egy teljes táblázat jön létre az alkalmazottak információival. Ezt az információt különböző pontokon lehet felhasználni. A forrást kezelő menedzserek összesíthetik az adatokat, míg a csapatvezetők – csapat táblázatokat készíthetnek, hozzáadva a válogatáshoz a csapat címkét.
A címkék alapján különböző összefoglalókat láthatunk, például a következőkre qa-upgrade-plan megjelenik az összes feladat a QA fejlesztésére. Ezenkívül minden ember a saját alkalmazotti kártyáján vezeti fontos történetét és fejlesztési tervét – létrehozva egy aloldalt a fejlesztési tervek sablonjából.
Zárás
Bármilyen dokumentációt úgy készíts, hogy ne kelljen szégyenkezned miatta, és a felhasználóknak ne okozzon kínzó fájdalmat!
Nagyon remélem, hogy a cikk hasznos lesz, és a világ minden dokumentációjában rendre kerül.
Forrás: habr.com
