{"id":76463,"date":"2020-04-02T13:42:40","date_gmt":"2020-04-02T11:42:40","guid":{"rendered":"https:\/\/prohoster.info\/blog\/administrirovanie\/proektirovanie-v-confluence"},"modified":"2020-04-02T13:42:40","modified_gmt":"2020-04-02T11:42:40","slug":"proektirovanie-v-confluence","status":"publish","type":"post","link":"https:\/\/prohoster.info\/pl\/blog\/administrirovanie\/proektirovanie-v-confluence","title":{"rendered":"Projektowanie w Confluence","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

Cze\u015b\u0107 wszystkim! <\/p>\n

Nazywam si\u0119 Masza, pracuj\u0119 jako in\u017cynier ds. zapewnienia jako\u015bci w grupie firm Tinkoff. Praca w QA wymaga wielu komunikacji z r\u00f3\u017cnymi lud\u017ami z r\u00f3\u017cnych zespo\u0142\u00f3w, a ja dodatkowo by\u0142am mened\u017cerem i wyk\u0142adowc\u0105 program\u00f3w edukacyjnych, wi\u0119c moja mapa komunikacji by\u0142a maksymalnie szeroka. I w pewnym momencie eksplodowa\u0142am: zrozumia\u0142am, \u017ce ju\u017c nie mog\u0119, nie mog\u0119, nie mog\u0119 wype\u0142nia\u0107 piekielnych ton nieczytelnych tabel i dokument\u00f3w. <\/p>\n

\"Projektowanie
\n
\n<\/a><\/noindex>
\nZapewne ka\u017cdy z was wyobrazi\u0142 sobie teraz to, o czym m\u00f3wi\u0119, i obla\u0142 si\u0119 zimnym potem: listy nazwisk bez porz\u0105dku alfabetycznego, tabele w setkach kolumn z przesuni\u0119t\u0105 szat\u0105 graficzn\u0105, tabele w tysi\u0105cach wierszy, w kt\u00f3rych trzeba trze\u0107 palcem o k\u00f3\u0142ko myszy, \u017ceby zobaczy\u0107 nag\u0142\u00f3wek, tony stron nieponumerowanych instrukcji, setki przesy\u0142anych sobie nawzajem maili z danymi, kt\u00f3re trzeba przeanalizowa\u0107 i usystematyzowa\u0107 oraz upcha\u0107 w r\u00f3wnie nieczytelnych tabelach.<\/p>\n

\"Projektowanie
\n
\nI oto, gdy nieco och\u0142on\u0119\u0142am, postanowi\u0142am napisa\u0107 ten artyku\u0142. Opowiem, jak mo\u017cna normalnie (a nawet czasem wygodnie) prowadzi\u0107 r\u00f3\u017cnorodn\u0105 dokumentacj\u0119 niezwi\u0105zan\u0105 z produktem. Mam nadziej\u0119, \u017ce artyku\u0142 rozprzestrzeni si\u0119 w sieci i poziom ba\u0142aganu w s\u0105siednich dzia\u0142ach rozwoju chocia\u017c troch\u0119 si\u0119 obni\u017cy, a ludzie (i ja r\u00f3wnie\u017c) stan\u0105 si\u0119 odrobin\u0119 szcz\u0119\u015bliwsi.<\/p>\n

\"Projektowanie
\n<\/p>\n

Narz\u0119dzia<\/h2>\n

\nDokumentacja produktowa cz\u0119sto jest przechowywana obok kodu, i to dobrze. Natomiast dokumentacja niezwi\u0105zana z produktem cz\u0119sto jest przechowywana gdzie popadnie. Cz\u0119sto ludzie staraj\u0105 si\u0119 przenosi\u0107 informacje z r\u00f3\u017cnych miejsc do Confluence, i my nie jeste\u015bmy wyj\u0105tkiem. Tak wi\u0119c ca\u0142a dalsza opowie\u015b\u0107 o nim.<\/p>\n

W og\u00f3le Confluence to zaawansowany silnik wiki. Umo\u017cliwia prac\u0119 z danymi w r\u00f3\u017cnych formatach: tekst z formatowaniem, tabele, r\u00f3\u017cnorodne diagramy. To bardzo interesuj\u0105ce i pot\u0119\u017cne narz\u0119dzie, ale je\u015bli nie potrafisz go przygotowa\u0107, otrzymasz kolejny ba\u0142agan nieczytelnych dokument\u00f3w. Naucz\u0119 ci\u0119, jak to robi\u0107!<\/p>\n

\"Projektowanie
\n<\/p>\n

Makarony<\/h2>\n

\nPrawie ca\u0142a magia Confluence opiera si\u0119 na makrach. Jest ich bardzo wiele i mo\u017cna je ze sob\u0105 \u0142\u0105czy\u0107. Wyst\u0119puj\u0105 w wersjach p\u0142atnych i darmowych, b\u0119d\u0105 r\u00f3\u017cne przyk\u0142ady makr z linkami do dokumentacji dla nich.<\/p>\n

Interfejs pracy z makrami jest maksymalnie prosty. Aby doda\u0107 makro, nale\u017cy klikn\u0105\u0107 na plus i wybra\u0107 odpowiedni element z listy.<\/p>\n

\"Projektowanie
\n
\nJe\u015bli makro jest samowystarczalne, to znaczy, \u017ce nie wymaga wstawiania czego\u015b innego w jego wn\u0119trzu, wygl\u0105da jak blok.<\/p>\n

\"Projektowanie
\n
\nJe\u015bli do pracy makra potrzebne jest co\u015b wewn\u0105trz, wygl\u0105da jak ramka.<\/p>\n

\"Projektowanie
\n
\nMo\u017cna umieszcza\u0107 w jednej ramce dowoln\u0105 liczb\u0119 innych ram, byle w twojej piramidzie by\u0142a logika.<\/p>\n

\"Projektowanie
\n
\nKa\u017cde makro ma podgl\u0105d: wida\u0107 w nim od razu, czy poprawnie wype\u0142ni\u0142e\u015b i skonfigurowa\u0142e\u015b makro.<\/p>\n

Szablony<\/h2>\n

\nOpr\u00f3cz makr jest wygodne narz\u0119dzie do wype\u0142niania tre\u015bci \u2014 to szablon.
\nSzablony mo\u017cna wykorzysta\u0107 przy tworzeniu dowolnej strony: wystarczy klikn\u0105\u0107 trzy kropki obok przycisku \u201eUtw\u00f3rz\u201d i wybra\u0107 odpowiedni szablon.<\/p>\n

\"Projektowanie
\n
\nWtedy na stworzon\u0105 stron\u0119 zostanie dodana ca\u0142a tre\u015b\u0107, kt\u00f3ra znajduje si\u0119 w szablonie.<\/p>\n

Strony ze szablon\u00f3w mo\u017ce tworzy\u0107 ka\u017cdy, ale edytowa\u0107 same szablony mog\u0105 tylko ci, kt\u00f3rzy maj\u0105 do tego uprawnienia. Do szablonu mo\u017cna doda\u0107 dodatkowe instrukcje, jak powinno si\u0119 prowadzi\u0107 stron\u0119.<\/p>\n

\"Projektowanie
\n<\/p>\n

Magia tabel<\/h2>\n

\nTak naprawd\u0119, jako technik, serdecznie kocham tabele i mog\u0119 prawie ka\u017cd\u0105 informacj\u0119 w nie zawin\u0105\u0107 (cho\u0107 nie zawsze jest to efektywne). Same w sobie tabele s\u0105 jasne, uporz\u0105dkowane, skalowalne, magiczne!<\/p>\n

\"Projektowanie
\n
\nJednak nawet tak wspania\u0142\u0105 rzecz, jak tabela, mo\u017cna zepsu\u0107. Mo\u017cna j\u0105 r\u00f3wnie\u017c skutecznie wykorzysta\u0107 i nawet ulepszy\u0107. O tym poni\u017cej.<\/p>\n

Filtrowanie (p\u0142atna wtyczka)<\/h3>\n

\nKa\u017cd\u0105 ogromn\u0105, nieczyteln\u0105 tabel\u0119 mo\u017cna sprawi\u0107, by by\u0142a nieco mniejsza i nieco bardziej czytelna dzi\u0119ki filtracji. Mo\u017cna do tego wykorzysta\u0107 p\u0142atne makro. \u201eFiltr tabel\u201d<\/a><\/noindex>.<\/p>\n

Do tego makra nale\u017cy w\u0142o\u017cy\u0107 tabel\u0119 (mo\u017cna nawet najbrzydsz\u0105, byle w\u0142o\u017cy\u0107 j\u0105 w ca\u0142o\u015bci). W makrze mo\u017cna wybra\u0107 kolumny do filtrowania z rozwijanego menu, filtr tekstowy, numeryczny i filtrowanie po datach. <\/p>\n

\"Projektowanie
\n
\nWyobra\u017a sobie, \u017ce wszystkie informacje o kandydat\u00f3w na wszystkie oferty pracy s\u0105 zapisywane w tabeli. Oczywi\u015bcie, nieuporz\u0105dkowane \u2014 ludzie przychodz\u0105 na rozmowy kwalifikacyjne nie wg alfabetu. A ty musisz zrozumie\u0107, czy przeprowadza\u0142e\u015b rozmow\u0119 kwalifikacyjn\u0105 z konkretnym kandydatem wcze\u015bniej. Wystarczy umie\u015bci\u0107 ten ba\u0142agan w makrze filtru, doda\u0107 filtr tekstowy po nazwisku \u2014 i voila, informacja pojawi si\u0119 na ekranie.<\/p>\n

\"Projektowanie
\n
\nWarto zauwa\u017cy\u0107, \u017ce filtrowanie ogromnych tabel mo\u017ce wp\u0142ywa\u0107 na wydajno\u015b\u0107 systemu i czas \u0142adowania stron, dlatego wrzucenie ogromnej tabeli do filtra to tymczasowe rozwi\u0105zanie, lepiej zbudowa\u0107 proces, w kt\u00f3rym ludzie nie musz\u0105 tworzy\u0107 ogromnych, nieczytelnych tabel (przyk\u0142ad procesu znajdzie si\u0119 na ko\u0144cu artyku\u0142u).<\/p>\n

Sortowanie (p\u0142atna wtyczka)<\/h3>\n

\nDzi\u0119ki magicznemu makrowi \u201eFiltr tabel\u201d<\/a><\/noindex> mo\u017cna r\u00f3wnie\u017c ustawi\u0107 domy\u015blne sortowanie wed\u0142ug dowolnej kolumny i ponumerowa\u0107 wiersze. Lub klikn\u0105\u0107 na dowoln\u0105 kolumn\u0119 tabeli umieszczonej w makrze filtru, a nast\u0119pnie nast\u0105pi sortowanie wed\u0142ug tej kolumny. <\/p>\n

\"Projektowanie
\n
\nNa przyk\u0142ad, je\u015bli macie t\u0119 sam\u0105 tabel\u0119 z kandydatami i trzeba okre\u015bli\u0107, ile rozm\u00f3w kwalifikacyjnych przeprowadzono w danym miesi\u0105cu \u2014 posortujcie wed\u0142ug daty i cieszcie si\u0119.<\/p>\n

Tabele przestawne (p\u0142atna wtyczka)<\/h3>\n

\nTeraz przejd\u017amy do ciekawszego przypadku. Wyobra\u017acie sobie, \u017ce wasza tabela jest ogromna i trzeba co\u015b w niej policzy\u0107. Oczywi\u015bcie mo\u017cna skopiowa\u0107 j\u0105 do Excela, policzy\u0107 potrzebne dane i za\u0142adowa\u0107 je z powrotem do Confluence. Mo\u017cna jednak jednorazowo zastosowa\u0107 makro \u201eTabela przestawna\u201d<\/a><\/noindex> i otrzyma\u0107 ten sam wynik, z t\u0105 r\u00f3\u017cnic\u0105, \u017ce b\u0119dzie on aktualizowany.<\/p>\n

Na przyk\u0142ad: macie tabel\u0119, w kt\u00f3rej zbierane s\u0105 dane o wszystkich pracownikach \u2014 gdzie si\u0119 znajduj\u0105 i jakie maj\u0105 stanowiska. Aby policzy\u0107, ile os\u00f3b jest w ka\u017cdym mie\u015bcie, musicie wybra\u0107 w makrze \u201eTabela przestawna\u201d wiersz, wed\u0142ug kt\u00f3rego b\u0119d\u0105 agregowane dane (lokalizacja) oraz typ operacji (sumowanie).<\/p>\n

\"Projektowanie
\n
\nNaturalnie, mo\u017cna grupowa\u0107 wed\u0142ug kilku kryteri\u00f3w jednocze\u015bnie, wszystkie mo\u017cliwo\u015bci mo\u017cna zobaczy\u0107 w dokumentacji.<\/a><\/noindex>.<\/p>\n

Wykresy (p\u0142atna wtyczka)<\/h3>\n

\nJak ju\u017c wspomnia\u0142am, nie wszyscy kochaj\u0105 tabele tak bardzo jak ja. Niestety, mened\u017cerowie w wi\u0119kszo\u015bci ich w og\u00f3le nie lubi\u0105. Ale wszyscy bardzo lubi\u0105 jasne, kolorowe wykresy.
\nTw\u00f3rcy Confluence o tym na pewno wiedzieli (z pewno\u015bci\u0105 maj\u0105 te\u017c szefostwo, kt\u00f3re lubi raporty i wykresy, gdzie\u017cby bez tego). Dlatego mo\u017cna skorzysta\u0107 z magicznego makra \u201eWykres z tabeli\u201d<\/a><\/noindex>. Do tego makra nale\u017cy wstawi\u0107 tabel\u0119 przestawn\u0105 z poprzedniego punktu, a voila \u2014 wasze szare, nudne dane pi\u0119knie zwizualizowane.<\/p>\n

\"Projektowanie
\n
\nNaturalnie, w tym makrze te\u017c s\u0105 ustawienia. Link do dokumentacji ka\u017cdego makra mo\u017cna znale\u017a\u0107 w trybie edycji tego makra.<\/p>\n

\u0141atwo\u015b\u0107 agregacji<\/h2>\n

\nInformacje z wcze\u015bniejszych punkt\u00f3w z pewno\u015bci\u0105 nie by\u0142y dla Ciebie nowo\u015bci\u0105. Ale teraz na pewno potrafisz korzysta\u0107 z makr, a ja mog\u0119 przej\u015b\u0107 do bardziej interesuj\u0105cej cz\u0119\u015bci artyku\u0142u.<\/p>\n

\"Projektowanie
\n<\/p>\n

Tagi<\/h3>\n

\nTo \u017ale, gdy ludzie przechowuj\u0105 informacje w jednym nieuporz\u0105dkowanym artykule lub ogromnej tabeli. Jeszcze gorzej, gdy cz\u0119\u015bci tych informacji s\u0105 nieczytelnie sformatowane i rozsiane po przestrzeniach Confluence. Na szcz\u0119\u015bcie istnieje mo\u017cliwo\u015b\u0107 zebrania rozproszonej informacji w jednym miejscu. W tym celu nale\u017cy skorzysta\u0107 z tag\u00f3w<\/a><\/noindex> (znanych wszystkim z medi\u00f3w spo\u0142eczno\u015bciowych).<\/p>\n

\"Projektowanie
\n
\nMo\u017cesz doda\u0107 dowoln\u0105 liczb\u0119 tag\u00f3w do ka\u017cdej strony. Klikaj\u0105c na tag, trafisz na stron\u0119 agregacji, gdzie znajduj\u0105 si\u0119 odno\u015bniki do wszystkich materia\u0142\u00f3w z tym tagiem, a tak\u017ce zwi\u0105zanych tag\u00f3w. Powi\u0105zane tagi to te, kt\u00f3re cz\u0119sto wyst\u0119puj\u0105 na jednej stronie.<\/p>\n

\"Projektowanie
\n<\/p>\n

W\u0142a\u015bciwo\u015bci stron<\/h3>\n

\nMo\u017cna doda\u0107 jeszcze jeden ciekawy makro do strukturyzacji informacji \u2014 \u201eW\u0142a\u015bciwo\u015bci stron\u201d<\/a><\/noindex>. Nale\u017cy wprowadzi\u0107 do niego tabel\u0119 z dwiema kolumnami, pierwsza z nich b\u0119dzie kluczem, a druga \u2014 warto\u015bci\u0105 w\u0142a\u015bciwo\u015bci. Co wa\u017cne, makro mo\u017cna ukry\u0107 na stronie, aby nie przeszkadza\u0142o w czytaniu tre\u015bci, jednak strona nadal b\u0119dzie oznaczona odpowiednimi kluczami.<\/p>\n

\"Projektowanie
\n
\nZwr\u00f3\u0107 uwag\u0119 na ID \u2014 jest wygodne do przypisywania r\u00f3\u017cnych grup w\u0142a\u015bciwo\u015bci do r\u00f3\u017cnych stron (lub nawet r\u00f3\u017cnych grup w\u0142a\u015bciwo\u015bci do jednej strony). <\/p>\n

Raporty<\/h3>\n

\nNa podstawie tag\u00f3w mo\u017cna generowa\u0107 raporty. Na przyk\u0142ad, makro \u201eRaport o tre\u015bci\u201d<\/a><\/noindex> zbiera wszystkie strony z okre\u015blonym zestawem tag\u00f3w.<\/p>\n

\"Projektowanie
\n
\nJednak bardziej interesuj\u0105cym raportem jest makro \u201eRaport w\u0142a\u015bciwo\u015bci strony\u201d<\/a><\/noindex>. Zbiera wszystkie strony z okre\u015blonym zestawem tag\u00f3w, ale nie tylko wy\u015bwietla ich list\u0119, lecz tworzy tabel\u0119 (\u0142apiesz powi\u0105zanie z pocz\u0105tkiem artyku\u0142u?), w kt\u00f3rej kolumnami s\u0105 klucze w\u0142a\u015bciwo\u015bci strony.<\/p>\n

\"Projektowanie
\n
\nTworzy to tabel\u0119 przestawn\u0105 z informacji z r\u00f3\u017cnych \u017ar\u00f3de\u0142. Mi\u0142o, \u017ce ma ono przydatne funkcje: responsywne uk\u0142adanie, sortowanie wed\u0142ug dowolnej kolumny. Tak\u0105 tabel\u0119 raportow\u0105 mo\u017cna r\u00f3wnie\u017c konfigurowa\u0107 wewn\u0105trz makra. <\/p>\n

\"Projektowanie
\n
\nPodczas konfigurowania mo\u017cna usun\u0105\u0107 z raportu pewne kolumny, ustawi\u0107 domy\u015blny stan lub liczb\u0119 wy\u015bwietlanych rekord\u00f3w. Mo\u017cna r\u00f3wnie\u017c ustawi\u0107 ID w\u0142a\u015bciwo\u015bci strony, aby widzie\u0107 tylko potrzebne informacje.<\/p>\n

Na przyk\u0142ad macie wiele stron pracownik\u00f3w, a te strony maj\u0105 zestaw w\u0142a\u015bciwo\u015bci dotycz\u0105cych danej osoby: jakiego jest poziomu, gdzie si\u0119 znajduje, kiedy do\u0142\u0105czy\u0142 do zespo\u0142u i tak dalej. Te w\u0142a\u015bciwo\u015bci s\u0105 oznaczone ID = employee_inf<\/i>. Jest r\u00f3wnie\u017c drugi zestaw w\u0142a\u015bciwo\u015bci na tej samej stronie, w kt\u00f3rym zebrane s\u0105 informacje o osobie jako cz\u0119\u015bci zespo\u0142u: jak\u0105 rol\u0119 pe\u0142ni, w jakim zespole si\u0119 znajduje itd. Te w\u0142a\u015bciwo\u015bci s\u0105 oznaczone ID = team_inf<\/i>. Wtedy przy tworzeniu raportu mo\u017cecie wy\u015bwietli\u0107 tylko informacje wed\u0142ug jednego identyfikatora lub od razu wed\u0142ug dw\u00f3ch \u2014 w zale\u017cno\u015bci od wygody.<\/p>\n

Zalet\u0105 takiego podej\u015bcia jest to, \u017ce ka\u017cdy mo\u017ce stworzy\u0107 potrzebn\u0105 sobie informacyjn\u0105 tabel\u0119, kt\u00f3ra nie b\u0119dzie niczego dublowa\u0107 i b\u0119dzie si\u0119 aktualizowa\u0107 w miar\u0119 aktualizacji g\u0142\u00f3wnej strony. Na przyk\u0142ad: dla lidera zespo\u0142u nie jest istotne, kiedy jego deweloperzy zacz\u0119li prac\u0119, ale wa\u017cne jest, jak\u0105 rol\u0119 ka\u017cdy z nich pe\u0142ni w zespole. Lider zespo\u0142u stworzy raport o zespole. A ksi\u0119gowy zupe\u0142nie nie obchodzi, kto jak\u0105 rol\u0119 pe\u0142ni, ale wa\u017cne s\u0105 pozycje \u2014 stworzy raport o stanowiskach. Przy tym \u017ar\u00f3d\u0142o informacji nie b\u0119dzie dublowane ani przenoszone.<\/p>\n

Proces ko\u0144cowy<\/h2>\n

<\/p>\n

Instrukcja<\/h3>\n

\nZatem mo\u017cemy pi\u0119knie strukturyzowa\u0107 i efektywnie agregowa\u0107 informacje w Confluence na przyk\u0142adzie u\u017cycia makr. Ale w idealnym przypadku nale\u017cy zrobi\u0107 tak, aby nowe informacje od razu by\u0142y ustrukturyzowane i trafia\u0142y do wszystkich ju\u017c u\u017cywanych mechanizm\u00f3w agregacji.<\/p>\n

Tu z pomoc\u0105 przyjdzie zestawienie makr i szablon\u00f3w. Aby zmusi\u0107 ludzi do tworzenia nowych stron w odpowiednim formacie, mo\u017cna u\u017cy\u0107 makra \u201eUtw\u00f3rz z szablonu\u201d. Dodaje ono na stron\u0119 przycisk, po naci\u015bni\u0119ciu kt\u00f3rego tworzona jest nowa strona z odpowiedniego szablonu. W ten spos\u00f3b zmuszacie ludzi do pracy w po\u017c\u0105danym formacie. <\/p>\n

\"Projektowanie
\n
\nDo szablonu, z kt\u00f3rego dajecie mo\u017cliwo\u015b\u0107 tworzenia strony, nale\u017cy wcze\u015bniej doda\u0107 etykiety, makro \u201eW\u0142a\u015bciwo\u015bci strony\u201d oraz tabel\u0119 potrzebnych w\u0142a\u015bciwo\u015bci. Rekomenduj\u0119 r\u00f3wnie\u017c dodanie instrukcji dotycz\u0105cych tego, jakimi warto\u015bciami nale\u017cy wype\u0142nia\u0107 stron\u0119 oraz warto\u015bci w\u0142a\u015bciwo\u015bci.<\/p>\n

\"Projektowanie
\n
\nWtedy proces ko\u0144cowy b\u0119dzie wygl\u0105da\u0142 tak:<\/p>\n

    \n
  1. Tworzycie szablon dla informacji okre\u015blonego typu.<\/li>\n
  2. Do tego szablonu dodajecie etykiety i w\u0142a\u015bciwo\u015bci strony w makrze.<\/li>\n
  3. W dowolnym dogodnym miejscu tworzysz stron\u0119 g\u0142\u00f3wn\u0105 z przyciskiem, po klikni\u0119ciu na kt\u00f3ry zak\u0142adana jest strona podrz\u0119dna wed\u0142ug szablonu. <\/li>\n
  4. Udost\u0119pniasz stron\u0119 g\u0142\u00f3wn\u0105 u\u017cytkownikom, kt\u00f3rzy potencjalnie b\u0119d\u0105 generowa\u0107 potrzebne informacje (wed\u0142ug wymaganego szablonu, klikaj\u0105c przycisk).<\/li>\n
  5. Zbierasz raport dotycz\u0105cy atrybut\u00f3w strony przez etykiety, kt\u00f3re zadeklarowa\u0142e\u015b w szablonie.<\/li>\n
  6. Cieszysz si\u0119: masz wszystkie potrzebne informacje w wygodnym formacie. <\/li>\n<\/ol>\n

    \"Projektowanie
    \n<\/p>\n

    Pu\u0142apki<\/h3>\n

    \nJako in\u017cynier jako\u015bci mog\u0119 \u015bmia\u0142o stwierdzi\u0107, \u017ce nic doskona\u0142ego w \u015bwiecie nie istnieje. Nawet boskie tabele nie s\u0105 doskona\u0142e. A w powy\u017cszym procesie istniej\u0105 pu\u0142apki.<\/p>\n