Dokumentacja to ciężka sprawa

Tym razem luźny wpis o tym jak idzie mi zabieranie się za dokumentowanie systemu.

Rozwijasz projekt, wprowadzasz kolejne niesamowite funkcjonalności, wszystko robi się coraz bardziej rozbudowane i w pewnym momencie albo sam postanawiasz (rzadszy przypadek ;) ), albo ktoś z zespołu/szef Ci każde zacząć pisać dokumentację do projektu. Ja właśnie znalazłem się w takiej sytuacji. Projekt w pracy urósł, stał się „dojrzałym” narzędziem i przyszła pora aby przygotować go dla ewentualnych przyszłych współpracowników, ponieważ do tej pory w dużej mierze pracowałem przy nim sam. I takim przygotowaniem, poza delikatnym wyczyszczeniem kodu stało się też napisanie dokumentacji. Nie uważam, że taki dokument jest czymś złym, i tylko zabiera czas podczas jego pisania, nawet byłem i nadal jestem pozytywnie nastawiony do tego pomysłu, w końcu możliwość uporządkowania  tego co się dzieje „pod maską” zawsze poprawia komfort pracy.  Jednak już przy próbie napisania pierwszej linijki powstał problem – co pisać? Niby znam system na pamięć, niby wiem co z czym i dlaczego, ale jednak nie potrafię w żaden sposób zacząć tego opisywać! Gdyby zapytać kogoś co powinno być w dokumentacji pewnie odpowiedział by ogólnie, że to co jest istotne dla zespołu. Tylko co w takim razie jest istotne? A nawet jeśli wiem jaki fragment całości opisywać to powstaje pytanie które etapy wybranego procesu opisywać? Jak dokładnie? Czy założyć, że coś powinno być oczywiste dla każdego kto przyjdzie pracować nad projektem, czy opisywać tak jakby miał przy tym pracować ktoś kto przeczytał „Podstawy programowania w weekend”?

Co prawda trochę podkoloryzowałem problem, ale nie tak bardzo jakby mogło się wydawać ;) Mówią, że dobry programista potrafi pisać dobrą dokumentację. Z tego wynika, że jeszcze daleko mi do bycia dobry programistą :D Ale nigdy za takiego się nie uważałem więc wszystko by się zgadzało. Myślę, że głównym problemem jest tutaj samodzielna praca nad kodem i dobra znajomość całości. Przez to nie potrafię obiektywnie stwierdzić czy użycie czegoś jest problematyczne – w końcu sam to tworzyłem więc wiem jak się zachowa. W takich momentach wychodzi jak dużo, albo raczej mało pracowałem przy projektach grupowych, tworzonych przez co najmniej 2-3 osoby. Bo jeśli najczęściej siedzisz nad kodem sam to właśnie tak jak w moim przypadku nie potrafisz ocenić czy napisany przez Ciebie fragment wymaga uwzględniania w dokumentacji, a jeśli tak to jak obszernego. Również samo doświadczenie w pracy przy większych projektach daje dużo lepsze rozeznanie w tym co warto opisywać. W końcu jeśli Twoja aplikacja powstaje pół roku czy rok to do zabawy dołącza problem pamiętania co jak działało ;)

Dlatego podsumowaniem tego wpisu i moim osobistym przemyśleniem jest to, że żeby nauczyć się pisać dokumentację trzeba albo mieć wrodzony talent, albo najpierw nauczyć się pracować z cudzym i/lub starszym kodem. Nabrane doświadczenie pozwoli Ci łatwiej ocenić jakie elementy warto opisywać aby ułatwić sobie i innym późniejszą pracę.

Ja tym czasem wracam do próby pisania dokumentacji…