Cześć ,

przechodząc sobie od projektu do projektu, zauważyłem jeden wspólny mianownik. I choć projekty były bardzo zróżnicowane - jedne z obszarów bankowości, inne z dotykały mocno edukacji, a jeszcze inne były realizowane dla pewnego nietypowego klienta z Arabii Saudyjskiej, miały coś wspólnego.

Dokumentację. I niechęć do jej pisania. Bo przyznaj - chce Ci się ją pisać? Masz ją w ogóle w projekcie?

Dziś słów kilka o projektowej dokumentacji, e-booku oraz wstępnej zapowiedzi bezpłatnego Q&A dla Ciebie. Będzie długo i konkretnie, więc nie przeciągam i zapraszam do lektury 😉

Zostały jeszcze trzy bilety na warsztaty QA vs Klient. W trakcie tego 4,5-godzinnego spotkania popracujesz w grupie nad jakością aplikacji, a następnie omówisz stan i wybronisz swoje decyzje przed klientem, w którego się wcielę. To samo mięsko i dużo praktyki! Omówienie biznesowe zajmie nam jakieś 10 do 15 minut, a potem ruszamy do boju! Dołącz do nas, spotykamy się 21 września o 18:00 (do 22:30). Koszt tego spotkania to 60 PLN. Jeżeli odczytujesz maila z opóźnieniem, po prostu sprawdź koszyk - jeżeli uda się dodać produkt, będzie można go kupić. Po sprzedaniu wszystkich biletów, koszyk zostanie automatycznie zablokowany.

Niestety dzisiejsze czasy są uzależnione od social mediów. Dlatego też bardzo Cię proszę - jeżeli widzisz, że dostarczam wartość i otrzymujesz ode mnie dużo korzyści, zaobserwuj mnie, ale również podziel się łapką w górę, udostępnij wpis swoim znajomym czy skomentuj coś raz na jakiś czas. Bardzo mi to pomoże i pozwoli robić dalej dobrze 😉

Udzielam się głównie na LinkedIn. Znajdziesz mnie również na Facebooku, Instagramie oraz YouTube. Na Instagramie pojwiła się kolejna część naszej zabawy "Znajdź robaczka".

Jaka powinna być dobra dokumentacja? Prosta, przejrzysta i czytelna. Zapisz te trzy słowa na kartce, przyklej ją do monitora i niech przyświecają przez cały proces wytwarzania oprogramowania.

Dokumentacja to miejsce, które przyspiesza to, co chcemy zrobić. Jeżeli więc trafiamy do przestrzeni, gdzie przez kolejne trzydzieści minut będziemy szukać odpowiedzi – oznaczać to będzie, że skopaliśmy zadanie, a naszą dokumentację możemy wyrzucić do kosza. Wyobraź sobie programistę, który kończy już swoje zadanie, jest piątek, 15:45. Za piętnaście minut chce iść na zasłużony odpoczynek. Musi jeszcze tylko wpiąć token autoryzacyjny i gotowe! Token jest dostępny w dokumentacji (nie polecam tego rozwiązania – wszelkie hasła, tokeny i poufne dane powinny być zapisywane w firmowych menadżerach haseł!). Nasz programista wchodzi więc do dokumentu i… no właśnie. Co dalej? Gdzie to może być? W zakładce „informacje ogólne”? Nie, tam jest coś o spotkaniach. Może w „autoryzacja”? Nie, tam jest jakiś skrypt do łączenia z bazą danych. Może więc w „tokeny”? Nie, tu są tokeny do endpointów API. Nie tego szukamy. O, jest coś takiego jak „dla programistów!”. Ah, tu PM wpisał „pamiętaj o logowaniu czasu”. Dowcipniś. No nic, wyszukiwarka. „token: 92 wyniki”. „token autoryzacyjny: 61 wyników”. I po weekendzie.

Niech ta historia utkwi Ci w pamięci. Taka dokumentacja prawdopodobnie nie spełniła żadnych z trzech filarów:

• nie jest prosta, bo skoro wyszukało prawie sto pozycji o tokenie, być może jest przeładowana zbędnymi informacjami,
• nie jest przejrzysta, bo nazwy kategorii/zakładek nie odpowiadały temu co było w środku – lub nie były na tyle jasne i zrozumiałe,
• nie jest czytelna – bo jednak programista miał problem ze znalezieniem tu czegokolwiek.

W moich projektach sprawdziły się dwa rozwiązania.

• Confluence – jeżeli korzystasz z Jiry, a z dużym prawdopodobieństwem tak jest, masz coś takiego jak Confluence. Czasami będzie to domyślnie włączone, czasami musisz poprosić administratora o dodanie tego do Twojego projektu. To nic innego jak rozwiązanie Atlassiana do tworzenia bloga projektowego. Czym jest blog projektowy? Zbiorem informacji.

Jeżeli korzystasz z mojego autorskiego szkolenia dla przyszłych Quality Assurance, to rozwiązanie powinno być Ci już znane lub lada moment będzie – gdy dotrzesz do odpowiedniego modułu. Jeżeli jesteś samoukiem, możesz założyć bezpłatne konto w Jira i dodać tam Confluence. Jeżeli pracujesz już w firmie – rozwiązanie to będzie uzależnione od podjętych decyzji projektowych.

Nie jest to miejsce, by omawiać konfigurację Confluence, ale dodam jedną istotną rzecz – przestrzeń ta umożliwia kontrolę nad dostępami. Możesz więc wrzucić dostęp wszystkim w ramach projektu lub wybranym osobom. Dzięki temu na jednej przestrzeni mogą pracować analitycy biznesowi, klienci, CTO, CEO, QA i inni specjaliści – z dostępem tylko do swoich zakładek. To bardzo pomaga przy organizacji skomplikowanych projektów, które dzielą się na podprojekty i wiele różnych zespołów.

• Google Docs – prawdopodobnie nie będzie to wielkim zaskoczeniem, że Google Docs pojawiło się w tym zestawieniu. Jeżeli korzystasz z Gmaila w swojej firmie, masz dostęp również do edytora tekstowego. Tworząc dokumentację w takim dokumencie, możesz wykorzystać różne nagłówki i stworzyć tym samym konspekt, dzięki któremu dużo łatwiej będzie się poruszać po dokumencie.

Narzędzie nie wymaga żadnej konfiguracji, dorzucania do istniejących projektów – po prostu trzeba zacząć pisać, a następnie udostępnić wybranym osobom. To też jest ważne – tylko zaproszone/wybrane osoby będą miały dostęp do zawartości. Jeżeli dbasz o bezpieczeństwo w swojej firmie, ten aspekt nie pozostanie obojętny.

Te dwa rozwiązania to tylko moje subiektywne propozycje, które warto rozważyć w swoim projekcie lub na potrzeby rekrutacji. Nie są to oczywiście rozwiązania idealne, każde ma jakąś wadę.

Podzielmy sobie to na dwa przykłady – dokumentacja minimalna, czyli taka, która powinna zawsze być w projekcie, a nie wymaga od nas większej ilości czasu. Oraz dokumentacja profesjonalna, czyli taka, nad którą mamy możliwość popracować nieco dłużej. Korzyści z tej drugiej są takie, że zawiera ona więcej informacji biznesowych, które mogą nas inspirować i pomagać przy rozmowach z biznesem (klientem). Jeżeli jednak nie mamy w zespole analityka, taka dokumentacja może zająć więcej czasu – zatem będzie ona droższa w realizacji.

Rzućmy na pierwszy przykład, czyli dokumentację minimalną:

• czytelny spis treści, czyli miejsce z którego bezproblemowo przejdziemy do interesujących nas informacji czy obszarów,
• informacje ogranizacyjne – kiedy i jakie spotkania odbywają się w ramach procesu wytwórczego oraz ich cel. Zdaję sobie sprawę, że terminy są podane w kalendarzu, ale wyobraź sobie kogoś, kto dopiero dołączyć i nie ma jeszcze zaproszenia – dzięki takiej stronie będzie wiedział na co się przygotować i poukłada swoje inne spotkania. Cele daily, planningów czy refinementów również są istotne. Pamiętaj bowiem, że nie zawsze będzie Ci dane pracować z doświadczonymi specjalistami, czasami będą to osoby dopiero raczkujące w IT,
• zespół projektowy – warto rozpisać pełny zespół, który pracuje nad projektem wraz z informacjami kto jest za co odpowiedzialny (DevOps, Frontend Developer itd.). Jest to bardzo pomocne dla wszystkich nowych członków zespołu, gdy nie wiedzą,
• obszary techniczne.

Dokumentacja profesjonalna, czyli ta większa i droższa to rozszerzenie tej pierwszej o następujące elementy:

• zrozumienie biznesu – zastanawiałem się jak ująć tę stronę, więc opiszę jej zawartość, aby nakreślić Ci istotę rzeczy:
  •  cel biznesowy,
  • potrzeba biznesowa,
  • spisane wymagania,
  • słownik terminów,
  • priorytety i inne informacje istotne biznesowo.
    

E-book nie jest jeszcze gotowy, ale na chwilę obecną zawiera 12 stron A4 konkretów (jeszcze przed wystylizowaniem). W e-booku omawiam między innymi:

• czym jest dokumentacja,
• dla kogo ją tworzymy i jak rozróżniamy różne typy dokumentacji,
• parę słów o stylach pisania,
• po co ktoś miałby czytać dokumentację?,
• gdzie tworzyć dokumentację - wraz z dodatkowymi narzędziami - propozycjami, które można rozważyć,
• trzy filary dobrej dokumentacji - fragment można przeczytać wyżej, ale w rozdziale skupiam się również na podejściu metodologicznym do zawartości,
• elementy dobrej dokumentacji - rozszerzam i omawiam w nim punkty, które można przeczytać w tym mailu.

Przede mną jeszcze sporo pracy, ale już teraz możesz kupić preorder tego dokumentu w cenie 50 złotych. Wysyłka nastąpi pod koniec września. Cena po wydaniu będzie wyższa o 20 złotych. 

Jeżeli uda się przekroczyć odpowiedni próg sprzedaży preorderu, pojawi się dodatkowy bonus 😉

E-book przyda się:

• początkującym, by zaskoczyć rekruterów swoją wiedzą i podejściem do tworzenia dokumentacji projektowej,
• doświadczonym, by usprawnić swoje własne projekty o obszar dokumentacji (usprawnić własne dokumenty).
  

Czego tutaj nie znajdziesz? Wszelkich planów, raportów czy scenariuszy testowych - ten temat bardzo mocno omawiam w głównym szkoleniu.

Z kodem "szkolenieqa" zgarniesz 10% zniżki na kursy i konsultacje