Przejdź do:
1. Identyfikator
Identyfikator defektu to po prostu unikatowy ciąg znaków mający na celu poprawne zidentyfikowanie zadania w systemie i szybkie odwoływanie się do niego w razie potrzeby.
Jeśli mamy system zgłaszania błędów
Jeśli wykorzystujemy system zgłaszania błędów, to narzędzia te przypisują identyfikator automatycznie, więc nie musimy się o to martwić.
Jeśli zgłoszeń defektów dokonujemy bez systemu
Jednak w przypadku pracy bez takiego systemu musimy bezwzględnie pamiętać o odpowiednim inkrementowaniu identyfikatorów.
2. Opis defektu
Opis zgłaszanego defektu powinien zawierać informacje służące jako krótki opis zaistniałej sytuacji – jego zadaniem jest nakierowanie programisty na dany kontekst, obszar aplikacji, dzięki czemu będzie miał już na wstępie możliwość zastanowienia się, z czego dany błąd może wynikać. Powinien być krótki – nie więcej niż kilka zdań. Zgłaszający powinien zawrzeć w nim informacje w sposób ogólny – nie skupiać się na szczegółach, które powinny zostać podane na etapie opisu kroków prowadzących do odtworzenia błędu. Sekcja ta ma być niczym „tło”, które stanowi fundament dalszej analizy zgłoszonego błędu.
3. Tytuł
Tytuł powinien ograniczać się do jednego zdania opisującego „w pigułce” co się dzieje – w celu nadania kontekstu. Czasem już sam tytuł może zasugerować priorytet błędu i odpowiednio nakierować myśli osoby odpowiedzialnej za zgłoszenie. Dla zwiększenia czytelności na samym początku można umieścić dodatkowe informacje na temat obszaru aplikacji lub środowiska, używając w tym celu na przykład kwadratowych nawiasów.
Osobiście, często podaję kilka obszarów – w zależności od kontekstu, lecz zawsze w myśl zasady „od ogółu do szczegółu”. Na przykład: [środowisko][moduł] (przykład: [DEV02][STRONA PRODUKTU] Nie można dodać produktu do koszyka).
4. Kroki prowadzące do odtworzenia błędu
Istotne jest napisanie kroków odtworzenia błędu w taki sposób, aby nawet osoba niezaznajomiona z danym obszarem aplikacji (lub osoba nietechniczna w przypadku zgłoszenia błędu dotyczącego obszarów kodu/API, baz danych itd.) była w stanie zrozumieć, co się dzieje i mogła odtworzyć zgłoszony błąd. Każdy krok musi być dokładnym i krótkim opisem czynności, które razem będą stanowić ścieżkę prowadzącą do odtworzenia defektu.
Dobre praktyki:
- Kroki należy dodawać w formie krótkich zdań (w miarę możliwości jeden krok = jedna czynność)
- Każdy krok powinien być napisany w osobnej linii
- W przypadku podawania parametrów – należy je wyraźnie zaznaczyć, na przykład poprzez pogrubienie lub umieszczenie w nawiasach, cudzysłowach (temat ten zostanie opisany bardziej szczegółowo w sekcji „Formatowanie” niniejszego artykułu)
- Jeśli do odtworzenia błędu niezbędne jest podanie danych – należy umieścić je w krokach jako konkretny parametr (na przykład w kroku opisującym logowanie zamiast informacji „zaloguj się do konta” powinniśmy podać login oraz hasło i opisać krok jako „zaloguj się na konto X, używając hasła Y”)
- Od strony gramatycznej – kroki najlepiej pisać w trybie rozkazującym drugiej osoby („kliknij”, „zaloguj się”, „podaj liczbę” itd.)
- Nie należy pomijać w krokach informacji, które z punktu widzenia zgłaszającego mogą wydawać się oczywiste (pamiętajmy o zasadzie, że nawet osoba, która widzi projekt po raz pierwszy, powinna być w stanie samodzielnie odtworzyć zgłoszony błąd)
- Kroki powinny być pisane zgodnie z definicją niskopoziomowego przypadku testowego – a więc ewentualne parametry muszą zawierać konkretne wartości. Przykład: dodanie produktu do koszyka z poziomu strony produktu – krok „dodaj produkt do koszyka” powinien zostać uściślony – „dodaj 1 produkt do koszyka”, gdzie 1 jest parametrem – ogranicza to możliwość niepowodzenia w odtworzeniu błędu, ponieważ często zdarza się, że błędy można odtworzyć tylko z podaniem konkretnych wartości (na przykład wartości brzegowych pewnych klas równoważności)
- Kroki muszą być pisane sekwencyjnie – najlepiej, aby były ponumerowane
- Odwołując się do elementów interfejsu użytkownika (na przykład przycisków na stronie) – należy podawać ich nazwy w sposób identyczny z tekstem widocznym na stronie, pamiętając o odpowiednim sformatowaniu go w celu zwiększenia czytelności
Dokładne opisanie kroków jest jedną z najważniejszych czynności w zgłaszaniu defektów. Jako autorzy, poświęcając odrobinę więcej czasu na ich dokładny opis, jednocześnie zmniejszamy czas potrzebny do rozwiązania defektu. Dzięki temu programista nie musi domyślać się, co mieliśmy na myśli i ma możliwość użycia konkretnych danych, które zwiększają prawdopodobieństwo odtworzenia błędu za pierwszym razem. Ułatwiamy to zadanie również innym osobom zaangażowanym w projekt.
5. Rezultat aktualny i oczekiwany
Są to dwie niezbędne, komplementarne sekcje, w których należy opisać aktualny stan systemu (a więc konkretny defekt) oraz stan oczekiwany (czyli opis poprawnego zachowania aplikacji po przejściu wszystkich kroków).
Aktualny rezultat
W sekcji „aktualny rezultat” należy opisać, co dzieje się z systemem po przejściu ostatniego kroku replikacji błędu: co widzimy, na co zwrócić szczególną uwagę lub gdy jakaś część błędu nie jest widoczna natychmiast – zaznaczyć, że należy odczekać chwilę do pojawienia się lub otrzymania dalszych informacji. Opis ten musi zawierać informacje ściśle powiązane ze zgłoszonym defektem. W przypadku informacji pochodzących z serwera dobrym pomysłem będzie również podanie powiązanego endpointa API z fragmentem (lub całością) zwróconej odpowiedzi oraz innych informacji istotnych z tego punktu widzenia.
Oczekiwany rezultat
W tym miejscu należy opisać poprawne zachowanie systemu, które powinno wystąpić po wykonaniu wszystkich kroków replikacji. Żeby zwiększyć czytelność oraz ułatwić proces odtwarzania, sekcja „aktualny rezultat” powinna pojawić się tuż po sekcji opisującej kroki replikacji – defekt istnieje, a więc jest to naturalna, sekwencyjna kolejność czytania zgłoszonego błędu linia po linii. Dopiero po opisie aktualnego rezultatu dodajemy informacje na temat zachowania oczekiwanego.
6. Środowisko
Podanie informacji o środowisku, na którym wykryto defekt, jest kluczowe w celu szybkiego rozpoczęcia próby jego odtworzenia. Często zdarza się, że znaleziony błąd jest możliwy do odtworzenia tylko w konkretnej wersji aplikacji lub systemu, na którym jest zainstalowana. Na przykład wieloplatformowa aplikacja w pewnych okolicznościach może nie działać tylko na konkretnym systemie operacyjnym. Idąc dalej – może okazać się, że nie działa tylko z daną wersją owego systemu operacyjnego, a być w pełni funkcjonalna z inną. Przez „środowisko” rozumiem również infrastrukturę samej aplikacji, opierającą się na rozdzieleniu projektu na wersje (które mogą mieć kilka środowisk), na przykład: developerska, testowa, produkcyjna. W tym przypadku należy również pamiętać o podaniu odpowiedniej wersji, w której znaleźliśmy błąd.
To tylko kilka przykładów, które pokazują, że dodanie obszernej informacji na temat środowiska aplikacji jest równie ważne co dokładne opisanie kroków prowadzących do odtworzenia błędu.
7. Informacje na temat zgłaszającego
Dane dotyczące osoby zgłaszającej defekt są istotne przede wszystkim w kwestii kontaktu – w przypadku jakichkolwiek pytań wiemy, do kogo należy się zgłosić.
8. Priorytet
W tym polu należy ustalić priorytet dla zgłaszanego błędu. Określa on pilność – im wyższy priorytet, tym szybciej należy rozpocząć prace nad naprawieniem błędu.
9. Ważność
Dodatkowo w parze ze statusem powinno pojawić się pole „severity” – ważność określające, jak duży wpływ na działanie aplikacji ma zgłaszany defekt. Tak jak w przypadku priorytetu – im wyższa wartość, tym większy wpływ defektu na działanie systemu.
10. Przypisanie do konkretnej osoby
W zależności od przyjętego procesu należy zadbać o to, aby zgłoszenie nie zostało zbyt szybko „zapomniane”. Jeśli nie przypiszemy zgłoszenia do konkretnej osoby, może się zdarzyć, że zadanie zagubi się gdzieś w liście zadań w Backlogu. Dodatkowo możemy zaobserwować zjawisko tzw. rozproszonej odpowiedzialności – osoby w zespole będą przekonane, że zajmie się tym ktoś inny, bardziej odpowiedni.
W metodykach zwinnych zadania powinny być wykonywane zgodnie z ich ważnością przez osobę, która posiada wystarczającą ilość czasu, aby się nimi zająć. W celu zwiększenia pewności, że praca nad zgłoszeniem rozpocznie się szybko, można przypisać je do obecnego lub kolejnego Sprintu (najlepiej skonsultować to z zespołem). W przypadku, gdy zgłoszenie jest efektem zmiany stworzonej przez konkretnego programistę – można przypisać je bezpośrednio do niego. Jeszcze innym sposobem jest przypisanie zadania do Product Managera / Product Ownera, który po zapoznaniu się z jego treścią przepnie zadanie do odpowiedniego programisty oraz nada mu odpowiedni priorytet.
11. Opcje nieobowiązkowe
Poniżej opisane opcje nie są obowiązkowe podczas tworzenia opisu błędu, niemniej użycie ich sprawi, że opis będzie jeszcze bardziej czytelny i dokładny. Spędzenie kilku dodatkowych minut na ich dodanie może wyeliminować na przykład: potencjalne dwuznaczności, dodatkowy czas programisty na przeszukiwanie logów, dzięki czemu czas poświęcony na analizę i zrozumienie zgłoszenia zostanie zredukowany do minimum.
Tagi
Dodanie informacji w postaci tagu do zgłaszanego błędu pomoże przy filtrowaniu oraz przeszukiwaniu systemu do zarządzania defektami w celu znalezienia błędów dotyczących konkretnych obszarów aplikacji, wydań (release) itd.
Powtarzalność
Opis częstotliwości sukcesu w próbach odtwarzania błędu można pominąć, gdy zgłaszany defekt jesteśmy w stanie odtworzyć za każdym razem. Jednak gdy błąd z bliżej nieokreślonych przyczyn jesteśmy w stanie odtworzyć X razy na Y liczbę prób lub na przykład jedynie w określonej części dnia – te dodatkowe informacje będą również przydatne na etapie analizowania błędu, ponieważ potencjalnie będą mogły zawęzić obszar poszukiwań.
Załączniki
Nawet najdokładniejszy opis może okazać się niewystarczający, szczególnie w przypadku, gdy droga do odtworzenia błędu jest skomplikowana (niejednoznaczne elementy UI, niezbędne akcje w zintegrowanych systemach, dane do importu itd.) Wówczas pomocne okażą się załączniki. Można dodawać je w celu wskazania konkretnego elementu interfejsu graficznego w którymś z kroków replikacji lub po prostu jako informację dodatkową, by ułatwić zrozumienie kontekstu problemu na dowolnym etapie jego odtwarzania. Dobrym pomysłem jest również nagranie krótkiego filmu zawierającego kroki replikacji. Dzięki temu w przypadku niejasności przy którymś z opisanych kroków programista będzie mógł bez trudu odnaleźć dany etap.
Należy przy tym pamiętać, aby zachować umiar. Zbyt wiele załączników może wprowadzić chaos i sprawić, że utworzone zadanie będzie „przytłaczające”. Zmniejszy się przejrzystość, a w przypadku konieczności np. poszukiwania konkretnego zrzutu ekranu (faktycznie pomocnego) wśród dziesiątek zbędnych plików może być frustrująca i powodować zmniejszenie skupienia na błędzie. Z tego powodu załączniki powinno się dodawać tylko wtedy, gdy mogą być naprawdę przydatne, na przykład:
- są niezbędne w procesie odtworzenia błędu (np. konkretny plik z danymi do importu)
- uważamy, że opisywany element aplikacji (np. w krokach replikacji, aktualnym rezultacie itp.) może być niejednoznaczny dla osoby, która będzie pracowała z nim po raz pierwszy
- stwierdzamy, że odtworzenie błędu jest na tyle skomplikowane, że dobrze będzie nagrać cały proces i załączyć go w formie krótkiego video
- mamy dostęp do logów zawierających informacje dotyczące błędu – wtedy również dołączmy taki plik do zgłoszenia
Linki do podobnych zgłoszeń
Jeśli istnieje taka możliwość, podanie linków do podobnych błędów zgłoszonych w przeszłości może być niezwykle przydatne. Niejednokrotnie może okazać się, że podobny (lub nawet identyczny) defekt istniał w przeszłości, a obecne zadanie (zakładając, że było dobrze dokumentowane, na przykład komentarzami oraz linkiem do brancha zawierającego poprawkę) będzie mogło zostać naprawione błyskawicznie dzięki zaimplementowaniu znanego już rozwiązania. W połączeniu z używaniem tagów (punkt 10) – będziemy mieli także możliwość usprawnienia nieco zarządzania ryzykiem w pewnych obszarach aplikacji. Filtrowanie po konkretnym tagu pokaże błędy zgłoszone w jego kontekście – dzięki czemu będziemy mogli dowiedzieć się, ile, z jaką częstotliwością oraz jakiego typu błędy zgłaszane są dla danego obszaru aplikacji (np. tag „koszyk” – 35 błędów; tag „lista życzeń” – 3 błędy). Pozwoli to nam lepiej oszacować czas oraz priorytetyzować obszary aplikacji potencjalnie najbardziej narażone na błędy.
Formatowanie zgłoszenia
Zastosowanie odpowiedniego formatowania w zgłaszanych błędach nie jest niezbędne, lecz bardzo pomaga w szybkim zrozumieniu i odnalezieniu się w strukturze zgłoszenia. Dzięki niemu już na pierwszy rzut oka widać, jakie sekcje są opisywane i jakie akcje będą w nich do wykonania.
Dobrym pomysłem będzie ujednolicenie formatowania i ustalenie pewnych reguł, których będziemy przestrzegać przy zgłaszaniu defektów (spisanie ich lub utworzenie przykładowego szablonu). Dzięki temu cały zespół będzie mógł zgłaszać błędy, korzystając z jednolitej struktury, a osoby analizujące opis – będą wiedziały w każdym aspekcie „co autor miał na myśli”.
Przykładowo:
- wszystkie parametry opisujemy, używając kursywy
- przyciski na stronie opisujemy, używając podkreślenia
- wszelkie pola tekstowe oznaczamy, umieszczając ich nazwy w nawiasach <>
- każde sekcje w zgłoszeniu piszemy, korzystając z nagłówka h3, dużymi literami i pogrubioną czcionką
- ewentualny blok kodu formatujemy, używając fontu Consolas – pamiętając o zachowaniu jego struktury
- teksty oznaczamy, umieszczając je w cudzysłowie
Poniżej porównanie przykładu zgłoszenia z zachowaniem proponowanego formatu (po lewej) oraz to samo zgłoszenie bez formatowania (po prawej):
Informacje dodatkowe
Na koniec zaproponuję jeszcze kilka dobrych praktyk, które powinny towarzyszyć nam na co dzień w kontekście zgłaszania defektów. Dzięki ich przestrzeganiu praca stanie się jeszcze bardziej efektywna nie tylko dla nas, ale i całego zespołu projektowego.
- Jeżeli nie mamy 100% pewności, że zastany przez nas rezultat w działaniu aplikacji to na pewno błąd – skonsultujmy to z inną osobą z zespołu, zanim zgłosimy raport o błędzie.
- W przypadku pracy zdalnej – gdy napotkamy błędy związane z brakiem możliwości połączenia się do serwera – upewnijmy się, że jesteśmy wciąż podłączeni do sieci VPN.
- Upewnijmy się, że w czasie znalezienia defektu nie są przeprowadzane żadne aktualizacje środowiska – może okazać się, że dany serwis jest w tym samym momencie aktualizowany i dlatego pewien obszar aplikacji nie działa.
- Po napisaniu kroków replikacji przejdźmy samodzielnie proces odtwarzania błędu, wcielając się w osobę, do której może trafić nasze zadanie. W ten sposób będziemy mogli wyłapać ewentualne nieścisłości i poprawić instrukcje tak, aby były jednoznaczne i jeszcze bardziej czytelne.
- Jeżeli w projekcie jest zaimplementowane narzędzie do monitorowania stanu aplikacji (np. Splunk, New Relic), nie wahajmy się wykorzystać go w celu znalezienia logu błędu i dodania go do tworzonego przez nas zgłoszenia.
- W miarę możliwości, zanim zgłosimy defekt, upewnijmy się, że w systemie nie jest on już zgłoszony. W ten sposób unikniemy duplikatów.
- W przypadku wątpliwości co do opisu zadania już stworzonego, skontaktujmy się z autorem i poinformujmy go, że chcemy uzupełnić jego opis o dodatkowe informacje, które mogą okazać się pomocne.
Podsumowanie
Dzięki przestrzeganiu tych kilku zasad możemy być prawie pewni, że zadanie zostanie dobrze zrozumiane, a przyczyna błędu celnie zdiagnozowana – wskutek czego znalezione awarie zostaną rozwiązane najszybciej, jak to możliwe.
