Czy pisanie dokumentacji w obecnym kryzysie jest troche strzalem w stope?

Po co pisac dokumentacje, skoro przez to robi sie tylko siebie latwiej zastepowalnym w projekcie? W dobie powszednich zwolnien, ciec budzetu czy nie ma wiecej sensu robienie jedynie prywatnych notatek dla wlasnego uzytku? W ramach ciec budzetu przeciez i tak jest mala szansa, ze kogos nowego zatrudnia do pomocy, a poniewaz wszyscy chca miec sprinty, taski robione na juz, trzeba dowozic - to naturalne, ze czasu na pisanie dokumentacji brakuje. W takim klimacie, jak product owner cisnie, zeby robic funkcjonalnosci i jestem w polowie sprintu i zatrudniaja kogos nowego do pomocy to juz lepiej chyba zrobic z nim pair programming caly dzien, pokazac na przykladzie mojego taska co gdzie i jak, i pokazac mu moj flow niz dbanie przy tym wszystkim, zeby dokumentacja byla aktualna i odzwierciedlala moj flow?

Mamy w pracy takiego goscia, zrobił c**** rozwiazania i nie mozna go zwolnic, i nikomu ich nie tłumaczy nie da sie z nim komunikować. Nie ktorzy menagerowie robili aktywne ruchy sie go pozbyc dlatego ze robi hujowe rozwiazania nic nikomu nic tlumaczy i nie da sie z nim dogadac. Robiono tez ruchy w kierunku anwansu(by sie go pozbyc) ale tego nie mozna zrobic bo ktoś musi utrzymywac jego hujowy kod. Ten kod jest tak hujowy, ze trudnosc jego sprzedaży i utrzymania były jadna z motywacji by przpisac projekty na nowo.

Wiec mozna tak żyć, mozna nawet odnosić sukcesy, ale jak nie masz tak głupiego szcześcia jak on to sie nie to Cie zwolnia w przed biegach. Jak masz to zatrudnia drugi zespół i wyrzuca Cie jak bedzie gotowy. Najlepsza opcją jest chyba ne byc tak upierdliwym gosciem ze kazdy chce Cie zwolnić.

Po pierwsze nikt nie patrzy czy cię łatwo zastąpić, chyba że w 3 osobowym startupie, albo gdy jesteś naprawdę wybitną jednostką. A po drugie dokumentacja i tak jest do d... i nikt z niej nie korzysta a jak już chce się skorzystać to zazwyczaj jest outdated i nic się nie zgadza. To tylko takie żarty że kod bez dokumentacji gwarantuje posadę. Dokumentacja jest zazwyczaj jeszcze gorzej utrzymywana niż komentarze w kodzie. A po trzecie jak nie tworzysz łatwego w utrzymaniu kodu to raczej sprawia że wyglądasz na niekompetentną i łatwo zastępowalną osobę więc efekt byłby odwrotny od zamierzonego.
Najlepsza dokumentacja to git, jira i testy i pisze się sama.

Jak zwykle - to zależy. Od projektu, domeny, poziomu complexity rozwiązania. Mało kto dzisiaj tworzy dokumentacje, bo jeszcze mniej osób chce ją czytać. Jak jesteś one-man-army i tworzysz kluczowy feature / projekt od zera to w wielu przypadkach daje to pewnego rodzaju dupochron, ale nie zawsze. Warto pamiętać, że w korpo nie zawsze kierują się rozsądkiem.

W naszym "januszexie" nigdy nie tworzyliśmy osobnej dokumentacji do kodu.
Natomiast zawsze powstawała dokumentacja na poziomie interfejsów i komunikacji między modułami systemu. Czyli opis tego co wchodzi i co ma wychodzić z poszczególnych modułów. Moduły od zawsze traktujemy jak czarne skrzynki ale nie znaczy to, że mamy tu "radosne pierdoolooloo" bo zwyczajnie dla wygody trzymamy się sprawdzonych wewnętrznych schematów postępowania i ogólnie przyjętych praktyk tworzenia sensownego kodu.
Do tego z rzadka w kodzie pojawiają się komentarze, zwykle w miejscach nieoczywistych lub tam gdzie zastosowano jakieś skróty bądź optymalizacje, których zasady działania na pierwszy rzut oka lub jednego przejścia debugerem nie da się łatwo wywnioskować.

Lata praktyki pokazują, że jest to całkowicie wystarczające. Nawet jeśli ktoś stworzył strasznego bubla nie wartego poświęcania czasu by go poprawiać to i tak da się go dość sprawnie zastąpić nowym... czasem też bublem :-)
Może te zasady nie sprawdzą się przy budowaniu samolotów albo systemów zarządzania światem ale przy większości systemów zamawianych przez naszych klientów to zadziała.

Ogólnie rozdzielanie zadań w projektach ogranicza się do omówienia:

• skąd i w jakim formacie masz brać dane,
• co masz zrobić w nowym module,
• co masz zwracać oraz w jakim formacie / gdzie zapisać,
• termin realizacji zadania.
  Pieczę nad łączeniem klocków zawsze trzyma projektant/analityk/główny programista w jednej osobie taka "święta trójca" co ma na wszystko oko.

Bardziej cierpimy na brak dokumentacji związanej z samą infrastukturą / konfiguracją środowisk, w których pracują całe systemy bo tu kiedyś olaliśmy temat zakładając, że każdy linux == linux a win == win i niestety czasem przy przenoszeniu aplikacji na nowe serwery odbija się to małą czkawką. Nie ma jednak dramatu a od kilku lat całe procesy wdrożenia także wymagają opisu, który zawiera rzeczy nietypowe występujące podczas instalacji/konfiguracji środowiska.

Nigdy nie tworzyliśmy dokumentacji automatycznych bo te w praktyce są warte tyle co ryza zużytego papieru...

W powyższym układzie programista nie musi pisać dokumentacji w ogóle - chyba, że chce to wtedy miło z jego strony.
Nikomu jednak jej brakiem nie strzeli w stopę... Ani sobie ani innym.

Zresztą uważam, że pisanie dokumentacji to nie rola programisty tylko projektanta/analityka a programista ma jedynie zaimplementować wynikającą z niej funkcjonalność i tyle.
Niestety programistę trzeba zawsze prowadzić tak aby był łatwo zastępowalny.

Jeśli będziesz tworzyć dobre rozwiązania, takie które są łatwo utrzymywalne przez każdego, łącznie z testami i dokumentacją; to najpewniej jakość Twojej pracy zostanie zauważona, firma powinna być bardziej skłonna Cię zachować niż zwolnić.

Riddle napisał(a):

Jeśli będziesz tworzyć dobre rozwiązania, takie które są łatwo utrzymywalne przez każdego, łącznie z testami i dokumentacją; to najpewniej jakość Twojej pracy zostanie zauważona, firma powinna być bardziej skłonna Cię zachować niż zwolnić.

Ale to trzeba już być ponadprzeciętnym i jeszcze trzeba mieć nad sobą przełożonych co mają trochę oleju w głowie lub są blisko właścicieli firmy po to by w razie kryzysu ich rekomendacje miały realne przełożenie na możliwość utrzymania firmy przy życiu. W dużych korporacjach z głęboką strukturą to nie będzie miało żadnego znaczenia. Ogólnie w dużych korporacjach jeśli sam nie zadbasz o swoją karierę to to w jaki sposób pracujesz ma niewielkie znaczenie. Przy czym to dbanie o karierę to w 90% tworzenie relacji i znajomości a nie jakość kodu jaki produkujesz. Wyjątek mogą stanowić jedynie wybitne jednostki.

Riddle napisał(a):

Jeśli będziesz tworzyć dobre rozwiązania, takie które są łatwo utrzymywalne przez każdego, łącznie z testami i dokumentacją; to najpewniej jakość Twojej pracy zostanie zauważona, firma powinna być bardziej skłonna Cię zachować niż zwolnić.

Potwierdzam. U nas osoba robiąca wzorową dokumentację jest publicznie chwalona przez tech leada przy kierowniku projektu, który odpowiada m.in. za osiągnięcie celów finansowych projektu, w tym za czas(koszt) poświęcany na rozwiązywanie bugów (dokumentacja skraca naprawę bugów) i zarządzanie finansowaniem kolejnych modyfikacji (dokumentacja skraca czas analizy, ofertowania i ostatecznie realizacji nowej funkcji).

obscurity napisał(a):

Po pierwsze nikt nie patrzy czy cię łatwo zastąpić, chyba że w 3 osobowym startupie, albo gdy jesteś naprawdę wybitną jednostką. A po drugie dokumentacja i tak jest do d... i nikt z niej nie korzysta a jak już chce się skorzystać to zazwyczaj jest outdated i nic się nie zgadza. To tylko takie żarty że kod bez dokumentacji gwarantuje posadę. Dokumentacja jest zazwyczaj jeszcze gorzej utrzymywana niż komentarze w kodzie. A po trzecie jak nie tworzysz łatwego w utrzymaniu kodu to raczej sprawia że wyglądasz na niekompetentną i łatwo zastępowalną osobę więc efekt byłby odwrotny od zamierzonego.
Najlepsza dokumentacja to git, jira i testy i pisze się sama.

Generalnie się zgadzam, ale dokumentacja się przydaje jako wprowadzenie do projektu. Jakieś rysunki łączące komponenty, ogólny opis czym jest apka i chociaż kluczowe funkcjonalności. Takie coś ułatwia wejście w projekt. Można nurkować do kodu od razu i rozkminiać wszystkie zależności, ale zajmie to więcej czasu i energii.

Co do dokumentacji, to ludzie mają skłonność do pisania dokumentacji "per każda metoda w klasie", co może się przydać, jak ktoś już coś ogarnia. Jednak jak ktoś wchodzi do projektu, to taka dokumentacja mu niewiele powie, bo i tak nie będzie wiedział której metody, w której klasie użyć (chyba, że przeczyta opisy dziesiątek metod i klas). Brakuje często dokumentacji w stylu "getting started" czy "how to" (i tu jakieś recepty jak zrobić pewne rzeczy w raz z przykładami, w tutorialowym stylu).

Z drugiej strony niepisanie porządnej dokumentacji faktycznie sprawia, że ktoś jest nie zastąpiony, bo jedyny zna projekt. I nowy programista od razu ma trudniej się wdrożyć (więc stary programista może pokazać "jestem lepszy od tego nowego nowego, który nie zna projektu i nie dowozi tak szybko).

Tylko, że to jest toksyczne zachowanie, które może wrócić do kogoś, jak ktoś pójdzie do nowej pracy i będzie musiał się samemu wdrażać. Ludzie powinni częściej zmieniać pracę, żeby docenić wartość dobrej dokumentacji.

Nawet w czasach mlekiem i miodem płynącym szczegołowa dokumentacja raczej nie miała sensu. Chyba, że firma jest tak bogata i ją stać, albo ma jeleni którzy po godzinach będą siedzieć, pisać i co najważniejsze uaktualniać(to jest największy problem) dokumentacje. Z reguły wystarczą spisane wymagania (tu problem, że product owner albo klient nie wiedzą czego chcą) co ma dany ficzer robić + ewentualnie dokumentacja architektury/algorytmu, Resztę roboty zrobi dobrze napisany kod w którym ktoś myślał o kompozycji.

W przyszłości dokumentacje pewnie będzie generować AI, więc temat i tak jset z d**y.

Co do zastępowalności to nikt nie jest niezastąpiony. Wyjąkiem są seniorzy po 20 lat w wielomilionym projekcie, którzy zatrzymali się na umiejętności pisania jak skończyli studia w czasach c++98. Tak, tacy są realnie nie do ruszenia, bo nikt nie będzie chciał w takim syfie pracować. Poza tym to nie. Sabre kiedyś pokazało, że można seniorów pozwalniać jak nie chce im się uczyć chmur. No i jakoś ta firma istnieje.

lambdadziara napisał(a):

Po co pisac dokumentacje, skoro przez to robi sie tylko siebie latwiej zastepowalnym w projekcie?

To proste - najpierw piszesz dokumentację, później na jej podstawie czat-gpt generuje kod, poprawiasz kod czata i zostawiasz dokumentacje.

Jak cię zwolnią to czekasz aż przyjdą prosić o konsultacje.

W dobie powszednich zwolnien, ciec budzetu...

...jeszcze bardziej istotne jest, by wykonywać dobrą robotę. Jeśli Ci nie płacą wprost za poświęcanie czasu na pisanie szczegółowej dokumentacji to sens tego można kwestionować, ale indywidualnie powinno Ci zależeć by robić wszystko by być postrzeganym jako wydajny pracownik. IMHO dokumentowanie pewnych nieoczywistych fragmentów chociażby poprzez komentarze jak najbardziej się w to wlicza.

lambdadziara napisał(a):

Po co pisac dokumentacje, skoro przez to robi sie tylko siebie latwiej zastepowalnym w projekcie? W dobie powszednich zwolnien, ciec budzetu czy nie ma wiecej sensu robienie jedynie prywatnych notatek dla wlasnego uzytku? W ramach ciec budzetu przeciez i tak jest mala szansa, ze kogos nowego zatrudnia do pomocy, a poniewaz wszyscy chca miec sprinty, taski robione na juz, trzeba dowozic - to naturalne, ze czasu na pisanie dokumentacji brakuje. W takim klimacie, jak product owner cisnie, zeby robic funkcjonalnosci i jestem w polowie sprintu i zatrudniaja kogos nowego do pomocy to juz lepiej chyba zrobic z nim pair programming caly dzien, pokazac na przykladzie mojego taska co gdzie i jak, i pokazac mu moj flow niz dbanie przy tym wszystkim, zeby dokumentacja byla aktualna i odzwierciedlala moj flow?

Ale czemu dokumentacja miałaby odzwierciedlać czyjkolwiek flow?
W zależności od poziomu dokumentacja powinna:

• opisywać komponenty systemu, i to jak się ze sobą komunikują;
• uzasadniać wybór takiej, a nie innej architektury oraz technologii;
• umożliwiać uruchomienie systemu na środowisku lokalnym bez angażowania innych osób.

obscurity napisał(a):

A po drugie dokumentacja i tak jest do d... i nikt z niej nie korzysta a jak już chce się skorzystać to zazwyczaj jest outdated i nic się nie zgadza. To tylko takie żarty że kod bez dokumentacji gwarantuje posadę. Dokumentacja jest zazwyczaj jeszcze gorzej utrzymywana niż komentarze w kodzie.

Współczuję.

lambdadziara napisał(a):

juz lepiej chyba zrobic z nim pair programming caly dzien, pokazac na przykladzie mojego taska co gdzie i jak, i pokazac mu moj flow niz dbanie przy tym wszystkim

jak product owner cisnie

Chciałbym zobaczyć ten pair programming, w którym druga osoba-świeżak nie ma kompletnie zielonego pojęcia o projekcie ani systemie, a ty próbujesz jej pokazać cokolwiek w takim środowisku. Mnie by to bardzo frustrowało, miałbym dziesiątki pytań na temat projektu, systemu, domeny, biznesu, zależności, a ty byś pewnie skakał po plikach które mi nic nie mówią, jak najszybciej żeby tylko product owner był zadowolony.

kelog napisał(a):

Chciałbym zobaczyć ten pair programming, w którym druga osoba-świeżak nie ma kompletnie zielonego pojęcia o projekcie ani systemie, a ty próbujesz jej pokazać cokolwiek w takim środowisku. Mnie by to bardzo frustrowało, miałbym dziesiątki pytań na temat projektu, systemu, domeny, biznesu, zależności, a ty byś pewnie skakał po plikach które mi nic nie mówią, jak najszybciej żeby tylko product owner był zadowolony.

To jest faktycznie problem, i prowadzone PP w taki sposób jest kontr-produktywne. Jeśli senior pracuje ze świeżakiem, to powinien odpowiednio zmniejszyć tępo. Całościowo to i tak jest bardziej opłacalne niż zostawić świeżaka samego.

@lambdadziara tak sobie jeszcze myślę wracając do pierwszgo posta, że zawsze można dodać zapis w umowie, że wypłata będzie dopiero wtedy kiedy zostanie napisana dokuemntacja na tyle prosta i szczegółowa, że umożliwi zastąpienie pracownika w każdej chwilii. No i masz. Wannabe w kryzysie będzie podpisywać takie kontrakty, stanie się to normą i tyle z twojego buntu.