Witam wszystkich!
Nazywam się Masza, pracuję jako inżynier ds. zapewnienia jakości w grupie firm Tinkoff. Praca QA wiąże się z dużą komunikacją z różnymi osobami z różnych zespołów, a także byłem menadżerem i wykładowcą programów edukacyjnych, więc moja mapa komunikacyjna była jak najszersza. I w pewnym momencie eksplodowałem: zdałem sobie sprawę, że nie mogę, nie mogę, nie mogę wypełniać piekielnych ton nieczytelnych tabel i dokumentów.
Z pewnością każdy z Was już sobie wyobrażał, o czym mówię, i oblał się zimnym potem: listy nazwisk bez kolejności alfabetycznej, tabele z setkami kolumn o krzywym układzie, tabele z tysiącami wierszy, w których trzeba wytrzeć palec kółkiem myszy, żeby zobaczyć nagłówek, tony stron nienumerowanych instrukcji, setki wysyłanych do siebie listów z danymi, które należy przeanalizować, usystematyzować i upchnąć w równie nieczytelne tabele.
I tak, kiedy już trochę ochłonąłem, postanowiłem napisać ten artykuł. Opowiem o tym, jak można normalnie (nawet czasami wygodnie) prowadzić różnorodną dokumentację niezwiązaną z produktem. Mam nadzieję, że artykuł rozprzestrzeni się po Internecie i poziom piekła w wydziałach sąsiadujących z inwestycją choć trochę zmniejszy się, a ludzie (w tym ja) staną się choć trochę szczęśliwsi.
Narzędzia
Dokumentacja produktu często jest przechowywana obok kodu, co jest dobrą rzeczą. Dokumentacja niezwiązana z produktem jest zwykle przechowywana w dowolnym miejscu. Ludzie często próbują przenosić informacje z różnych miejsc do Confluence i my nie jesteśmy tu wyjątkiem. Zatem dalsza część historii dotyczy niego.
Ogólnie rzecz biorąc, Confluence jest zaawansowanym silnikiem wiki. Umożliwia pracę z danymi w różnych typach wyświetlania: tekst z formatowaniem, tabele, różne wykresy. To bardzo ciekawe i potężne narzędzie, ale jeśli nie wiesz, jak je przygotować, skończy się to kolejnym zrzutem nieczytelnych dokumentów. Nauczę Cię gotować!
Makra
Prawie cała magia Confluence pochodzi z makr. Makr jest mnóstwo i można je ze sobą łączyć. Mogą być płatne lub bezpłatne, poniżej znajdują się różne przykłady makr wraz z linkami do dokumentacji do nich.
Interfejs do pracy z makrami jest tak prosty, jak to tylko możliwe. Aby dodać makro należy kliknąć na plus i wybrać żądany element z listy.
Jeśli makro jest samodzielne, to znaczy nie wymaga wstawiania niczego innego do siebie, wygląda jak blok.
Jeśli makro wymaga umieszczenia czegoś w środku, aby mogło działać, wygląda jak ramka.
Jednocześnie możesz umieścić dowolną liczbę innych w jednej ramce, o ile w twojej piramidzie jest logika.
Każde makro posiada podgląd: od razu widać, czy poprawnie wypełniłeś i skonfigurowałeś makro.
Szablony
Oprócz makr dostępne jest wygodne narzędzie do wstępnego uzupełniania treści – szablon.
Szablonów można używać podczas tworzenia dowolnej strony: wystarczy kliknąć trzy kropki obok przycisku „Utwórz” i wybrać żądany szablon.
Następnie cała zawartość znajdująca się w szablonie zostanie dodana do utworzonej strony.
Każdy może tworzyć strony na podstawie szablonów, ale mogą to robić tylko osoby posiadające uprawnienia do samodzielnego tworzenia lub edytowania szablonów. Do szablonu możesz dodać dodatkowe instrukcje dotyczące sposobu utrzymywania strony.
Magia stołów
Właściwie, jako technik, bardzo kocham tabele i mogę zawrzeć w nich prawie każdą informację (choć nie zawsze jest to skuteczne). Same tabele są przejrzyste, uporządkowane, skalowalne, magiczne!
Ale nawet tak cudowną istotę jak stół można zrujnować. I można go z powodzeniem wykorzystać, a nawet ulepszyć. Więcej na ten temat poniżej.
Filtrowanie (wtyczka płatna)
Dowolną ogromną, nieczytelną tabelę można zmniejszyć i uczynić bardziej czytelną za pomocą filtrowania. Możesz do tego użyć płatnego makra .
Musisz umieścić tabelę w tym makrze (nawet najbrzydsza jest możliwa, najważniejsze jest, aby wcisnąć ją w całości). W makrze możesz wybrać kolumny dla filtra rozwijanego, filtru tekstowego, filtru liczbowego i filtru daty.
Wyobraź sobie, że wszystkie informacje o kandydatach na wszystkie wolne stanowiska są zapisane na liście tabelarycznej. Naturalnie nieposortowane – ludzie przychodzą na rozmowy kwalifikacyjne nie w kolejności alfabetycznej. Musisz także zrozumieć, czy rozmawiałeś już z konkretnym kandydatem. Wystarczy umieścić to piekło w makro filtrującym, dodać filtr tekstowy według nazwiska - i voila, informacja jest na ekranie.
Warto zauważyć, że filtrowanie dużych tabel może mieć wpływ na wydajność systemu i czas ładowania strony, więc umieszczenie dużej tabeli w filtrze jest tymczasowym rozwiązaniem; lepiej zbudować proces, w którym ludzie nie będą musieli tworzyć ogromnych, nieczytelnych tabel (np. przykład procesu będzie na końcu artykułu).
Sortowanie (wtyczka płatna)
Korzystanie z magicznego makra Możesz także ustawić domyślne sortowanie dowolnej kolumny i ponumerować wiersze. Lub kliknij dowolną kolumnę tabeli wstawioną do makra filtrującego, a sortowanie nastąpi według tej kolumny.
Przykładowo, masz tę samą tabelę z kandydatami i musisz oszacować, ile rozmów kwalifikacyjnych odbyło się w danym miesiącu – posortuj według daty i bądź szczęśliwy.
Tabele przestawne (wtyczka płatna)
Przejdźmy teraz do ciekawszego przypadku. Wyobraź sobie, że Twój stół jest ogromny i musisz coś z niego obliczyć. Możesz oczywiście skopiować go do Excela, obliczyć, czego potrzebujesz i przesłać dane z powrotem do Confluence. Czy można raz użyć makra? i uzyskaj ten sam wynik, tylko zaktualizowany.
Na przykład: masz tabelę, która zbiera dane od wszystkich pracowników - gdzie się znajdują i jakie stanowiska zajmują. Aby obliczyć, ile osób znajduje się w każdym mieście, należy wybrać wiersz w makrze tabeli przestawnej, który agreguje dane (lokalizacja) i typ operacji (dodawanie).
Oczywiście możesz grupować według kilku kryteriów jednocześnie, możesz przeglądać wszystkie możliwości .
Wykresy (wtyczka płatna)
Jak już mówiłem, nie wszyscy kochają stoły tak bardzo jak ja. Niestety większość menedżerów w ogóle ich nie lubi. Ale wszyscy naprawdę uwielbiają diagramy w jasnych kolorach.
Twórcy Confluence z pewnością o tym wiedzieli (zapewne też mają szefów, którzy kochają raporty i diagramy, bo gdzie by byli bez tego). Dlatego możesz użyć magicznego makra . W tym makrze musisz umieścić tabelę przestawną z poprzedniego akapitu i voila - Twoje szare, nudne dane są pięknie zwizualizowane.
Oczywiście to makro ma również ustawienia. Link do dokumentacji dowolnego makra znajdziesz w trybie edycji tego makra.
Łatwa agregacja
Informacje z poprzednich akapitów prawdopodobnie nie były dla Ciebie rewelacją. Ale teraz na pewno wiesz, jak korzystać z makr i mogę przejść do ciekawszej części artykułu.
tagi
Źle jest, gdy ludzie przechowują informacje w jednym nieustrukturyzowanym artykule lub w ogromnej tabeli. Jeszcze gorzej jest, gdy części tych informacji są nie tylko nieczytelnie sformatowane, ale także rozproszone po całym Confluence. Na szczęście możliwe jest zebranie rozproszonych informacji w jednym miejscu. Aby to zrobić, musisz użyć (tagi znane każdemu z sieci społecznościowych).
Do dowolnej strony możesz dodać dowolną liczbę tagów. Kliknięcie tagu przeniesie Cię do strony zbiorczej zawierającej linki do całej treści oznaczonej tym tagiem, a także zestaw powiązanych tagów. Powiązane tagi to te, które często pojawiają się na tej samej stronie.
Właściwości strony
Możesz dodać kolejne ciekawe makro do strony, aby uporządkować informacje - . Wewnątrz niego musisz przesłać tabelę składającą się z dwóch kolumn, pierwsza będzie kluczem, a druga wartością właściwości. Co więcej, makro można ukryć na stronie tak, aby nie przeszkadzało w czytaniu treści, ale strona nadal będzie oznaczona niezbędnymi kluczami.
Zwróć uwagę na identyfikator - wygodnie jest ustawić go tak, aby przypisywał różne grupy właściwości do różnych stron (lub nawet różne grupy właściwości do jednej strony).
Raporty
Możesz zbierać raporty za pomocą tagów. Na przykład makro zbiera wszystkie strony z określonym zestawem tagów.
Ale ciekawszym raportem jest makro . Zbiera także wszystkie strony z określonym zestawem tagów, ale nie tylko wyświetla ich listę, ale tworzy tabelę (łapiesz połączenie z początkiem artykułu?), w której kolumny są stroną klucze nieruchomości.
Rezultatem jest tabela podsumowująca informacje z różnych źródeł. Fajnie, że ma wygodne funkcje: adaptacyjny układ, sortowanie według dowolnej kolumny. Również taką tabelę raportowania można skonfigurować wewnątrz makra.
Podczas konfiguracji możesz usunąć niektóre kolumny z raportu, ustawić stan domyślny lub liczbę wyświetlanych rekordów. Możesz także ustawić identyfikator właściwości strony, aby wyświetlać tylko potrzebne informacje.
Na przykład masz wiele stron pracowników, strony te mają zestaw właściwości dotyczących danej osoby: na jakim jest poziomie, gdzie się znajduje, kiedy dołączył do zespołu i tak dalej. Te właściwości są zaznaczone Identyfikator = dane_pracownika. Na tej samej stronie znajduje się drugi zestaw właściwości, który zawiera informacje o danej osobie jako części zespołu: jaką rolę odgrywa dana osoba, w jakim zespole się znajduje i tak dalej. Te właściwości są zaznaczone Identyfikator = zespół_inf. Następnie podczas tworzenia raportu możesz wyświetlić informacje tylko dla jednego identyfikatora lub dwóch na raz - w zależności od tego, co jest wygodniejsze.
Piękno tego podejścia polega na tym, że każdy może ułożyć potrzebną mu tabelę informacyjną, która niczego nie powiela i będzie aktualizowana po aktualizacji strony głównej. Przykładowo: dla lidera zespołu nie ma znaczenia, kiedy jego programiści dostali pracę, ale ważne jest, jaką rolę każdy z nich pełni w zespole. Lider zespołu zbierze raport na temat zespołu. A księgowego na ogół nie obchodzi, kto pełni jaką rolę, ale stanowiska są ważne - sporządzi raport na temat stanowisk. W takim przypadku źródło informacji nie będzie powielane ani przekazywane.
Proces końcowy
Instrukcja
Możemy zatem pięknie uporządkować i efektywnie agregować informacje w Confluence na przykładzie makr. Idealnie byłoby jednak, gdyby nowe informacje zostały natychmiast ustrukturyzowane i ujęte we wszystkich już używanych mechanizmach agregacji.
Tutaj na ratunek przyjdzie mnóstwo makr i szablonów. Aby zmusić użytkowników do tworzenia nowych stron w żądanym formacie, możesz użyć makra Utwórz z szablonu. Dodaje przycisk do strony, po kliknięciu tworzona jest nowa strona z potrzebnego szablonu. W ten sposób zmuszasz ludzi do natychmiastowej pracy w formacie, którego potrzebujesz.
W szablonie, z którego tworzysz stronę, musisz wcześniej dodać etykiety, makro „Właściwości strony” i tabelę potrzebnych właściwości. Polecam także dodanie instrukcji jakie wartości należy wypełnić na stronie oraz wartości właściwości.
Następnie końcowy proces będzie wyglądał następująco:
- Tworzysz szablon dla określonego typu informacji.
- W tym szablonie dodajesz etykiety i właściwości strony w makrze.
- W dowolnym dogodnym miejscu utwórz stronę główną za pomocą przycisku, którego kliknięcie spowoduje utworzenie strony podrzędnej z szablonu.
- Pozwalasz użytkownikom przejść do strony głównej, która potencjalnie wygeneruje niezbędne informacje (zgodnie z wymaganym szablonem, klikając przycisk).
- Zbierasz raport na temat właściwości strony za pomocą tagów określonych w szablonie.
- Raduj się: masz wszystkie niezbędne informacje w wygodnym formacie.
Pułapki
Jako inżynier jakości mogę śmiało powiedzieć, że na świecie nie ma nic idealnego. Nawet boskie stoły są niedoskonałe. W powyższym procesie występują pułapki.
- Jeśli zdecydujesz się na zmianę nazw lub składu właściwości strony, będziesz musiał zaktualizować wszystkie już utworzone obiekty, aby ich dane zostały poprawnie uwzględnione w raporcie podsumowującym. To smutne, ale z drugiej strony zmusza do szczegółowego przemyślenia „architektury” swojego zbioru informacji, co jest bardzo interesującym zadaniem.
- Będziesz musiał napisać sporo instrukcji dotyczących wypełniania tabel informacyjnych i używania tagów. Ale z drugiej strony, tym artykułem możesz po prostu trafić do wszystkich właściwych osób.
Przykład przechowywania dokumentacji nieproduktowej
Dzięki procesowi opisanemu powyżej możesz zorganizować przechowywanie niemal każdej informacji. Piękno tego podejścia polega na tym, że jest ono uniwersalne: gdy użytkownicy się do niego przyzwyczają, przestają generować bałagan. Dużym (choć nie darmowym) plusem jest także możliwość zbierania na bieżąco różnych statystyk i rysowania na ich podstawie pięknych diagramów.
Podam przykład naszego procesu przechowywania informacji o zespole.
Postanowiliśmy stworzyć kartę pracownika dla każdej osoby w zespole. W związku z tym mamy szablon, według którego każda nowa osoba tworzy dla siebie tę kartę i przechowuje w niej wszystkie dane osobowe.
Jak widać, mamy szczegółową tabelę właściwości i od razu mamy instrukcje, jak dokładnie zarządzać tą stroną. Część tagów dodawana jest przez samych pracowników zgodnie z instrukcją, szablon zawiera tylko te główne: tag na kartę karta pracownika, znacznik kierunku kierunek-zaangażuj się i tag zespołu zespół-qa.
W rezultacie, po tym jak każdy stworzył dla siebie kartę, otrzymuje się kompletną tabelę z informacjami o pracownikach. Informacje te można wykorzystać w różnych momentach. Menedżerowie zasobów mogą samodzielnie gromadzić tabele ogólne, a liderzy zespołów mogą tworzyć tabele zespołowe, dodając tag zespołu do zaznaczenia.
Możesz na przykład zobaczyć różne podsumowania według tagów qa-plan aktualizacji Wyświetlone zostaną wszystkie zadania programistyczne kontroli jakości. Jednocześnie każda osoba przechowuje w swojej karcie pracownika ważną historię i własny plan rozwoju - tworzy zagnieżdżoną stronę z szablonu planów rozwoju.
wniosek
Każdą dokumentację prowadź w taki sposób, aby nie było w niej wstydu i nie sprawiała użytkownikom straszliwego bólu!
Mam wielką nadzieję, że artykuł będzie przydatny i zapanuje porządek w całej dokumentacji na świecie.
Źródło: www.habr.com