🥇Projektowanie w Confluence

Cześć wszystkim!

Nazywam się Masza, pracuję jako inżynier ds. zapewnienia jakości w grupie firm Tinkoff. Praca w QA wymaga wielu komunikacji z różnymi ludźmi z różnych zespołów, a ja dodatkowo byłam menedżerem i wykładowcą programów edukacyjnych, więc moja mapa komunikacji była maksymalnie szeroka. I w pewnym momencie eksplodowałam: zrozumiałam, że już nie mogę, nie mogę, nie mogę wypełniać piekielnych ton nieczytelnych tabel i dokumentów.

Zapewne każdy z was wyobraził sobie teraz to, o czym mówię, i oblał się zimnym potem: listy nazwisk bez porządku alfabetycznego, tabele w setkach kolumn z przesuniętą szatą graficzną, tabele w tysiącach wierszy, w których trzeba trzeć palcem o kółko myszy, żeby zobaczyć nagłówek, tony stron nieponumerowanych instrukcji, setki przesyłanych sobie nawzajem maili z danymi, które trzeba przeanalizować i usystematyzować oraz upchać w równie nieczytelnych tabelach.

I oto, gdy nieco ochłonęłam, postanowiłam napisać ten artykuł. Opowiem, jak można normalnie (a nawet czasem wygodnie) prowadzić różnorodną dokumentację niezwiązaną z produktem. Mam nadzieję, że artykuł rozprzestrzeni się w sieci i poziom bałaganu w sąsiednich działach rozwoju chociaż trochę się obniży, a ludzie (i ja również) staną się odrobinę szczęśliwsi.

Narzędzia

Dokumentacja produktowa często jest przechowywana obok kodu, i to dobrze. Natomiast dokumentacja niezwiązana z produktem często jest przechowywana gdzie popadnie. Często ludzie starają się przenosić informacje z różnych miejsc do Confluence, i my nie jesteśmy wyjątkiem. Tak więc cała dalsza opowieść o nim.

W ogóle Confluence to zaawansowany silnik wiki. Umożliwia pracę z danymi w różnych formatach: tekst z formatowaniem, tabele, różnorodne diagramy. To bardzo interesujące i potężne narzędzie, ale jeśli nie potrafisz go przygotować, otrzymasz kolejny bałagan nieczytelnych dokumentów. Nauczę cię, jak to robić!

Makarony

Prawie cała magia Confluence opiera się na makrach. Jest ich bardzo wiele i można je ze sobą łączyć. Występują w wersjach płatnych i darmowych, będą różne przykłady makr z linkami do dokumentacji dla nich.

Interfejs pracy z makrami jest maksymalnie prosty. Aby dodać makro, należy kliknąć na plus i wybrać odpowiedni element z listy.

Jeśli makro jest samowystarczalne, to znaczy, że nie wymaga wstawiania czegoś innego w jego wnętrzu, wygląda jak blok.

Jeśli do pracy makra potrzebne jest coś wewnątrz, wygląda jak ramka.

Można umieszczać w jednej ramce dowolną liczbę innych ram, byle w twojej piramidzie była logika.

Każde makro ma podgląd: widać w nim od razu, czy poprawnie wypełniłeś i skonfigurowałeś makro.

Szablony

Oprócz makr jest wygodne narzędzie do wypełniania treści — to szablon.
Szablony można wykorzystać przy tworzeniu dowolnej strony: wystarczy kliknąć trzy kropki obok przycisku „Utwórz” i wybrać odpowiedni szablon.

Wtedy na stworzoną stronę zostanie dodana cała treść, która znajduje się w szablonie.

Strony ze szablonów może tworzyć każdy, ale edytować same szablony mogą tylko ci, którzy mają do tego uprawnienia. Do szablonu można dodać dodatkowe instrukcje, jak powinno się prowadzić stronę.

Magia tabel

Tak naprawdę, jako technik, serdecznie kocham tabele i mogę prawie każdą informację w nie zawinąć (choć nie zawsze jest to efektywne). Same w sobie tabele są jasne, uporządkowane, skalowalne, magiczne!

Jednak nawet tak wspaniałą rzecz, jak tabela, można zepsuć. Można ją również skutecznie wykorzystać i nawet ulepszyć. O tym poniżej.

Filtrowanie (płatna wtyczka)

Każdą ogromną, nieczytelną tabelę można sprawić, by była nieco mniejsza i nieco bardziej czytelna dzięki filtracji. Można do tego wykorzystać płatne makro. „Filtr tabel”.

Do tego makra należy włożyć tabelę (można nawet najbrzydszą, byle włożyć ją w całości). W makrze można wybrać kolumny do filtrowania z rozwijanego menu, filtr tekstowy, numeryczny i filtrowanie po datach.

Wyobraź sobie, że wszystkie informacje o kandydatów na wszystkie oferty pracy są zapisywane w tabeli. Oczywiście, nieuporządkowane — ludzie przychodzą na rozmowy kwalifikacyjne nie wg alfabetu. A ty musisz zrozumieć, czy przeprowadzałeś rozmowę kwalifikacyjną z konkretnym kandydatem wcześniej. Wystarczy umieścić ten bałagan w makrze filtru, dodać filtr tekstowy po nazwisku — i voila, informacja pojawi się na ekranie.

Warto zauważyć, że filtrowanie ogromnych tabel może wpływać na wydajność systemu i czas ładowania stron, dlatego wrzucenie ogromnej tabeli do filtra to tymczasowe rozwiązanie, lepiej zbudować proces, w którym ludzie nie muszą tworzyć ogromnych, nieczytelnych tabel (przykład procesu znajdzie się na końcu artykułu).

Sortowanie (płatna wtyczka)

Dzięki magicznemu makrowi „Filtr tabel” można również ustawić domyślne sortowanie według dowolnej kolumny i ponumerować wiersze. Lub kliknąć na dowolną kolumnę tabeli umieszczonej w makrze filtru, a następnie nastąpi sortowanie według tej kolumny.

Na przykład, jeśli macie tę samą tabelę z kandydatami i trzeba określić, ile rozmów kwalifikacyjnych przeprowadzono w danym miesiącu — posortujcie według daty i cieszcie się.

Tabele przestawne (płatna wtyczka)

Teraz przejdźmy do ciekawszego przypadku. Wyobraźcie sobie, że wasza tabela jest ogromna i trzeba coś w niej policzyć. Oczywiście można skopiować ją do Excela, policzyć potrzebne dane i załadować je z powrotem do Confluence. Można jednak jednorazowo zastosować makro „Tabela przestawna” i otrzymać ten sam wynik, z tą różnicą, że będzie on aktualizowany.

Na przykład: macie tabelę, w której zbierane są dane o wszystkich pracownikach — gdzie się znajdują i jakie mają stanowiska. Aby policzyć, ile osób jest w każdym mieście, musicie wybrać w makrze „Tabela przestawna” wiersz, według którego będą agregowane dane (lokalizacja) oraz typ operacji (sumowanie).

Naturalnie, można grupować według kilku kryteriów jednocześnie, wszystkie możliwości można zobaczyć w dokumentacji..

Wykresy (płatna wtyczka)

Jak już wspomniałam, nie wszyscy kochają tabele tak bardzo jak ja. Niestety, menedżerowie w większości ich w ogóle nie lubią. Ale wszyscy bardzo lubią jasne, kolorowe wykresy.
Twórcy Confluence o tym na pewno wiedzieli (z pewnością mają też szefostwo, które lubi raporty i wykresy, gdzieżby bez tego). Dlatego można skorzystać z magicznego makra „Wykres z tabeli”. Do tego makra należy wstawić tabelę przestawną z poprzedniego punktu, a voila — wasze szare, nudne dane pięknie zwizualizowane.

Naturalnie, w tym makrze też są ustawienia. Link do dokumentacji każdego makra można znaleźć w trybie edycji tego makra.

Łatwość agregacji

Informacje z wcześniejszych punktów z pewnością nie były dla Ciebie nowością. Ale teraz na pewno potrafisz korzystać z makr, a ja mogę przejść do bardziej interesującej części artykułu.

Tagi

To źle, gdy ludzie przechowują informacje w jednym nieuporządkowanym artykule lub ogromnej tabeli. Jeszcze gorzej, gdy części tych informacji są nieczytelnie sformatowane i rozsiane po przestrzeniach Confluence. Na szczęście istnieje możliwość zebrania rozproszonej informacji w jednym miejscu. W tym celu należy skorzystać z tagów (znanych wszystkim z mediów społecznościowych).

Możesz dodać dowolną liczbę tagów do każdej strony. Klikając na tag, trafisz na stronę agregacji, gdzie znajdują się odnośniki do wszystkich materiałów z tym tagiem, a także związanych tagów. Powiązane tagi to te, które często występują na jednej stronie.

Właściwości stron

Można dodać jeszcze jeden ciekawy makro do strukturyzacji informacji — „Właściwości stron”. Należy wprowadzić do niego tabelę z dwiema kolumnami, pierwsza z nich będzie kluczem, a druga — wartością właściwości. Co ważne, makro można ukryć na stronie, aby nie przeszkadzało w czytaniu treści, jednak strona nadal będzie oznaczona odpowiednimi kluczami.

Zwróć uwagę na ID — jest wygodne do przypisywania różnych grup właściwości do różnych stron (lub nawet różnych grup właściwości do jednej strony).

Raporty

Na podstawie tagów można generować raporty. Na przykład, makro „Raport o treści” zbiera wszystkie strony z określonym zestawem tagów.

Jednak bardziej interesującym raportem jest makro „Raport właściwości strony”. Zbiera wszystkie strony z określonym zestawem tagów, ale nie tylko wyświetla ich listę, lecz tworzy tabelę (łapiesz powiązanie z początkiem artykułu?), w której kolumnami są klucze właściwości strony.

Tworzy to tabelę przestawną z informacji z różnych źródeł. Miło, że ma ono przydatne funkcje: responsywne układanie, sortowanie według dowolnej kolumny. Taką tabelę raportową można również konfigurować wewnątrz makra.

Podczas konfigurowania można usunąć z raportu pewne kolumny, ustawić domyślny stan lub liczbę wyświetlanych rekordów. Można również ustawić ID właściwości strony, aby widzieć tylko potrzebne informacje.

Na przykład macie wiele stron pracowników, a te strony mają zestaw właściwości dotyczących danej osoby: jakiego jest poziomu, gdzie się znajduje, kiedy dołączył do zespołu i tak dalej. Te właściwości są oznaczone ID = employee_inf. Jest również drugi zestaw właściwości na tej samej stronie, w którym zebrane są informacje o osobie jako części zespołu: jaką rolę pełni, w jakim zespole się znajduje itd. Te właściwości są oznaczone ID = team_inf. Wtedy przy tworzeniu raportu możecie wyświetlić tylko informacje według jednego identyfikatora lub od razu według dwóch — w zależności od wygody.

Zaletą takiego podejścia jest to, że każdy może stworzyć potrzebną sobie informacyjną tabelę, która nie będzie niczego dublować i będzie się aktualizować w miarę aktualizacji głównej strony. Na przykład: dla lidera zespołu nie jest istotne, kiedy jego deweloperzy zaczęli pracę, ale ważne jest, jaką rolę każdy z nich pełni w zespole. Lider zespołu stworzy raport o zespole. A księgowy zupełnie nie obchodzi, kto jaką rolę pełni, ale ważne są pozycje — stworzy raport o stanowiskach. Przy tym źródło informacji nie będzie dublowane ani przenoszone.

Proces końcowy

Instrukcja

Zatem możemy pięknie strukturyzować i efektywnie agregować informacje w Confluence na przykładzie użycia makr. Ale w idealnym przypadku należy zrobić tak, aby nowe informacje od razu były ustrukturyzowane i trafiały do wszystkich już używanych mechanizmów agregacji.

Tu z pomocą przyjdzie zestawienie makr i szablonów. Aby zmusić ludzi do tworzenia nowych stron w odpowiednim formacie, można użyć makra „Utwórz z szablonu”. Dodaje ono na stronę przycisk, po naciśnięciu którego tworzona jest nowa strona z odpowiedniego szablonu. W ten sposób zmuszacie ludzi do pracy w pożądanym formacie.

Do szablonu, z którego dajecie możliwość tworzenia strony, należy wcześniej dodać etykiety, makro „Właściwości strony” oraz tabelę potrzebnych właściwości. Rekomenduję również dodanie instrukcji dotyczących tego, jakimi wartościami należy wypełniać stronę oraz wartości właściwości.

Wtedy proces końcowy będzie wyglądał tak:

Tworzycie szablon dla informacji określonego typu.
Do tego szablonu dodajecie etykiety i właściwości strony w makrze.
W dowolnym dogodnym miejscu tworzysz stronę główną z przyciskiem, po kliknięciu na który zakładana jest strona podrzędna według szablonu.
Udostępniasz stronę główną użytkownikom, którzy potencjalnie będą generować potrzebne informacje (według wymaganego szablonu, klikając przycisk).
Zbierasz raport dotyczący atrybutów strony przez etykiety, które zadeklarowałeś w szablonie.
Cieszysz się: masz wszystkie potrzebne informacje w wygodnym formacie.

Pułapki

Jako inżynier jakości mogę śmiało stwierdzić, że nic doskonałego w świecie nie istnieje. Nawet boskie tabele nie są doskonałe. A w powyższym procesie istnieją pułapki.

Jeśli zdecydujesz się zmienić nazwy lub skład atrybutów strony, będziesz musiał zaktualizować wszystkie już utworzone obiekty, aby ich dane poprawnie odzwierciedlały się w zbiorczym raporcie. To smutne, ale z drugiej strony zmusza do starannego przemyślenia „architektury” twojego zestawu informacji, co stanowi dość interesujące zadanie.
Będziesz musiał napisać sporą ilość instrukcji na temat tego, jak wypełniać tabele informacyjne i korzystać z etykiet. Z drugiej strony, możesz po prostu przesłać ten artykuł wszystkim potrzebnym osobom.

Przykład przechowywania dokumentacji niedotyczącej produktów

Za pomocą opisanego powyżej procesu można zorganizować przechowywanie niemal każdej informacji. Urok tego podejścia polega na jego uniwersalności: gdy użytkownicy się do niego przyzwyczają, przestają generować bałagan. Ponadto istotną (ale płatną) zaletą jest możliwość gromadzenia różnorodnej statystyki na bieżąco i tworzenia na jej podstawie pięknych wykresów.

Podam przykład naszego procesu prowadzenia informacji o zespole.

Dla każdej osoby w zespole postanowiliśmy stworzyć kartę pracownika. W związku z tym mamy szablon, według którego każda nowa osoba tworzy tę kartę i prowadzi w niej wszystkie osobiste informacje.

Jak widać, mamy rozwiniętą tabelę atrybutów i od razu są dostępne instrukcje dotyczące prowadzenia tej strony. Część etykiet ustalają sami pracownicy według instrukcji, w szablonie tylko te podstawowe: etykieta karty employee-card, etykieta kierunku direction-involve i etykieta zespołu team-qa.

W rezultacie, po tym jak każdy stworzył swoją kartę, powstaje pełna tabela z informacjami o pracownikach. Te informacje można wykorzystać w różnych miejscach. Menedżerowie zasobów mogą stworzyć ogólne tabele, a liderzy zespołów — tabele zespołowe, dodając do wyboru tag zespołu.

Po tagach można zobaczyć różne podsumowania, na przykład według qa-upgrade-plan wyświetlą się wszystkie zadania dotyczące rozwoju QA. Przy tym każda osoba w swojej karcie pracownika prowadzi ważną historię i swój plan rozwoju — tworzy podrzędną stronę z szablonu planów rozwoju.