Nauka online jest dobra, ponieważ możesz zadać pytanie i uzyskać szczegółową odpowiedź od spikera na temat, który jest istotny dla bieżącego projektu. W dzisiejszym artykule – odpowiedź Pavla Ustinova, PMO w SOLAR Digital.
Więc co zrobić, jeśli jesteś PM w projekcie, który nie ma dokumentacji technicznej. Kto powinien ustawić zadanie dla jego opisu i co musi się w nim znaleźć?
Jest projekt, ale nie ma dokumentacji: analizujemy przyczyny
Nie zniechęcaj się, jeśli Twój projekt nie ma jeszcze dokumentacji technicznej: nie jesteś pierwszym takim menedżerem a nie ostatnim. Aby zrozumieć, od których artefaktów zacząć, musisz poznać kontekst. Praktyka pokazuje, że możesz mieć jedną z opcji opisanych poniżej.
Projekt dynamicznie się rozwija
Najczęściej mówimy o pierwszych wydaniach projektu. W takim przypadku musisz od razu zrozumieć, że nie będzie możliwe zebranie szczegółowych informacji na temat projektu, ponieważ podczas jego pisania kod zostanie zaktualizowany, a taka dokumentacja stanie się nieaktualna.
Wykonaj podstawowe rzeczy: opisz architekturę, modułową/mikrousługową strukturę aplikacji, schematy interakcji. Być może wymień warstwy i zastanów się dlaczego są potrzebne. Nie ma potrzeby schodzenia do poziomu funkcji i metod.
Projekt się rozwija przez długi czas i jest już dosyć duży
W takim przypadku pisanie szczegółowej dokumentacji będzie pracochłonne, a poza tym nie będzie czasu na jej tworzenie, bo trzeba wprowadzić funkcje do produkcji. Wtedy pomoże Ci opis podstawowych rzeczy: architektura, modułowa budowa aplikacji, schematy interakcji, plus regularne aktualizowanie dokumentacji w strukturze bieżących zadań. W dalszej części projektu poświęć czas nie tylko na rozpracowanie, ale także na tworzenie dokumentów.
Do czego dążyć? Ostatecznie musisz uzyskać przynajmniej średni poziom pogłębienia w sytuację w projekcie.
Zacznij od tych dokumentów:
- opis projektu i jego architektury
- umowy developerskie (jak prowadzimy rozpracowania, jakimi zasadami się kierujemy)
- aktualna dokumentacja API
- opis kodu strony internetowej (phpdoc lub inne, według technologii)
- dokumentacja użytkownika
- opisanie możliwości naszej aplikacji (pełna lista funkcji i do czego służą).
Przykład z Filters i Filter-Port
Filters
Użytkownik powinien umieć filtrować według różnych parametrów i danych w tabeli. Wielokrotny wybór przez jeden filtr powinien działać jak logiczne AND, tj. jeśli użytkownik wybrał Hongkong i Kijów, zaznaczenie pokaże wyniki tylko dla przecięcia warunków, tzn. tabela wyświetli dane tylko dla portu Hongkong i tylko dla portu Kijów.
Filter-Port
Użytkownik może filtrować według portów, może korzystać z wielokrotnego wyboru portów, w samym filtrze jest wyszukiwanie. Lista portów zawiera tylko te porty, które posiadają terminale. Wielokrotny wybór na jednym filtrze powinien działać jak logiczne OR, tj. jeśli użytkownik wybrał Hongkong i Londyn, będą pokazane wyniki dla obu portów. Wybrany port lub kilka portów wyświetlane są w dodatkowej linii jako znaczniki. Użytkownik może usunąć jeden lub wszystkie tagi, w wyniku czego filtrowanie według nich zostanie anulowane.
Projekt źle wykonany pod względem architektury
Jeśli architektura w projekcie jest wykonana źle, to udokumentowanie procesów i architektury projektu może wskazywać na krytyczne niedociągnięcia. Zwykle programiści to rozumieją, ale nie mówią tego, ponieważ boją się refaktoryzacji, problemów z przeglądem wynagrodzeń i tak dalej. Nawet jeśli wszystkie problemy są już w przeszłości, projekt będzie miał miejsca, gdzie lepiej nie zaglądać.
Jeśli wszystko jest źle pod względem architektury na projekcie, wywołuje to szereg problemów, z którymi można sobie poradzić, ale wszystkie te sytuacje w spójności prowadzą do ciągłego pośpiechu i braku zasobów zespołu. Wygląda to tak:
- W projektach, w których architektura jest słabo rozwinięta lub rozpracowanie zostało przeprowadzone niezgodnie z ogólnie przyjętymi standardami kodowania i kanonami zastosowanego frameworka, obsługa jest często niezwykle pracochłonna i trudna.
- Ponieważ wszystko jest robione przez bardzo długi czas, jest presja na zespół, z poleceniem przyspieszenia, co powoduje ciągły pośpiech w zespole
- W takich przypadkach zamiast „zrefaktoryzujmy to”, brzmi to jak „musimy zrobić release”, a zespół kontynuuje zgubną tradycję. Możemy liczyć tylko na to aby sytuacja się nie pogorszyła.
- „Obiecana” refaktoryzacja, na którą czeka cały zespół, jakoś się nie zaczyna, bo „musimy robić feature release” lub po prostu nie ma pieniędzy na produkt owner’a.
- Ponieważ sytuacja jest niekorzystna, pojawia się permanentna obawa, że członkowie zespołu nie dostaną oczekiwanych zmian w wynagrodzeniu, a myśl, że „są tu na zawsze”, jest oczywiście błędna.
A teraz spośród tego wszystkiego pojawia się niczego niepodejrzewający menedżer i naiwnie proponuje wykonanie dokumentacji na temat projektu. To automatycznie powoduje “ból” u członków zespołu, bo i tak nie ma czasu, a tu jeszcze trzeba dokumentację pisać. Oczywiście, opracowanie dokumentacji w takim projekcie potrzebuje sporo czasu, żeby opisać złożone niesystematyczne połączenia, zbyt złożony lub zdezorganizowany kod, przypomnieć wszystkie tymczasowe rozwiązania, które zostały tam zaimplementowane, i jeszcze pomyśleć, jak napisać ten „wstyd” w taki sposób, aby nie było to niekompetentne. Co więcej, w rezultacie ta dokumentacja nadal będzie musiała zostać napisana od nowa, ponieważ wiele rzeczy nadal będzie się zmieniała w ramach refaktoryzacji.
W tym przypadku problem nie polega na tym co dokumentować, a na tym, żeby zacząć poprawiać to, co jest źle napisane pod względem architektury. Najgorsze w tak problematycznym projekcie jest to, że programista nie mówi o problemach w rozwoju, dlatego ważne jest przede wszystkim rozumienie tego, co warto zmienić w architekturze i wtedy dokumentacja będzie pisana szybciej i łatwiej.
Ile potrzebujemy dokumentów i kto ich musi tworzyć
Nie ma jednej odpowiedzi na to pytanie, każda sytuacja jest indywidualna. Są podstawowe rzeczy, które zespół i stakecholderzy chcieliby zobaczyć, ale są też niuanse. Bez zrozumienia, czym jest projekt i z czego on się składa, trudno jest udzielać zaleceń, ale można zrobić to tak:
Architektura
Lepiej Tech Lead lub Chief Technology Officer. Jeżeli ich nie ma, to Lead developer, a jeśli developerzy unikają zadań dokumentacyjnych, to Project Manager, pokazując zespołowi przykład, jak opracować skuteczną dokumentację, nie poświęcając na to zbyt dużo czasu.
Developerzy mogą odmówić robić dokumentację, jeśli:
- nie wierzą, że konieczne jest pisanie dokumentacji i że nie jest to zamiast zamykania zadań, a wręcz przeciwnie, aby rozpracowanie było bardziej logiczne.
- są problemy w projekcie, a zespół obawia się, że będzie musiał przerobić projekt, a następnie przerabiać dokumenty.
Najważniejsze jest odrzucenie faktu, że „napisanie dokumentacji zajmuje bardzo dużo czasu, szkoda czasu, a przecież i tak wszystko jest jasne”. W każdym razie należy opisać z czego się składa aplikacja (moduły/mikroserwisy), praca z bazą danych, plikami, w jaki sposób dane są przesyłane do front-endu.
Ogólne warunki pracy
Określić ogólne warunki (Developers Agreement), jaki style guide, jak używać zmienne (variables), funkcje (functions / classes methods), jaki code linting (jeżeli on jest), jakie podejście stosuje się do organizacji kodu (SOLID), jak pracują funkcje (functions interacting). Nie powinno być wątpliwości, że wszystko będzie tak samo, choć w praktyce nie zawsze tak jest.
Inna podstawowa dokumentacja:
- Stos technologiczny.
- Instrukcja instalacji środowiska: local environment and server environment.
- Opis działania CI/CD, jeżeli istnieje i jeśli jest to możliwe, jego ustawienia (setup). Określić, które skrypty co robią.
- Integracje zewnętrzne: czym są, jak działają. Dołącz linki do dokumentacji API.
- Można podłączyć automatyczny dokumentator kodu, aby komentarze w kodzie same generowały dokumentację. W przypadku podłączenia, wyjaśnij zespołowi, że nie jest konieczne szczegółowe opisywanie każdej funkcji (metody).
- Struktura bazy danych (automatycznie pobierana z WebStorm) lub po prostu lista tabel i dlaczego są potrzebne.
- Jeśli istnieją unit testy, wymień je.
- API Doc, w przypadku korzystania z API. API Doc powinien być szczegółowy, opisujący metody API,parametry i struktury odpowiedzi wraz z typami danych.
Reszta zależy od gustu i potrzeb, na przykład:
- Instrukcje dla użytkownika.
- Test-cases, które wymieniają wszystko, co jest testowane.
- Opis funkcjonalności aplikacji.
Wtedy będziesz miał dobry opis tego, co robi Twoja aplikacja, i zawsze możesz do niego wrócić, aby zrozumieć, co musi się tam znaleźć. Najlepiej pisze to QA.
Ważna uwaga: nie straszcie kolegów, którym powierzyliście dokumentację, że zamiast pracować będą tylko pisać dokumentację. To całkowicie zablokuje ich świadomość, a dostosowanie tego procesu będzie bolesne lub nawet niemożliwe.
Jeśli uda Ci się to zrobić, to będziesz w stanie tworzyć dobrą, zrozumiałą dokumentację bez chaosu w zadaniach. A jeśli potrzebujesz wiedzy systemowej z zakresu technologii developerskich, CI/CD oraz umiejętności komunikacji z zespołem technicznym, przyjdź na kurs TechMind 😉